primUtils.h
1 //
2 // Copyright 2019 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_HD_ST_PRIM_UTILS_H
25 #define PXR_IMAGING_HD_ST_PRIM_UTILS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hdSt/api.h"
29 #include "pxr/imaging/hdSt/resourceRegistry.h"
30 #include "pxr/imaging/hd/sceneDelegate.h"
31 #include "pxr/imaging/hd/rprim.h"
32 
33 #include <memory>
34 #include <string>
35 #include <vector>
36 
37 PXR_NAMESPACE_OPEN_SCOPE
38 
39 class HdChangeTracker;
40 class HdDrawItem;
41 class HdRenderIndex;
42 class HdRenderParam;
43 class HdRprim;
44 struct HdRprimSharedData;
45 class HdStDrawItem;
46 class HdStInstancer;
47 
48 using HdBufferArrayRangeSharedPtr = std::shared_ptr<class HdBufferArrayRange>;
49 
50 using HdBufferSourceSharedPtrVector = std::vector<HdBufferSourceSharedPtr>;
51 using HdBufferSpecVector = std::vector<struct HdBufferSpec>;
52 using HdSt_MaterialNetworkShaderSharedPtr =
53  std::shared_ptr<class HdSt_MaterialNetworkShader>;
54 
55 using HdComputationSharedPtr = std::shared_ptr<class HdComputation>;
56 
57 using HdStResourceRegistrySharedPtr =
58  std::shared_ptr<HdStResourceRegistry>;
59 
60 // -----------------------------------------------------------------------------
61 // Draw invalidation and garbage collection utilities
62 // -----------------------------------------------------------------------------
63 HDST_API
64 void HdStMarkDrawBatchesDirty(HdRenderParam *renderParam);
65 
66 HDST_API
67 void HdStMarkMaterialTagsDirty(HdRenderParam *renderParam);
68 
69 HDST_API
70 void HdStMarkGeomSubsetDrawItemsDirty(HdRenderParam *renderParam);
71 
72 HDST_API
73 void HdStMarkGarbageCollectionNeeded(HdRenderParam *renderParam);
74 
75 // -----------------------------------------------------------------------------
76 // Primvar descriptor filtering utilities
77 // -----------------------------------------------------------------------------
78 // Get filtered primvar descriptors for drawItem
79 HDST_API
80 HdPrimvarDescriptorVector
81 HdStGetPrimvarDescriptors(
82  HdRprim const * prim,
83  HdStDrawItem const * drawItem,
84  HdSceneDelegate * delegate,
85  HdInterpolation interpolation,
86  const HdReprSharedPtr &repr = nullptr,
87  HdMeshGeomStyle descGeomStyle = HdMeshGeomStyleInvalid,
88  int geomSubsetDescIndex = 0,
89  size_t numGeomSubsets = 0);
90 
91 // Get filtered instancer primvar descriptors for drawItem
92 HDST_API
93 HdPrimvarDescriptorVector
94 HdStGetInstancerPrimvarDescriptors(
95  HdStInstancer const * instancer,
96  HdSceneDelegate * delegate);
97 
98 // -----------------------------------------------------------------------------
99 // Tracking render tag changes
100 // -----------------------------------------------------------------------------
101 
102 HDST_API
103 void HdStUpdateRenderTag(HdSceneDelegate *delegate,
104  HdRenderParam *renderParam,
105  HdRprim *rprim);
106 
107 // -----------------------------------------------------------------------------
108 // Material processing utilities
109 // -----------------------------------------------------------------------------
110 HDST_API
111 void HdStSetMaterialId(HdSceneDelegate *delegate,
112  HdRenderParam *renderParam,
113  HdRprim *rprim);
114 
115 HDST_API
116 void HdStSetMaterialTag(HdRenderParam *renderParam,
117  HdDrawItem *drawItem,
118  const TfToken &materialTag);
119 
120 HDST_API
121 void HdStSetMaterialTag(HdSceneDelegate *delegate,
122  HdRenderParam *renderParam,
123  HdDrawItem *drawItem,
124  SdfPath const & materialId,
125  bool hasDisplayOpacityPrimvar,
126  bool occludedSelectionShowsThrough);
127 // Resolves the material network shader for the given prim (using a fallback
128 // material as necessary).
129 HDST_API
130 HdSt_MaterialNetworkShaderSharedPtr
131 HdStGetMaterialNetworkShader(
132  HdRprim const * prim,
133  HdSceneDelegate * delegate);
134 
135 HDST_API
136 HdSt_MaterialNetworkShaderSharedPtr
137 HdStGetMaterialNetworkShader(
138  HdRprim const * prim,
139  HdSceneDelegate * delegate,
140  SdfPath const & materialId);
141 
142 // -----------------------------------------------------------------------------
143 // Primvar processing and BAR allocation utilities
144 // -----------------------------------------------------------------------------
145 // Returns true if range is non-empty and valid.
146 HDST_API
147 bool HdStIsValidBAR(HdBufferArrayRangeSharedPtr const& range);
148 
149 // Returns true if curRange can be used as-is (even if it's empty) during
150 // primvar processing.
151 HDST_API
152 bool HdStCanSkipBARAllocationOrUpdate(
153  HdBufferSourceSharedPtrVector const& sources,
154  HdStComputationSharedPtrVector const& computations,
155  HdBufferArrayRangeSharedPtr const& curRange,
156  HdDirtyBits dirtyBits);
157 
158 HDST_API
159 bool HdStCanSkipBARAllocationOrUpdate(
160  HdBufferSourceSharedPtrVector const& sources,
161  HdBufferArrayRangeSharedPtr const& curRange,
162  HdDirtyBits dirtyBits);
163 
164 // Returns the buffer specs that have been removed from curRange based on the
165 // new primvar descriptors and internally generated primvar names.
166 //
167 // Internally generated primvar names will never be among the specs returned,
168 HDST_API
169 HdBufferSpecVector
170 HdStGetRemovedPrimvarBufferSpecs(
171  HdBufferArrayRangeSharedPtr const& curRange,
172  HdPrimvarDescriptorVector const& newPrimvarDescs,
173  HdExtComputationPrimvarDescriptorVector const& newCompPrimvarDescs,
174  TfTokenVector const& internallyGeneratedPrimvarNames,
175  SdfPath const& rprimId);
176 
177 HDST_API
178 HdBufferSpecVector
179 HdStGetRemovedPrimvarBufferSpecs(
180  HdBufferArrayRangeSharedPtr const& curRange,
181  HdPrimvarDescriptorVector const& newPrimvarDescs,
182  TfTokenVector const& internallyGeneratedPrimvarNames,
183  SdfPath const& rprimId);
184 
185 // Updates the existing range at drawCoordIndex with newRange and flags garbage
186 // collection (for the existing range) and rebuild of all draw batches when
187 // necessary.
188 HDST_API
189 void HdStUpdateDrawItemBAR(
190  HdBufferArrayRangeSharedPtr const& newRange,
191  int drawCoordIndex,
192  HdRprimSharedData *sharedData,
193  HdRenderParam *renderParam,
194  HdChangeTracker *changeTracker);
195 
196 // Returns true if primvar with primvarName exists within primvar descriptor
197 // vector primvars and primvar has a valid value
198 HDST_API
199 bool HdStIsPrimvarExistentAndValid(
200  HdRprim *prim,
201  HdSceneDelegate *delegate,
202  HdPrimvarDescriptorVector const& primvars,
203  TfToken const& primvarName);
204 
205 // -----------------------------------------------------------------------------
206 // Constant primvar processing utilities
207 // -----------------------------------------------------------------------------
208 // Returns whether constant primvars need to be populated/updated based on the
209 // dirty bits for a given rprim.
210 HDST_API
211 bool HdStShouldPopulateConstantPrimvars(
212  HdDirtyBits const *dirtyBits,
213  SdfPath const& id);
214 
215 // Given prim information it will create sources representing
216 // constant primvars and hand it to the resource registry.
217 // If transforms are dirty, updates the optional bool.
218 HDST_API
219 void HdStPopulateConstantPrimvars(
220  HdRprim *prim,
221  HdRprimSharedData *sharedData,
222  HdSceneDelegate *delegate,
223  HdRenderParam *renderParam,
224  HdDrawItem *drawItem,
225  HdDirtyBits *dirtyBits,
226  HdPrimvarDescriptorVector const& constantPrimvars,
227  bool *hasMirroredTransform = nullptr);
228 
229 // -----------------------------------------------------------------------------
230 // Instancer processing utilities
231 // -----------------------------------------------------------------------------
232 
233 // Updates drawItem bindings for changes to instance topology/primvars.
234 HDST_API
235 void HdStUpdateInstancerData(
236  HdRenderIndex &renderIndex,
237  HdRenderParam *renderParam,
238  HdRprim *prim,
239  HdStDrawItem *drawItem,
240  HdRprimSharedData *sharedData,
241  HdDirtyBits rprimDirtyBits);
242 
243 // Returns true if primvar with primvarName exists among instance primvar
244 // descriptors.
245 HDST_API
246 bool HdStIsInstancePrimvarExistentAndValid(
247  HdRenderIndex &renderIndex,
248  HdRprim *prim,
249  TfToken const& primvarName);
250 
251 // -----------------------------------------------------------------------------
252 // Topological visibility processing utility
253 // -----------------------------------------------------------------------------
254 // Creates/Updates/Migrates the topology visiblity BAR with element and point
255 // visibility encoded using one bit per element/point of the topology.
256 HDST_API
257 void HdStProcessTopologyVisibility(
258  VtIntArray invisibleElements,
259  int numTotalElements,
260  VtIntArray invisiblePoints,
261  int numTotalPoints,
262  HdRprimSharedData *sharedData,
263  HdStDrawItem *drawItem,
264  HdRenderParam *renderParam,
265  HdChangeTracker *changeTracker,
266  HdStResourceRegistrySharedPtr const &resourceRegistry,
267  SdfPath const& rprimId);
268 
269 //
270 // De-duplicating and sharing immutable primvar data.
271 //
272 // Primvar data is identified using a hash computed from the
273 // sources of the primvar data, of which there are generally
274 // two kinds:
275 // - data provided by the scene delegate
276 // - data produced by computations
277 //
278 // Immutable and mutable buffer data is managed using distinct
279 // heaps in the resource registry. Aggregation of buffer array
280 // ranges within each heap is managed separately.
281 //
282 // We attempt to balance the benefits of sharing vs efficient
283 // varying update using the following simple strategy:
284 //
285 // - When populating the first repr for an rprim, allocate
286 // the primvar range from the immutable heap and attempt
287 // to deduplicate the data by looking up the primvarId
288 // in the primvar instance registry.
289 //
290 // - When populating an additional repr for an rprim using
291 // an existing immutable primvar range, compute an updated
292 // primvarId and allocate from the immutable heap, again
293 // attempting to deduplicate.
294 //
295 // - Otherwise, migrate the primvar data to the mutable heap
296 // and abandon further attempts to deduplicate.
297 //
298 // - The computation of the primvarId for an rprim is cumulative
299 // and includes the new sources of data being committed
300 // during each successive update.
301 //
302 // - Once we have migrated a primvar allocation to the mutable
303 // heap we will no longer spend time computing a primvarId.
304 //
305 
306 HDST_API
307 bool HdStIsEnabledSharedVertexPrimvar();
308 
309 HDST_API
310 uint64_t HdStComputeSharedPrimvarId(
311  uint64_t baseId,
312  HdBufferSourceSharedPtrVector const &sources,
313  HdStComputationSharedPtrVector const &computations);
314 
315 HDST_API
316 void HdStGetBufferSpecsFromCompuations(
317  HdStComputationSharedPtrVector const& computations,
318  HdBufferSpecVector *bufferSpecs);
319 
320 PXR_NAMESPACE_CLOSE_SCOPE
321 
322 #endif // PXR_IMAGING_HD_ST_PRIM_UTILS_H
The Hydra render index is a flattened representation of the client scene graph, which may be composed...
Definition: renderIndex.h:120
Tracks changes from the HdSceneDelegate, providing invalidation cues to the render engine.
Definition: changeTracker.h:51
The HdRenderParam is an opaque (to core Hydra) handle, to an object that is obtained from the render ...
Token for efficient comparison, assignment, and hashing of known strings.
Definition: token.h:87
The render engine state for a given rprim from the scene graph.
Definition: rprim.h:54
Adapter class providing data exchange with the client scene graph.
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:442
A path value used to locate objects in layers or scenegraphs.
Definition: path.h:290
HdSt implements instancing by drawing each proto multiple times with a single draw call.
Definition: instancer.h:68
A draw item is a light-weight representation of an HdRprim's resources and material to be used for re...
Definition: drawItem.h:66