Consider moving the pipeline barrier explanation closer to where the parameters are set
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_OPTIMALandTRANSFER_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
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from KhronosGroup/Vulkan-Tutorial
-
Difficulty 1/5 Under an hour Newbie friendliness 85/100
KhronosGroup/Vulkan-Tutorial#545 ·
Maintainers usually reply within 1 day
-
Difficulty 1/5 1-3 hours Newbie friendliness 76/100
KhronosGroup/Vulkan-Tutorial#544 ·
Maintainers usually reply within 1 day
-
Clarify front-face culling when using a negative viewport heightPossibly taken @1sgtpepper claimed this 18 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
KhronosGroup/Vulkan-Tutorial#534 ·
Maintainers usually reply within 1 day
-
Stale GLSL-specific wording in the Vertex Input Description chapterPossibly taken @gpx1000 claimed this 27 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
KhronosGroup/Vulkan-Tutorial#528 · 1 assignee ·
Maintainers usually reply within 1 day
-
Clarify vertex input bindingsPossibly taken @SaschaWillems claimed this 27 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
KhronosGroup/Vulkan-Tutorial#527 · 1 assignee ·
Maintainers usually reply within 1 day
All issues in KhronosGroup/Vulkan-Tutorial
Similar issues
-
Documentation: Fix parameter markup, legacy branch link, and phrasing in Detachable Joints and Model Command tutorialsPossibly taken @patelshivani2283-lab claimed this today. Open
Difficulty 1/5 1-3 hours Newbie friendliness 88/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
Maintainers usually reply within 1 day
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Niko1221/Strata#6071 · 2 comments ·
Maintainers usually reply within 4 days
-
pumpOpen
Difficulty 1/5 Under an hour Newbie friendliness 68/100
dewenni/ESP_Buderus_KM271#191 ·