README: Remove deprecated builder() snippets and guidelines
#743
Conversation
MarijnS95
force-pushed
the
readme-no-builder
branch
from
1df8d1d to
dbc001e
Compare
README.md
Outdated
| Pointer chains in builders differ from raw Vulkan. Instead of chaining every struct manually, you instead use `.push_next` on the struct that you are going to pass into the function. Those structs then get *prepended* into the chain. | ||
|
|
||
| `push_next` is also type checked, you can only add valid structs to the chain. Both the structs and the builders can be passed into `push_next`. Only builders for structs that can be passed into functions will implement a `push_next`. | ||
| Pointer chains in Ash differ from raw Vulkan. Instead of chaining every struct manually, you instead use `.push_next()` on the struct that you are going to pass into the function. Those structs then get _prepended_ into the chain. |
There was a problem hiding this comment.
Nit: I don't think "Pointer chains in Ash differ from raw Vulkan" is the right wording, but it was already there. They are still the same pointer chains, it's just that our .push_next() helper function has a specific way to ".insert(1)" rather than .append() to be simple and efficient (no need to walk to the end of the chain, though we do need to do that for the struct that is being appended, but the common case is that it's just one item).
At the same time the spec says that specific pNext ordering is allowed (but strongly discouraged) if drivers/extensions absolutely need it for deterministic behaviour.
There was a problem hiding this comment.
I agree this wording could be improved, both for clarity and concision. Perhaps:
Ash provides helpers for assembling pointer chains. Use
.push_next()on the struct ...
There was a problem hiding this comment.
Updated and reordered. Left out the "refer to the push_next() documentation for more detailed insertion order" or something along those lines.
Note that our fn push_next() docs don't cover the case where a hypothetical D->E chain is appended to an A->B->C chain, which will end up looking like A->D->E->B->C.
MarijnS95
force-pushed
the
readme-no-builder
branch
from
dbc001e to
93d14ed
Compare
#602 introduced builder functions directly on the raw Vulkan struct types by using lifetime borrows which are FFI compatible (ABI is identical) wuth raw pointers, simplifying the whole system and protecting the user against losing lifetimes upon calling `.build()`. However, this change wasn't propagated through to the `README` so the code snippets were still showcasing removed `::builder()` and `.build()` functions and documenting "the `.build()` footgun" which doesn't even exist anymore 🎉
MarijnS95
force-pushed
the
readme-no-builder
branch
from
93d14ed to
9c8d46d
Compare
Fixes #742
#602 introduced builder functions directly on the raw Vulkan struct types by using lifetime borrows which are FFI compatible (ABI is identical) wuth raw pointers, simplifying the whole system and protecting the user against losing lifetimes upon calling
.build(). However, this change wasn't propagated through to theREADMEso the code snippets were still showcasing removed::builder()and.build()functions and documenting "the.build()footgun" which doesn't even exist anymore 🎉