Improve documentation on Specialized*Pipeline*.
#19494
Conversation
andriyDev
added
C-Docs
| @@ -18,11 +18,29 @@ use core::{fmt::Debug, hash::Hash}; | |||
| use thiserror::Error; | |||
| use tracing::error; | |||
|
|
|||
| /// A trait that allows constructing different variants of a render pipeline from a key. | |||
| /// | |||
| /// Note: If your key is a ZST, you do not need to "specialize" anything. Just create the render | |||
There was a problem hiding this comment.
I don't really get what this note is saying 🤔
There was a problem hiding this comment.
The only reason to specialize a pipeline is if your key contains some information that results in different versions of the render pipeline. If your key is a zero-sized type (ZST), there is no reason to use this (since all your render pipelines would just be the same). It is simpler and easier to just use the PipelineCache directly to create the render pipeline.
Is there anything I can adjust to make this clearer? Not sure where the confusion is (perhaps ZST was confusing?)
There was a problem hiding this comment.
Also please correct me if I'm missing something here! This is my understanding based on just investigating the code.
There was a problem hiding this comment.
I would maybe just rephrase it to say that specialization is intended to modify the pipeline descriptor and cached on the basis of the key. The relevant scenario here would be if someone was using AsBindGroup derive without the #[bind_group_data] attr, then you don't need to specialize.
There was a problem hiding this comment.
Thanks, I've reworded it to match what you've said!
Objective
Solution
specialize_pipelineargument topipeline_specializerto clarify this is more like a factory than a render pipeline.Technically making
VertexLayoutCacheprivate is a breaking change, but it seems highly unlikely that anyone is using this (since it's just a hashmap alias. I don't think this needs a migration guide.