@@ -18,11 +18,35 @@ use core::{fmt::Debug, hash::Hash};
18
18
use thiserror:: Error ;
19
19
use tracing:: error;
20
20
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.
21
30
pub trait SpecializedRenderPipeline {
31
+ /// The key that defines each "variant" of the render pipeline.
22
32
type Key : Clone + Hash + PartialEq + Eq ;
33
+
34
+ /// Construct a new render pipeline based on the provided key.
23
35
fn specialize ( & self , key : Self :: Key ) -> RenderPipelineDescriptor ;
24
36
}
25
37
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.
26
50
#[ derive( Resource ) ]
27
51
pub struct SpecializedRenderPipelines < S : SpecializedRenderPipeline > {
28
52
cache : HashMap < S :: Key , CachedRenderPipelineId > ,
@@ -35,24 +59,49 @@ impl<S: SpecializedRenderPipeline> Default for SpecializedRenderPipelines<S> {
35
59
}
36
60
37
61
impl < S : SpecializedRenderPipeline > SpecializedRenderPipelines < S > {
62
+ /// Get or create a specialized instance of the pipeline corresponding to `key`.
38
63
pub fn specialize (
39
64
& mut self ,
40
65
cache : & PipelineCache ,
41
- specialize_pipeline : & S ,
66
+ pipeline_specializer : & S ,
42
67
key : S :: Key ,
43
68
) -> CachedRenderPipelineId {
44
69
* self . cache . entry ( key. clone ( ) ) . or_insert_with ( || {
45
- let descriptor = specialize_pipeline . specialize ( key) ;
70
+ let descriptor = pipeline_specializer . specialize ( key) ;
46
71
cache. queue_render_pipeline ( descriptor)
47
72
} )
48
73
}
49
74
}
50
75
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.
51
85
pub trait SpecializedComputePipeline {
86
+ /// The key that defines each "variant" of the compute pipeline.
52
87
type Key : Clone + Hash + PartialEq + Eq ;
88
+
89
+ /// Construct a new compute pipeline based on the provided key.
53
90
fn specialize ( & self , key : Self :: Key ) -> ComputePipelineDescriptor ;
54
91
}
55
92
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.
56
105
#[ derive( Resource ) ]
57
106
pub struct SpecializedComputePipelines < S : SpecializedComputePipeline > {
58
107
cache : HashMap < S :: Key , CachedComputePipelineId > ,
@@ -65,6 +114,7 @@ impl<S: SpecializedComputePipeline> Default for SpecializedComputePipelines<S> {
65
114
}
66
115
67
116
impl < S : SpecializedComputePipeline > SpecializedComputePipelines < S > {
117
+ /// Get or create a specialized instance of the pipeline corresponding to `key`.
68
118
pub fn specialize (
69
119
& mut self ,
70
120
cache : & PipelineCache ,
@@ -78,22 +128,34 @@ impl<S: SpecializedComputePipeline> SpecializedComputePipelines<S> {
78
128
}
79
129
}
80
130
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.
81
135
pub trait SpecializedMeshPipeline {
136
+ /// The key that defines each "variant" of the render pipeline.
82
137
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`.
83
143
fn specialize (
84
144
& self ,
85
145
key : Self :: Key ,
86
146
layout : & MeshVertexBufferLayoutRef ,
87
147
) -> Result < RenderPipelineDescriptor , SpecializedMeshPipelineError > ;
88
148
}
89
149
150
+ /// A cache of different variants of a render pipeline based on a key and the particular mesh's
151
+ /// vertex buffer layout.
90
152
#[ derive( Resource ) ]
91
153
pub struct SpecializedMeshPipelines < S : SpecializedMeshPipeline > {
92
154
mesh_layout_cache : HashMap < ( MeshVertexBufferLayoutRef , S :: Key ) , CachedRenderPipelineId > ,
93
155
vertex_layout_cache : VertexLayoutCache < S > ,
94
156
}
95
157
96
- pub type VertexLayoutCache < S > = HashMap <
158
+ type VertexLayoutCache < S > = HashMap <
97
159
VertexBufferLayout ,
98
160
HashMap < <S as SpecializedMeshPipeline >:: Key , CachedRenderPipelineId > ,
99
161
> ;
@@ -108,11 +170,13 @@ impl<S: SpecializedMeshPipeline> Default for SpecializedMeshPipelines<S> {
108
170
}
109
171
110
172
impl < S : SpecializedMeshPipeline > SpecializedMeshPipelines < S > {
173
+ /// Construct a new render pipeline based on the provided key and the mesh's vertex buffer
174
+ /// layout.
111
175
#[ inline]
112
176
pub fn specialize (
113
177
& mut self ,
114
178
cache : & PipelineCache ,
115
- specialize_pipeline : & S ,
179
+ pipeline_specializer : & S ,
116
180
key : S :: Key ,
117
181
layout : & MeshVertexBufferLayoutRef ,
118
182
) -> Result < CachedRenderPipelineId , SpecializedMeshPipelineError > {
@@ -121,7 +185,7 @@ impl<S: SpecializedMeshPipeline> SpecializedMeshPipelines<S> {
121
185
Entry :: Vacant ( entry) => specialize_slow (
122
186
& mut self . vertex_layout_cache ,
123
187
cache,
124
- specialize_pipeline ,
188
+ pipeline_specializer ,
125
189
key,
126
190
layout,
127
191
entry,
0 commit comments