Skip to content

Commit 2ddd884

Browse files
authored
Improve documentation on Specialized*Pipeline*. (#19494)
# Objective - Title. ## Solution - Add an explanation of the various traits and structs. - Make VertexLayoutCache private - this type is not used anywhere, and it's just a type alias for a HashMap with no other utility functions. - Rename `specialize_pipeline` argument to `pipeline_specializer` to clarify this is more like a factory than a render pipeline. Technically making `VertexLayoutCache` private 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.
1 parent 1b6e3f5 commit 2ddd884

File tree

1 file changed

+69
-5
lines changed

1 file changed

+69
-5
lines changed

crates/bevy_render/src/render_resource/pipeline_specializer.rs

Lines changed: 69 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -18,11 +18,35 @@ use core::{fmt::Debug, hash::Hash};
1818
use thiserror::Error;
1919
use tracing::error;
2020

21+
/// A trait that allows constructing different variants of a render pipeline from a key.
22+
///
23+
/// Note: This is intended for modifying your pipeline descriptor on the basis of a key. If your key
24+
/// contains no data then you don't need to specialize. For example, if you are using the
25+
/// [`AsBindGroup`](crate::render_resource::AsBindGroup) without the `#[bind_group_data]` attribute,
26+
/// you don't need to specialize. Instead, create the pipeline directly from [`PipelineCache`] and
27+
/// store its ID.
28+
///
29+
/// See [`SpecializedRenderPipelines`] for more info.
2130
pub trait SpecializedRenderPipeline {
31+
/// The key that defines each "variant" of the render pipeline.
2232
type Key: Clone + Hash + PartialEq + Eq;
33+
34+
/// Construct a new render pipeline based on the provided key.
2335
fn specialize(&self, key: Self::Key) -> RenderPipelineDescriptor;
2436
}
2537

38+
/// A convenience cache for creating different variants of a render pipeline based on some key.
39+
///
40+
/// Some render pipelines may need to be configured differently depending on the exact situation.
41+
/// This cache allows constructing different render pipelines for each situation based on a key,
42+
/// making it easy to A) construct the necessary pipelines, and B) reuse already constructed
43+
/// pipelines.
44+
///
45+
/// Note: This is intended for modifying your pipeline descriptor on the basis of a key. If your key
46+
/// contains no data then you don't need to specialize. For example, if you are using the
47+
/// [`AsBindGroup`](crate::render_resource::AsBindGroup) without the `#[bind_group_data]` attribute,
48+
/// you don't need to specialize. Instead, create the pipeline directly from [`PipelineCache`] and
49+
/// store its ID.
2650
#[derive(Resource)]
2751
pub struct SpecializedRenderPipelines<S: SpecializedRenderPipeline> {
2852
cache: HashMap<S::Key, CachedRenderPipelineId>,
@@ -35,24 +59,49 @@ impl<S: SpecializedRenderPipeline> Default for SpecializedRenderPipelines<S> {
3559
}
3660

3761
impl<S: SpecializedRenderPipeline> SpecializedRenderPipelines<S> {
62+
/// Get or create a specialized instance of the pipeline corresponding to `key`.
3863
pub fn specialize(
3964
&mut self,
4065
cache: &PipelineCache,
41-
specialize_pipeline: &S,
66+
pipeline_specializer: &S,
4267
key: S::Key,
4368
) -> CachedRenderPipelineId {
4469
*self.cache.entry(key.clone()).or_insert_with(|| {
45-
let descriptor = specialize_pipeline.specialize(key);
70+
let descriptor = pipeline_specializer.specialize(key);
4671
cache.queue_render_pipeline(descriptor)
4772
})
4873
}
4974
}
5075

76+
/// A trait that allows constructing different variants of a compute pipeline from a key.
77+
///
78+
/// Note: This is intended for modifying your pipeline descriptor on the basis of a key. If your key
79+
/// contains no data then you don't need to specialize. For example, if you are using the
80+
/// [`AsBindGroup`](crate::render_resource::AsBindGroup) without the `#[bind_group_data]` attribute,
81+
/// you don't need to specialize. Instead, create the pipeline directly from [`PipelineCache`] and
82+
/// store its ID.
83+
///
84+
/// See [`SpecializedComputePipelines`] for more info.
5185
pub trait SpecializedComputePipeline {
86+
/// The key that defines each "variant" of the compute pipeline.
5287
type Key: Clone + Hash + PartialEq + Eq;
88+
89+
/// Construct a new compute pipeline based on the provided key.
5390
fn specialize(&self, key: Self::Key) -> ComputePipelineDescriptor;
5491
}
5592

93+
/// A convenience cache for creating different variants of a compute pipeline based on some key.
94+
///
95+
/// Some compute pipelines may need to be configured differently depending on the exact situation.
96+
/// This cache allows constructing different compute pipelines for each situation based on a key,
97+
/// making it easy to A) construct the necessary pipelines, and B) reuse already constructed
98+
/// pipelines.
99+
///
100+
/// Note: This is intended for modifying your pipeline descriptor on the basis of a key. If your key
101+
/// contains no data then you don't need to specialize. For example, if you are using the
102+
/// [`AsBindGroup`](crate::render_resource::AsBindGroup) without the `#[bind_group_data]` attribute,
103+
/// you don't need to specialize. Instead, create the pipeline directly from [`PipelineCache`] and
104+
/// store its ID.
56105
#[derive(Resource)]
57106
pub struct SpecializedComputePipelines<S: SpecializedComputePipeline> {
58107
cache: HashMap<S::Key, CachedComputePipelineId>,
@@ -65,6 +114,7 @@ impl<S: SpecializedComputePipeline> Default for SpecializedComputePipelines<S> {
65114
}
66115

67116
impl<S: SpecializedComputePipeline> SpecializedComputePipelines<S> {
117+
/// Get or create a specialized instance of the pipeline corresponding to `key`.
68118
pub fn specialize(
69119
&mut self,
70120
cache: &PipelineCache,
@@ -78,22 +128,34 @@ impl<S: SpecializedComputePipeline> SpecializedComputePipelines<S> {
78128
}
79129
}
80130

131+
/// A trait that allows constructing different variants of a render pipeline from a key and the
132+
/// particular mesh's vertex buffer layout.
133+
///
134+
/// See [`SpecializedMeshPipelines`] for more info.
81135
pub trait SpecializedMeshPipeline {
136+
/// The key that defines each "variant" of the render pipeline.
82137
type Key: Clone + Hash + PartialEq + Eq;
138+
139+
/// Construct a new render pipeline based on the provided key and vertex layout.
140+
///
141+
/// The returned pipeline descriptor should have a single vertex buffer, which is derived from
142+
/// `layout`.
83143
fn specialize(
84144
&self,
85145
key: Self::Key,
86146
layout: &MeshVertexBufferLayoutRef,
87147
) -> Result<RenderPipelineDescriptor, SpecializedMeshPipelineError>;
88148
}
89149

150+
/// A cache of different variants of a render pipeline based on a key and the particular mesh's
151+
/// vertex buffer layout.
90152
#[derive(Resource)]
91153
pub struct SpecializedMeshPipelines<S: SpecializedMeshPipeline> {
92154
mesh_layout_cache: HashMap<(MeshVertexBufferLayoutRef, S::Key), CachedRenderPipelineId>,
93155
vertex_layout_cache: VertexLayoutCache<S>,
94156
}
95157

96-
pub type VertexLayoutCache<S> = HashMap<
158+
type VertexLayoutCache<S> = HashMap<
97159
VertexBufferLayout,
98160
HashMap<<S as SpecializedMeshPipeline>::Key, CachedRenderPipelineId>,
99161
>;
@@ -108,11 +170,13 @@ impl<S: SpecializedMeshPipeline> Default for SpecializedMeshPipelines<S> {
108170
}
109171

110172
impl<S: SpecializedMeshPipeline> SpecializedMeshPipelines<S> {
173+
/// Construct a new render pipeline based on the provided key and the mesh's vertex buffer
174+
/// layout.
111175
#[inline]
112176
pub fn specialize(
113177
&mut self,
114178
cache: &PipelineCache,
115-
specialize_pipeline: &S,
179+
pipeline_specializer: &S,
116180
key: S::Key,
117181
layout: &MeshVertexBufferLayoutRef,
118182
) -> Result<CachedRenderPipelineId, SpecializedMeshPipelineError> {
@@ -121,7 +185,7 @@ impl<S: SpecializedMeshPipeline> SpecializedMeshPipelines<S> {
121185
Entry::Vacant(entry) => specialize_slow(
122186
&mut self.vertex_layout_cache,
123187
cache,
124-
specialize_pipeline,
188+
pipeline_specializer,
125189
key,
126190
layout,
127191
entry,

0 commit comments

Comments
 (0)