HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
niPrototypePropagatingSceneIndex.h
Go to the documentation of this file.
1 //
2 // Copyright 2022 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_USD_IMAGING_USD_IMAGING_NI_PROTOTYPE_PROPAGATING_SCENE_INDEX_H
25 #define PXR_USD_IMAGING_USD_IMAGING_NI_PROTOTYPE_PROPAGATING_SCENE_INDEX_H
26 
28 
31 
33 
35 
37 
38 /// \class UsdImagingNiPrototypePropagatingSceneIndex
39 ///
40 /// A scene index implementing USD native instancing. If combined
41 /// with the UsdImagingPiPrototypePropagatingSceneIndex, the native
42 /// instancing scene index has to be run after the point instancing
43 /// scene index.
44 ///
45 /// This scene index uses the UsdImagingNiInstanceAggregationSceneIndex
46 /// to find all instances, aggregate them and insert instancers for
47 /// each set of aggregated instances. This scene index then inserts
48 /// flattened and possibly further transformed (e.g. applying draw mode)
49 /// copies of the corresponding USD prototype underneath each of these
50 /// instancers. Each of these copies is actually a
51 /// UsdImagingNiPrototypePropagatingSceneIndex itself. This way, we can
52 /// handle nested native instancing. In other words, we can call the
53 /// UsdImagingNiPrototypePropagatingSceneIndex for a USD prototype and
54 /// it will find the instances within that prototype.
55 ///
56 /// The instancing scene index uses the instancedBy:prototypeRoot
57 /// of the input scene index during aggregation.
58 /// Typically, the input scene index will be a
59 /// UsdImagingPiPrototypePropagatingSceneIndex which populates
60 /// instancedBy:prototypeRoot based on which point instancer is
61 /// instancing a prim.
62 ///
63 /// This scene index is implemented by a merging scene index with the
64 /// following inputs:
65 /// - a scene index ultimately tracing back to UsdImaging_NiPrototypeSceneIndex
66 /// which prepares the prototype for which this scene index was created.
67 /// The scene indices applied after UsdImaging_NiPrototypeSceneIndex
68 /// include a flattening scene index as well as scene indices
69 /// that can be specified through a callback by a user (typically,
70 /// the draw mode scene index).
71 /// - the UsdImaging_NiInstanceAggregationSceneIndex instantiated from the
72 /// above scene index. The instance aggregation scene index will insert the
73 /// instancers for the instances within this prototype.
74 /// - More UsdImagingNiPrototypePropagatingSceneIndex's:
75 /// The _InstanceAggregationSceneIndexObserver will observe the
76 /// latter scene index to add
77 /// respective UsdImagingNiPrototypePropagatingSceneIndex's under
78 /// each instancer.
79 ///
80 /// Example 1 (also see Example 1 in niInstanceAggregationSceneIndex.h)
81 ///
82 /// USD:
83 ///
84 /// def Xform "MyPrototype"
85 /// {
86 /// def Cube "MyCube"
87 /// {
88 /// }
89 /// }
90 ///
91 /// def "Cube_1" (
92 /// instanceable = true
93 /// references = </MyPrototype>
94 /// {
95 /// }
96 ///
97 /// Inputs of the UsdImagingNiPrototypePropagatingSceneIndex(inputSceneIndex):
98 ///
99 /// * HdMergingSceneIndex
100 /// * UsdImagingDrawModeSceneIndex (through SceneIndexAppendCallback)
101 /// * HdFlatteningSceneIndex
102 /// inputArgs = UsdImagingFlattenedDataSourceProviders()
103 /// [So model:drawMode is also flattened]
104 /// * UsdImaging_NiPrototypeSceneIndex
105 /// forPrototype = false
106 /// prototypeRootOverlayDs = null
107 /// * UsdImaging_NiPrototypePruningSceneIndex
108 /// forPrototype = false
109 /// * inputSceneIndex (typically a UsdImagingPiPrototypePropagatingSceneIndex)
110 /// * UsdImaging_NiInstanceAggregationSceneIndex
111 /// forPrototype = false
112 /// instanceDataSourceNames = ['materialBindings', 'purpose', 'model']
113 /// * UsdImagingDrawModeSceneIndex
114 /// [... as above]
115 /// * UsdImagingRerootingSceneIndex
116 /// (inserted by _InstanceAggregationSceneIndexObserver::PrimsAdded
117 /// through _MergingSceneIndexEntry)
118 /// srcPrefix = /UsdNiInstancer
119 /// dstPrefix = /UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer
120 /// * UsdImagingNiPrototypePropagatingSceneIndex
121 /// prototypeName = __Prototype_1
122 /// * HdMergingSceneIndex
123 /// * UsdImagingDrawModeSceneIndex (through SceneIndexAppendCallback)
124 /// * HdFlatteningSceneIndex
125 /// inputArgs = UsdImagingFlattenedDataSourceProviders()
126 /// [So model:drawMode is also flattened]
127 /// * UsdImaging_NiPrototypeSceneIndex
128 /// forPrototype = true
129 /// * UsdImagingRerootingSceneIndex
130 /// srcPrefix = /__PrototypeRoot1
131 /// dstPrefix = /UsdNiInstancer/UsdNiPrototype
132 /// * inputSceneIndex
133 /// * UsdImaging_NiInstanceAggregationSceneIndex
134 /// forPrototype = true
135 /// * UsdImagingDrawModeSceneIndex
136 /// [... as just above]
137 ///
138 /// UsdImagingNiPrototypePropagatingSceneIndex
139 ///
140 /// /Cube_1
141 /// primType: ""
142 /// dataSource:
143 /// instance: # Useful for translating Usd proxy paths for selection.
144 /// # See corresponding example in niInstanceAggregationIndex
145 /// # for more details.
146 /// instancer: /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer
147 /// prototypeId: 0
148 /// instanceId: 0
149 /// purpose: # From flattening scene index
150 /// purpose: geometry
151 /// xform: # From flattening scene index
152 /// matrix: [ identity matrix]
153 /// primOrigin:
154 /// scenePath: HdPrimOriginSchema::OriginPath(/Cube_1)
155 /// ...
156 /// /MyPrototype # Not referenced from a different file, so appears here
157 /// # as non-prototype as well
158 /// primType: ""
159 /// /MyPrototype/MyCube
160 /// primType: cube
161 /// /UsdNiPropagatedPrototypes
162 /// primType: ""
163 /// /UsdNiPropagatedPrototypes/Bindings_423...234
164 /// primType: ""
165 /// dataSource:
166 /// purpose: # Added by instance aggregation scene index, copied from /Cube_1
167 /// purpose: geometry
168 /// # No xform, visibility (never copied by instance aggregation, written to
169 /// instancer instead)
170 /// /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1
171 /// primType: ""
172 /// /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer
173 /// primType: instancer
174 /// dataSource:
175 /// instancerTopology:
176 /// instanceIndices:
177 /// i0: [ 0 ]
178 /// prototypes: [ /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer/UsdNiPrototype
179 /// instanceLocations: [ /Cube_1 ] # for picking
180 /// primvars:
181 /// hydra:instanceTransforms:
182 /// primvarValue: [ identity matrix ]
183 /// interpolation: instance
184 /// /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer/UsdNiPrototype
185 /// primType: ""
186 /// dataSource:
187 /// instancedBy:
188 /// paths: [ /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer ]
189 /// prototypeRoot: /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1 /UsdNiInstancer/UsdNiPrototype
190 /// purpose: # Added by prototype scene index, copied from /UsdNiPropagatedPrototypes/Bindings_423...234
191 /// # Flattened scene index did not touch it.
192 /// purpose: geometry
193 /// xform: # From flattening scene index
194 /// matrix: [ identity matrix ]
195 /// resetXformStack: true
196 /// primOrigin:
197 /// scenePath: HdPrimOriginSchema::OriginPath(.)
198 /// /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer/UsdNiPrototype/MyCube
199 /// primType: cube
200 /// dataSource:
201 /// instancedBy:
202 /// paths: [ /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1/UsdNiInstancer ]
203 /// prototypeRoot: /UsdNiPropagatedPrototypes/Bindings_423...234/__Prototype_1 /UsdNiInstancer/UsdNiPrototype
204 /// purpose: # From flattening scene index
205 /// purpose: geometry
206 /// xform: # From flattening scene index
207 /// matrix: [ identity matrix ]
208 /// resetXformStack: true
209 /// primOrigin:
210 /// scenePath: HdPrimOriginSchema::OriginPath(MyCube)
211 ///
212 /// Example 2:
213 ///
214 /// def Xform "MyNestedPrototype" # Will become USD prototype /__Prototype_1
215 /// {
216 /// def Cube "MyCube"
217 /// {
218 /// }
219 /// }
220 ///
221 /// def Xform "MyPrototype" # Will become USD prototype /__Prototype_2
222 /// {
223 /// def "MyNestedInstance" (
224 /// instanceable = true
225 /// references = </MyNestedPrototype> )
226 /// {
227 /// }
228 /// }
229 ///
230 /// def Xform "MyInstance" (
231 /// instanceable = true
232 /// references = </MyPrototype>)
233 /// {
234 ///
235 /// }
236 ///
237 /// UsdImagingNiPrototypePropagatingSceneIndex
238 ///
239 /// ...
240 /// /MyInstance
241 /// primType: ""
242 /// dataSource:
243 /// instance:
244 /// instancer: /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer
245 /// prototypeId: 0
246 /// instanceId: 0
247 /// ...
248 /// /UsdNiPropagatedPrototypes
249 /// primType: ""
250 /// /UsdNiPropagatedPrototypes/NoBindings
251 /// primType: ""
252 /// dataSource:
253 /// ...
254 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2
255 /// primType: ""
256 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer
257 /// primType: instancer
258 /// dataSource:
259 /// instanerTopology:
260 /// prototypes: [ /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype ]
261 /// ...
262 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/_Prototype_2
263 /// primType: ""
264 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/_Prototype_2/MyNestedInstance
265 /// primType: ""
266 /// dataSource:
267 /// instancer: /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer
268 /// prototypeId: 0
269 /// instanceId: 0
270 /// ...
271 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes
272 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings
273 /// primType: ""
274 /// dataSource:
275 /// ...
276 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1
277 /// primType: ""
278 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer
279 /// primType: instancer
280 /// dataSource:
281 /// instanerTopology:
282 /// prototypes: [ /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer/UsdPiPrototype ]
283 /// ...
284 /// instancedBy:
285 /// paths: [ /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer ]
286 /// prototypeRoot: /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype
287 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer/UsdPiPrototype
288 /// primType: ""
289 /// dataSource:
290 /// instancedBy:
291 /// paths: [ /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer ]
292 /// prototypeRoot: /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer/UsdPiPrototype
293 /// ...
294 /// /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer/UsdPiPrototype/MyCube
295 /// primType: "cube"
296 /// dataSource:
297 /// instancedBy:
298 /// paths: [ /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/UsdPiPrototype/UsdNiInstancer ]
299 /// prototypeRoot: /UsdNiPropagatedPrototypes/NoBindings/__Prototype_2/UsdNiInstancer/UsdPiPrototype/UsdNiPropagatedPrototypes/NoBindings/__Prototype_1/UsdNiInstancer/UsdPiPrototype
300 /// ...
301 ///
302 ///
305 {
306 public:
308  std::function<
309  HdSceneIndexBaseRefPtr(const HdSceneIndexBaseRefPtr &inputScene)>;
310 
311  // instanceDataSourceNames are the names of the data sources of a native
312  // instance prim that need to have the same values for the instances to
313  // be aggregated. A copy of these data sources is bundled into the
314  // prim data source for the binding scope.
315  //
316  // When propagating a prototype by inserting the scene index isolating
317  // that prototype into the merging scene index implementing this scene
318  // index, we also call sceneIndexAppendCallback.
319  //
320  // The use case is for the UsdImagingDrawModeSceneIndex.
321  //
323  static UsdImagingNiPrototypePropagatingSceneIndexRefPtr New(
324  HdSceneIndexBaseRefPtr const &inputSceneIndex,
325  const TfTokenVector &instanceDataSourceNames,
326  const SceneIndexAppendCallback &sceneIndexAppendCallback);
327 
330 
332  HdSceneIndexPrim GetPrim(const SdfPath &primPath) const override;
333 
335  SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const override;
336 
338  std::vector<HdSceneIndexBaseRefPtr> GetInputScenes() const override;
339 
340 private:
341  class _SceneIndexCache;
342  using _SceneIndexCacheSharedPtr =
343  std::shared_ptr<_SceneIndexCache>;
344 
345  class _MergingSceneIndexEntry;
346  using _MergingSceneIndexEntryUniquePtr =
347  std::unique_ptr<_MergingSceneIndexEntry>;
348 
351  {
352  public:
355 
356  void PrimsAdded(
357  const HdSceneIndexBase &sender,
358  const AddedPrimEntries &entries) override;
359  void PrimsDirtied(
360  const HdSceneIndexBase &sender,
361  const DirtiedPrimEntries &entries) override;
362  void PrimsRemoved(
363  const HdSceneIndexBase &sender,
364  const RemovedPrimEntries &entries) override;
365  void PrimsRenamed(
366  const HdSceneIndexBase &sender,
367  const RenamedPrimEntries &entries) override;
368 
369  private:
371  };
372 
375  {
376  public:
379 
380  void PrimsAdded(
381  const HdSceneIndexBase &sender,
382  const AddedPrimEntries &entries) override;
383  void PrimsDirtied(
384  const HdSceneIndexBase &sender,
385  const DirtiedPrimEntries &entries) override;
386  void PrimsRemoved(
387  const HdSceneIndexBase &sender,
388  const RemovedPrimEntries &entries) override;
389  void PrimsRenamed(
390  const HdSceneIndexBase &sender,
391  const RenamedPrimEntries &entries) override;
392 
393  private:
395  };
396 
397  // Use prototypeName to instantiate for "scene root".
398  static UsdImagingNiPrototypePropagatingSceneIndexRefPtr _New(
399  const TfToken &prototypeName,
400  HdContainerDataSourceHandle const &prototypeRootOverlayDs,
401  _SceneIndexCacheSharedPtr const &cache);
402 
404  const TfToken &prototypeName,
405  HdContainerDataSourceHandle const &prototypeRootOverlayDs,
406  _SceneIndexCacheSharedPtr const &cache);
407 
408  void _Populate(HdSceneIndexBaseRefPtr const &instanceAggregationSceneIndex);
409  void _AddPrim(const SdfPath &primPath);
410  void _RemovePrim(const SdfPath &primPath);
411 
412  const TfToken _prototypeName;
413  const HdDataSourceHashType _prototypeRootOverlayDsHash;
414  _SceneIndexCacheSharedPtr const _cache;
415 
416  HdMergingSceneIndexRefPtr _mergingSceneIndex;
417 
418  std::map<SdfPath, _MergingSceneIndexEntryUniquePtr>
419  _instancersToMergingSceneIndexEntry;
420 
421  HdSceneIndexBaseRefPtr _instanceAggregationSceneIndex;
422 
424  _instanceAggregationSceneIndexObserver;
425  _MergingSceneIndexObserver _mergingSceneIndexObserver;
426 };
427 
429 
430 #endif
USDIMAGING_API ~UsdImagingNiPrototypePropagatingSceneIndex() override
#define USDIMAGING_API
Definition: api.h:40
USDIMAGING_API HdSceneIndexPrim GetPrim(const SdfPath &primPath) const override
size_t HdDataSourceHashType
USDIMAGING_API SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const override
static USDIMAGING_API UsdImagingNiPrototypePropagatingSceneIndexRefPtr New(HdSceneIndexBaseRefPtr const &inputSceneIndex, const TfTokenVector &instanceDataSourceNames, const SceneIndexAppendCallback &sceneIndexAppendCallback)
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_REF_PTRS(HdMergingSceneIndex)
Definition: token.h:87
USDIMAGING_API std::vector< HdSceneIndexBaseRefPtr > GetInputScenes() const override
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:457
Definition: path.h:290
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
std::function< HdSceneIndexBaseRefPtr(const HdSceneIndexBaseRefPtr &inputScene)> SceneIndexAppendCallback