Consider moving the pipeline barrier explanation closer to where the parameters are set

Open Beginner friendly
#551 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
72/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
cpp
Domain
documentation

Research direction

Read the Layout transitions and Transition barrier masks sections in the linked tutorial page, then compare where pipelineBarrier() parameters are explained with where their masks are set. Move or condense the explanation as proposed so readers encounter the details alongside their use; done when the earlier section briefly notes that masks come later and the detailed explanation appears in Transition barrier masks.

Written by the indexing model from the issue text.

Description

In the Layout transitions section, the tutorial says:

The right values depend on the old and new layout, so we’ll get back to this once we’ve figured out which transitions we’re going to use.

However, the tutorial then spends several paragraphs explaining the parameters of pipelineBarrier(), including pipeline stages, access types, eByRegion, and different types of memory barriers. The actual stage and access masks are not set until the later Transition barrier masks section.

I found this order a bit confusing for a few reasons:

  • The tutorial tells readers that these parameters will be handled later, but immediately goes into a fairly detailed explanation of them.
  • The two layout transitions (UNDEFINED → TRANSFER_DST_OPTIMAL and TRANSFER_DST_OPTIMAL → SHADER_READ_ONLY_OPTIMAL) have already been introduced at this point, so the reason given for postponing the parameters is also a little unclear.
  • By the time the parameters are actually set, the reader has already moved through several other topics.

I think it would be easier to follow if the earlier section briefly mentioned that the stage and access masks would be filled in later, and left the detailed explanation for the Transition barrier masks section, where readers can immediately see how those parameters are used.

I don't think leaving the implementation incomplete is a problem by itself. It's mainly the placement of the explanation that makes the section harder to follow.

Dominant language
C++
Stars
444
Forks
145
PR merge metrics
No merged PRs in 30d

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from KhronosGroup/Vulkan-Tutorial

All issues in KhronosGroup/Vulkan-Tutorial

Similar issues

More C++ issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.