HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
piPrototypePropagatingSceneIndex.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_PI_PROTOTYPE_PROPAGATING_SCENE_INDEX_H
25 #define PXR_USD_IMAGING_USD_IMAGING_PI_PROTOTYPE_PROPAGATING_SCENE_INDEX_H
26 
28 
30 
32 
34 
35 namespace UsdImagingPiPrototypePropagatingSceneIndex_Impl
36 {
37 using _ContextSharedPtr = std::shared_ptr<struct _Context>;
38 using _InstancerObserverUniquePtr = std::unique_ptr<class _InstancerObserver>;
39 }
40 
41 /// \class UsdImagingPiPrototypePropagatingSceneIndex
42 ///
43 /// A scene index translating USD point instancers into Hydra instancers.
44 ///
45 /// It applies various USD semantics and populates the "instancedBy" schema,
46 /// including the prototypeRoot data source which is needed by the USD native
47 /// instancing scene index.
48 ///
49 /// To achieve various USD behaviors, it has a (recursive) instancer observer
50 /// that inserts copies of prototypes processed through the prototype scene
51 /// index into appropriate places in namespace.
52 ///
53 /// ---------------------------------------------------------------------------
54 ///
55 /// Example 1:
56 ///
57 /// USD:
58 ///
59 /// def PointInstancer "MyInstancer"
60 /// {
61 /// rel prototypes = [
62 /// </MyInstancer/MyPrototypes/MyPrototype> ]
63 /// def Scope "MyPrototypes"
64 /// {
65 /// def Xform "MyPrototype"
66 /// {
67 /// def Sphere "MySphere"
68 /// {
69 /// }
70 /// }
71 /// }
72 /// }
73 ///
74 /// Note that USD says that no geometry under a PointInstancer is drawn unless
75 /// it is targeted by a point instancer's prototype relationship.
76 ///
77 /// Inputs of the PointPropagatingSceneIndex:
78 ///
79 /// * _Context::mergingSceneIndex
80 /// (HdMergingSceneIndex)
81 /// * _Context::instancerSceneIndex
82 /// (HdRetainedSceneIndex, will rewrite prototypes of /MyInstancer to
83 /// [ /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55 ] )
84 /// * UsdImaging_PiPrototypeSceneIndex
85 /// (inserted by PointPropagatingSceneIndex::_instancerOberver
86 /// which was constructed with
87 /// instancer = ""
88 /// prototypeRoot = /
89 /// rerootedPrototypeRoot = /)
90 /// instancer = ""
91 /// prototypeRoot = /
92 /// * _Context::inputSceneIndex
93 /// (argument to PointPropagatingSceneIndex,
94 /// typically UsdImagingStageSceneIndex, maybe followed by
95 /// other filtering scene indices)
96 /// * UsdImagingRerootingSceneIndex
97 /// (inserted recursively by PointPropagatingSceneIndex::_instancerObserver::_subinstancerObservers
98 /// which was constructed with
99 /// instancer = /MyInstancer
100 /// prototypeRoot = /MyInstancer/MyPrototypes/MyPrototype
101 /// rerootedPrototypeRoot = /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55)
102 /// srcPrefix = /MyInstancer/MyPrototypes/MyPrototype
103 /// dstPrefix = /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55
104 /// * UsdImaging_PiPrototypeSceneIndex
105 /// instancer = /MyInstancer
106 /// prototypeRoot = /MyInstancer/MyPrototypes/MyPrototype
107 /// * UsdImagingRerootingSCeneIndex
108 /// srcPrefix = dstPrefix = /MyInstancer/MyPrototypes/MyPrototype
109 /// * _Context::inputSceneIndex
110 ///
111 /// PointPropagatingSceneIndex:
112 ///
113 /// /MyInstancer
114 /// primType: instancer
115 /// dataSource:
116 /// setting # [1]
117 /// prototypes = [/MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55]
118 ///
119 /// /MyInstancer/MyPrototypes
120 /// /MyInstancer/MyPrototypes/MyPrototype
121 /// /MyInstancer/MyPrototypes/MyPrototype/MySphere
122 /// primType: "" # [2]
123 /// dataSource: unchanged
124 ///
125 /// /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55 # [3]
126 /// primType: unchanged (from /MyInstancer/MyPrototypes/MyPrototype)
127 /// dataSource: (from /MyInstancer/MyPrototypes/MyPrototype)
128 /// setting # [4]
129 /// xform:resetXformStack = true
130 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55
131 /// instancedBy:paths = /MyInstancer
132 ///
133 /// /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55/MySphere
134 /// dataSource: (from /MyInstancer/MyPrototypes/MyPrototype/MySphere)
135 /// setting # [5]
136 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55
137 /// instancedBy:paths = /MyInstancer
138 ///
139 /// [1] Set through the retained scene index _Context::instancerSceneIndex to
140 /// point to the re-rooted copy of the prototype.
141 /// The prim entry was inserted by the (recursive) instancer observer
142 /// (instantiated with instancer = empty,
143 /// prototypeRoot = rerootedPrototypeRoot = /).
144 ///
145 /// [2] Forced by the prototype scene index (instantiated with
146 /// instancer = empty and prototypeRoot = /).
147 /// In general, the prototype scene index forces the prim
148 /// type to empty for all descendants of instancers within the prototypeRoot.
149 ///
150 /// [3] The re-rooted copy of /MyInstancer/MyPrototypes/MyPrototype inserted
151 /// by the instancer observer (instantiated with instancer = /MyInstancer,
152 /// prototypeRoot = /MyInstancer/MyPrototypes/MyPrototypes and
153 /// rerootedPrototypeRoot = /MyInstancer/MyPrototypes/MyPrototype/ForInstancer84e...f55
154 ///
155 /// [4] Set by the prototype scene index (instantiated with
156 /// instancer = /MyInstancer,
157 /// prototypeRoot = /MyInstancer/MyPrototypes/MyPrototypes).
158 ///
159 /// For the prototype root itself, it resets the xform stack so that the xform
160 /// of geometry within a prototype is relative to the root of the prototype.
161 /// Also see [5].
162 ///
163 /// [5] Set by the same prototype scene index.
164 ///
165 /// Sets instancedBy:prototypeRoot and instancedBy:paths on all prims that are
166 /// not descendants of an instancer within the prototype root.
167 ///
168 /// ---------------------------------------------------------------------------
169 ///
170 /// Example 2:
171 ///
172 /// USD:
173 ///
174 /// def PointInstancer "MyInstancer"
175 /// {
176 /// rel prototypes = [
177 /// </MyPrototypes/MyPrototype> ]
178 /// }
179 /// over "MyPrototypes"
180 /// {
181 /// def Xform "MyPrototype"
182 /// {
183 /// def Sphere "MySphere"
184 /// {
185 /// }
186 /// }
187 /// }
188 ///
189 /// Note that the USD specification says that even though
190 /// /MyPrototype/MyPrototype is under an "over", it will be drawn (through
191 /// an instancer) since it is targeted by a PointInstancers' prototypes
192 /// relationship. Furthermore, if "MyPrototypes" is changed from an "over" to
193 /// a "def", MySphere would be drawn twice: once in its own right and once
194 /// being instanced by /MyInstancers.
195 ///
196 /// PointPropagatingSceneIndex::
197 ///
198 /// /MyInstancer
199 /// primType: instancer
200 /// dataSource:
201 /// setting # [1]
202 /// prototypes = [/MyPrototypes/MyPrototype/ForInstancer4e6...f36]
203 ///
204 /// /MyPrototypes
205 /// /MyPrototypes/MyPrototype
206 /// /MyPrototypes/MyPrototype/MySphere
207 /// primType: "" # [2]
208 /// dataSource: unchanged
209 ///
210 /// /MyPrototypes/MyPrototype/ForInstancer4e6...f36 # [3]
211 /// primType: unchanged (from /MyPrototypes/MyPrototype)
212 /// dataSource: (from /MyPrototypes/MyPrototype)
213 /// settings # [4]
214 /// xform:resetXformStack = true
215 /// instancedBy:PrototypeRoot = /MyPrototypes/MyPrototype/ForInstancer4e6...f36
216 /// instancedBy:paths = /MyInstancer
217 ///
218 /// /MyPrototypes/MyPrototype/ForInstancer4e6...f36/MySphere
219 /// dataSource: (from /MyInstancer/MyPrototypes/MyPrototype/MySphere)
220 /// setting # [5]
221 /// instancedBy:PrototypeRoot = /MyPrototypes/MyPrototype/ForInstancer4e6...f36
222 /// instancedBy:paths = /MyInstancer
223 ///
224 /// [1] As [1] in Example 1.
225 ///
226 /// [2] Forced by the prototype scene index.
227 /// In general, the prototype scene index forces the prim type to
228 /// empty for all descendants of an over.
229 /// Note that we changed MyPrototypes from an "over" to a "def", there will be
230 /// prim's of type sphere in the scene index corresponding to the one USD prim:
231 /// one instanced through /MyInstancer and one not instanced.
232 ///
233 /// [3] The re-rooted copy of /MyPrototypes/MyPrototype inserted
234 /// by the instancer observer (instantiated with instancer = /MyInstancer,
235 /// prototypeRoot = /MyPrototypes/MyPrototypes and
236 /// rerootedPrototypeRoot = /MyPrototypes/MyPrototype/ForInstancer4e6...f36
237 ///
238 /// [4] Similar to [4] in Example 1.
239 ///
240 /// [5] Similar to [5] in Example 1.
241 ///
242 /// ---------------------------------------------------------------------------
243 ///
244 /// Example 3:
245 ///
246 /// USD:
247 ///
248 /// def PointInstancer "MyInstancer"
249 /// {
250 /// rel prototypes = [
251 /// </MyInstancer/MyPrototype> ]
252 /// def Xform "MyPrototype"
253 /// {
254 /// def PointInstancer "MyNestedInstancer"
255 /// {
256 /// rel prototypes = [
257 /// </MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype> ]
258 /// def Xform "MyNestedPrototype"
259 /// {
260 /// def Sphere "MySphere"
261 /// {
262 /// }
263 /// }
264 /// }
265 /// }
266 /// }
267 ///
268 /// Note that "MySphere" is instanced by two nested point instancers.
269 /// This will be realized by the PointPropagatingSceneIndex as follows:
270 /// PointPropagatingSceneIndex as follows:
271 ///
272 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f/MySphere
273 /// is instanced by
274 /// /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer
275 /// is instanced by
276 /// /MyInstancer
277 ///
278 /// PointPropagatingSceneIndex:
279 ///
280 /// /MyInstancer
281 /// primType: instancer
282 /// dataSource:
283 /// setting # [1]
284 /// prototypes = [/MyInstancer/MyPrototype/ForInstancer6a3...234]
285 ///
286 /// /MyInstancer/MyPrototype
287 /// /MyInstancer/MyPrototype/MyNestedInstancer
288 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype
289 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/MySphere
290 /// primType: "" # [2]
291 /// dataSource: unchanged
292 ///
293 /// /MyInstancer/MyPrototype/ForInstancer6a3...234 # [3]
294 /// primType: unchanged (from /MyInstancer/MyPrototype)
295 /// dataSource: (from /MyInstancer/MyPrototype)
296 /// settings # [4]
297 /// xform:resetXformStack = true
298 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototype/ForInstancer6a3...234
299 /// instancedBy:paths = /MyInstancer
300 ///
301 /// /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer
302 /// primType: instancer
303 /// dataSource:
304 /// setting # [5]
305 /// prototypes = [/MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f]
306 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototype/ForInstancer6a3...234
307 /// instancedBy:paths = /MyInstancer
308 ///
309 /// /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer/MyNestedPrototype
310 /// /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer/MyNestedPrototype/MySphere
311 /// primType: "" # [6]
312 /// dataSource: unchanged
313 ///
314 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f #[7]
315 /// primType: unchanged (from /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype)
316 /// dataSource: (from /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype)
317 /// settings # [8]
318 /// xform:resetXformStack = true
319 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f
320 /// instancedBy:paths = /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer
321 ///
322 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f/MySphere
323 /// primType: sphere
324 /// dataSource:
325 /// settings # [9]
326 /// instancedBy:PrototypeRoot = /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f
327 /// instancedBy:paths = /MyInstancer/MyPrototype/ForInstancer6a3...234/MyNestedInstancer
328 ///
329 /// [1] As [1] in Example 1.
330 ///
331 /// [2] As [2] in Example 1.
332 ///
333 /// [3] The re-rooted copy of /MyInstancer/MyPrototype inserted
334 /// by the instancer observer (instantiated with instancer = /MyInstancer,
335 /// prototypeRoot = /MyInstancer/MyPrototypes and
336 /// rerootedPrototypeRoot = /MyInstancer/MyPrototype/ForInstancer6a3...234).
337 ///
338 /// [4] Similar to [4] in Example 1.
339 ///
340 /// [5] Similar to [5] in Example 1.
341 ///
342 /// [6] The prototype scene index forced the empty prim types on
343 /// all descendants of an instancer within the prototype root.
344 ///
345 /// [7] The re-rooted copy of
346 /// /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype inserted
347 /// by the instancer observer (instantiated with
348 /// instancer = /MyInstancer/MyPrototype/MyNestedInstancer,
349 /// prototypeRoot = /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype,
350 /// rerootedPrototypeRoot = /MyInstancer/MyPrototype/MyNestedInstancer/MyNestedPrototype/ForInstancer8a2...51f)
351 ///
352 /// Note that this copy is inserted by the instancer observer for
353 /// /MyInstancer/MyPrototype.
354 ///
355 /// The instancer path is the path in the USD scene and will be changed by
356 /// a latter re-rooting scene index in the instancer observer.
357 ///
358 /// Note the hash at the end of the rerootedPrototypeRoot was computed from the
359 /// calling the instancer observer by combining its rerootedPrototypeRoot with
360 /// the path of the instancer within its prototypeRoot.
361 ///
362 /// [8] Similar to [4].
363 ///
364 /// [9] Similar to [5].
365 ///
368 {
369 public:
371  static UsdImagingPiPrototypePropagatingSceneIndexRefPtr New(
372  HdSceneIndexBaseRefPtr const &inputSceneIndex);
373 
375  HdSceneIndexPrim GetPrim(const SdfPath &primPath) const override;
376 
378  SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const override;
379 
381  std::vector<HdSceneIndexBaseRefPtr> GetInputScenes() const override;
382 
383 private:
385  const HdSceneIndexBaseRefPtr &inputSceneIndex);
386 
389  {
390  public:
393 
394  void PrimsAdded(
395  const HdSceneIndexBase &sender,
396  const AddedPrimEntries &entries) override;
397  void PrimsDirtied(
398  const HdSceneIndexBase &sender,
399  const DirtiedPrimEntries &entries) override;
400  void PrimsRemoved(
401  const HdSceneIndexBase &sender,
402  const RemovedPrimEntries &entries) override;
403  void PrimsRenamed(
404  const HdSceneIndexBase &sender,
405  const RenamedPrimEntries &entries) override;
406 
407  private:
409  };
410 
412  _ContextSharedPtr const _context;
413 
414  _MergingSceneIndexObserver _mergingSceneIndexObserver;
415 
417  _InstancerObserverUniquePtr const _instancerObserver;
418 };
419 
421 
422 #endif
423 
USDIMAGING_API HdSceneIndexPrim GetPrim(const SdfPath &primPath) const override
std::unique_ptr< class _InstancerObserver > _InstancerObserverUniquePtr
#define USDIMAGING_API
Definition: api.h:40
PXR_NAMESPACE_OPEN_SCOPE TF_DECLARE_REF_PTRS(UsdImagingPiPrototypePropagatingSceneIndex)
Definition: path.h:290
std::vector< class SdfPath > SdfPathVector
A vector of SdfPaths.
Definition: path.h:211
USDIMAGING_API std::vector< HdSceneIndexBaseRefPtr > GetInputScenes() const override
static USDIMAGING_API UsdImagingPiPrototypePropagatingSceneIndexRefPtr New(HdSceneIndexBaseRefPtr const &inputSceneIndex)
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
USDIMAGING_API SdfPathVector GetChildPrimPaths(const SdfPath &primPath) const override