HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
pointInstancer.h
Go to the documentation of this file.
1 //
2 // Copyright 2016 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef USDGEOM_GENERATED_POINTINSTANCER_H
8 #define USDGEOM_GENERATED_POINTINSTANCER_H
9 
10 /// \file usdGeom/pointInstancer.h
11 
12 #include "pxr/pxr.h"
13 #include "pxr/usd/usdGeom/api.h"
15 #include "pxr/usd/usd/prim.h"
16 #include "pxr/usd/usd/stage.h"
17 #include "pxr/usd/usdGeom/tokens.h"
18 
19 #include "pxr/base/vt/value.h"
20 
21 #include "pxr/base/gf/vec3d.h"
22 #include "pxr/base/gf/vec3f.h"
23 #include "pxr/base/gf/matrix4d.h"
24 
25 #include "pxr/base/tf/token.h"
26 #include "pxr/base/tf/type.h"
27 
29 
30 class SdfAssetPath;
31 
32 // -------------------------------------------------------------------------- //
33 // POINTINSTANCER //
34 // -------------------------------------------------------------------------- //
35 
36 /// \class UsdGeomPointInstancer
37 ///
38 /// Encodes vectorized instancing of multiple, potentially
39 /// animated, prototypes (object/instance masters), which can be arbitrary
40 /// prims/subtrees on a UsdStage.
41 ///
42 /// PointInstancer is a "multi instancer", as it allows multiple prototypes
43 /// to be scattered among its "points". We use a UsdRelationship
44 /// \em prototypes to identify and order all of the possible prototypes, by
45 /// targeting the root prim of each prototype. The ordering imparted by
46 /// relationships associates a zero-based integer with each prototype, and
47 /// it is these integers we use to identify the prototype of each instance,
48 /// compactly, and allowing prototypes to be swapped out without needing to
49 /// reauthor all of the per-instance data.
50 ///
51 /// The PointInstancer schema is designed to scale to billions of instances,
52 /// which motivates the choice to split the per-instance transformation into
53 /// position, (quaternion) orientation, and scales, rather than a
54 /// 4x4 matrix per-instance. In addition to requiring fewer bytes even if
55 /// all elements are authored (32 bytes vs 64 for a single-precision 4x4
56 /// matrix), we can also be selective about which attributes need to animate
57 /// over time, for substantial data reduction in many cases.
58 ///
59 /// Note that PointInstancer is \em not a Gprim, since it is not a graphical
60 /// primitive by any stretch of the imagination. It \em is, however,
61 /// Boundable, since we will sometimes want to treat the entire PointInstancer
62 /// similarly to a procedural, from the perspective of inclusion or framing.
63 ///
64 /// \section UsdGeomPointInstancer_varyingTopo Varying Instance Identity over Time
65 ///
66 /// PointInstancers originating from simulations often have the characteristic
67 /// that points/instances are "born", move around for some time period, and then
68 /// die (or leave the area of interest). In such cases, billions of instances
69 /// may be birthed over time, while at any \em specific time, only a much
70 /// smaller number are actually alive. To encode this situation efficiently,
71 /// the simulator may re-use indices in the instance arrays, when a particle
72 /// dies, its index will be taken over by a new particle that may be birthed in
73 /// a much different location. This presents challenges both for
74 /// identity-tracking, and for motion-blur.
75 ///
76 /// We facilitate identity tracking by providing an optional, animatable
77 /// \em ids attribute, that specifies the 64 bit integer ID of the particle
78 /// at each index, at each point in time. If the simulator keeps monotonically
79 /// increasing a particle-count each time a new particle is birthed, it will
80 /// serve perfectly as particle \em ids.
81 ///
82 /// We facilitate motion blur for varying-topology particle streams by
83 /// optionally allowing per-instance \em velocities and \em angularVelocities
84 /// to be authored. If instance transforms are requested at a time between
85 /// samples and either of the velocity attributes is authored, then we will
86 /// not attempt to interpolate samples of \em positions or \em orientations.
87 /// If not authored, and the bracketing samples have the same length, then we
88 /// will interpolate.
89 ///
90 /// \section UsdGeomPointInstancer_transform Computing an Instance Transform
91 ///
92 /// Each instance's transformation is a combination of the SRT affine transform
93 /// described by its scale, orientation, and position, applied \em after
94 /// (i.e. less locally than) the local to parent transformation computed at
95 /// the root of the prototype it is instancing.
96 ///
97 /// If your processing of prototype geometry naturally takes into account the
98 /// transform of the prototype root, then this term can be omitted from the
99 /// computation of each instance transform, and this can be controlled when
100 /// computing instance transformation matrices using the
101 /// UsdGeomPointInstancer::PrototypeXformInclusion enumeration.
102 ///
103 /// To understand the computation of the instance transform, in order to put
104 /// an instance of a PointInstancer into the space of the PointInstancer's
105 /// parent prim we do the following:
106 ///
107 /// 1. Apply (most locally) the authored local to parent transformation for
108 /// <em>prototypes[protoIndices[i]]</em>
109 /// 2. If *scales* is authored, next apply the scaling matrix from *scales[i]*
110 /// 3. If *orientations* is authored: **if *angularVelocities* is authored**,
111 /// first multiply *orientations[i]* by the unit quaternion derived by scaling
112 /// *angularVelocities[i]* by the \ref UsdGeom_PITimeScaling "time differential"
113 /// from the left-bracketing timeSample for *orientation* to the requested
114 /// evaluation time *t*, storing the result in *R*, **else** assign *R*
115 /// directly from *orientations[i]*. Apply the rotation matrix derived
116 /// from *R*.
117 /// 4. Apply the translation derived from *positions[i]*. If *velocities* is
118 /// authored, apply the translation deriving from *velocities[i]* scaled by
119 /// the time differential from the left-bracketing timeSample for *positions*
120 /// to the requested evaluation time *t*.
121 /// 5. Least locally, apply the transformation authored on the PointInstancer
122 /// prim itself (or the UsdGeomImageable::ComputeLocalToWorldTransform() of the
123 /// PointInstancer to put the instance directly into world space)
124 ///
125 /// If neither *velocities* nor *angularVelocities* are authored, we fallback to
126 /// standard position and orientation computation logic (using linear
127 /// interpolation between timeSamples) as described by
128 /// \ref UsdGeom_VelocityInterpolation .
129 ///
130 /// \anchor UsdGeom_PITimeScaling
131 /// <b>Scaling Velocities for Interpolation</b>
132 ///
133 /// When computing time-differentials by which to apply velocity or
134 /// angularVelocity to positions or orientations, we must scale by
135 /// ( 1.0 / UsdStage::GetTimeCodesPerSecond() ), because velocities are recorded
136 /// in units/second, while we are interpolating in UsdTimeCode ordinates.
137 ///
138 /// We provide both high and low-level API's for dealing with the
139 /// transformation as a matrix, both will compute the instance matrices using
140 /// multiple threads; the low-level API allows the client to cache unvarying
141 /// inputs so that they need not be read duplicately when computing over
142 /// time.
143 ///
144 /// See also \ref UsdGeom_VelocityInterpolation .
145 ///
146 /// \section UsdGeomPointInstancer_primvars Primvars on PointInstancer
147 ///
148 /// \ref UsdGeomPrimvar "Primvars" authored on a PointInstancer prim should
149 /// always be applied to each instance with \em constant interpolation at
150 /// the root of the instance. When you are authoring primvars on a
151 /// PointInstancer, think about it as if you were authoring them on a
152 /// point-cloud (e.g. a UsdGeomPoints gprim). The same
153 /// <A HREF="https://renderman.pixar.com/resources/RenderMan_20/appnote.22.html#classSpecifiers">interpolation rules for points</A> apply here, substituting
154 /// "instance" for "point".
155 ///
156 /// In other words, the (constant) value extracted for each instance
157 /// from the authored primvar value depends on the authored \em interpolation
158 /// and \em elementSize of the primvar, as follows:
159 /// \li <b>constant</b> or <b>uniform</b> : the entire authored value of the
160 /// primvar should be applied exactly to each instance.
161 /// \li <b>varying</b>, <b>vertex</b>, or <b>faceVarying</b>: the first
162 /// \em elementSize elements of the authored primvar array should be assigned to
163 /// instance zero, the second \em elementSize elements should be assigned to
164 /// instance one, and so forth.
165 ///
166 ///
167 /// \section UsdGeomPointInstancer_masking Masking Instances: "Deactivating" and Invising
168 ///
169 /// Often a PointInstancer is created "upstream" in a graphics pipeline, and
170 /// the needs of "downstream" clients necessitate eliminating some of the
171 /// instances from further consideration. Accomplishing this pruning by
172 /// re-authoring all of the per-instance attributes is not very attractive,
173 /// since it may mean destructively editing a large quantity of data. We
174 /// therefore provide means of "masking" instances by ID, such that the
175 /// instance data is unmolested, but per-instance transform and primvar data
176 /// can be retrieved with the no-longer-desired instances eliminated from the
177 /// (smaller) arrays. PointInstancer allows two independent means of masking
178 /// instances by ID, each with different features that meet the needs of
179 /// various clients in a pipeline. Both pruning features' lists of ID's are
180 /// combined to produce the mask returned by ComputeMaskAtTime().
181 ///
182 /// \note If a PointInstancer has no authored \em ids attribute, the masking
183 /// features will still be available, with the integers specifying element
184 /// position in the \em protoIndices array rather than ID.
185 ///
186 /// \subsection UsdGeomPointInstancer_inactiveIds InactiveIds: List-edited, Unvarying Masking
187 ///
188 /// The first masking feature encodes a list of IDs in a list-editable metadatum
189 /// called \em inactiveIds, which, although it does not have any similar
190 /// impact to stage population as \ref UsdPrim::SetActive() "prim activation",
191 /// it shares with that feature that its application is uniform over all time.
192 /// Because it is list-editable, we can \em sparsely add and remove instances
193 /// from it in many layers.
194 ///
195 /// This sparse application pattern makes \em inactiveIds a good choice when
196 /// further downstream clients may need to reverse masking decisions made
197 /// upstream, in a manner that is robust to many kinds of future changes to
198 /// the upstream data.
199 ///
200 /// See ActivateId(), ActivateIds(), DeactivateId(), DeactivateIds(),
201 /// ActivateAllIds()
202 ///
203 /// \subsection UsdGeomPointInstancer_invisibleIds invisibleIds: Animatable Masking
204 ///
205 /// The second masking feature encodes a list of IDs in a time-varying
206 /// Int64Array-valued UsdAttribute called \em invisibleIds , since it shares
207 /// with \ref UsdGeomImageable::GetVisibilityAttr() "Imageable visibility"
208 /// the ability to animate object visibility.
209 ///
210 /// Unlike \em inactiveIds, overriding a set of opinions for \em invisibleIds
211 /// is not at all straightforward, because one will, in general need to
212 /// reauthor (in the overriding layer) **all** timeSamples for the attribute
213 /// just to change one Id's visibility state, so it cannot be authored
214 /// sparsely. But it can be a very useful tool for situations like encoding
215 /// pre-computed camera-frustum culling of geometry when either or both of
216 /// the instances or the camera is animated.
217 ///
218 /// See VisId(), VisIds(), InvisId(), InvisIds(), VisAllIds()
219 ///
220 /// \section UsdGeomPointInstancer_protoProcessing Processing and Not Processing Prototypes
221 ///
222 /// Any prim in the scenegraph can be targeted as a prototype by the
223 /// \em prototypes relationship. We do not, however, provide a specific
224 /// mechanism for identifying prototypes as geometry that should not be drawn
225 /// (or processed) in their own, local spaces in the scenegraph. We
226 /// encourage organizing all prototypes as children of the PointInstancer
227 /// prim that consumes them, and pruning "raw" processing and drawing
228 /// traversals when they encounter a PointInstancer prim; this is what the
229 /// UsdGeomBBoxCache and UsdImaging engines do.
230 ///
231 /// There \em is a pattern one can deploy for organizing the prototypes
232 /// such that they will automatically be skipped by basic UsdPrim::GetChildren()
233 /// or UsdPrimRange traversals. Usd prims each have a
234 /// \ref Usd_PrimSpecifiers "specifier" of "def", "over", or "class". The
235 /// default traversals skip over prims that are "pure overs" or classes. So
236 /// to protect prototypes from all generic traversals and processing, place
237 /// them under a prim that is just an "over". For example,
238 /// \code
239 /// 01 def PointInstancer "Crowd_Mid"
240 /// 02 {
241 /// 03 rel prototypes = [ </Crowd_Mid/Prototypes/MaleThin_Business>, </Crowd_Mid/Prototypes/MaleThin_Casual> ]
242 /// 04
243 /// 05 over "Prototypes"
244 /// 06 {
245 /// 07 def "MaleThin_Business" (
246 /// 08 references = [@MaleGroupA/usd/MaleGroupA.usd@</MaleGroupA>]
247 /// 09 variants = {
248 /// 10 string modelingVariant = "Thin"
249 /// 11 string costumeVariant = "BusinessAttire"
250 /// 12 }
251 /// 13 )
252 /// 14 { ... }
253 /// 15
254 /// 16 def "MaleThin_Casual"
255 /// 17 ...
256 /// 18 }
257 /// 19 }
258 /// \endcode
259 ///
260 ///
262 {
263 public:
264  /// Compile time constant representing what kind of schema this class is.
265  ///
266  /// \sa UsdSchemaKind
268 
269  /// Construct a UsdGeomPointInstancer on UsdPrim \p prim .
270  /// Equivalent to UsdGeomPointInstancer::Get(prim.GetStage(), prim.GetPath())
271  /// for a \em valid \p prim, but will not immediately throw an error for
272  /// an invalid \p prim
273  explicit UsdGeomPointInstancer(const UsdPrim& prim=UsdPrim())
274  : UsdGeomBoundable(prim)
275  {
276  }
277 
278  /// Construct a UsdGeomPointInstancer on the prim held by \p schemaObj .
279  /// Should be preferred over UsdGeomPointInstancer(schemaObj.GetPrim()),
280  /// as it preserves SchemaBase state.
281  explicit UsdGeomPointInstancer(const UsdSchemaBase& schemaObj)
282  : UsdGeomBoundable(schemaObj)
283  {
284  }
285 
286  /// Destructor.
288  virtual ~UsdGeomPointInstancer();
289 
290  /// Return a vector of names of all pre-declared attributes for this schema
291  /// class and all its ancestor classes. Does not include attributes that
292  /// may be authored by custom/extended methods of the schemas involved.
294  static const TfTokenVector &
295  GetSchemaAttributeNames(bool includeInherited=true);
296 
297  /// Return a UsdGeomPointInstancer holding the prim adhering to this
298  /// schema at \p path on \p stage. If no prim exists at \p path on
299  /// \p stage, or if the prim at that path does not adhere to this schema,
300  /// return an invalid schema object. This is shorthand for the following:
301  ///
302  /// \code
303  /// UsdGeomPointInstancer(stage->GetPrimAtPath(path));
304  /// \endcode
305  ///
307  static UsdGeomPointInstancer
308  Get(const UsdStagePtr &stage, const SdfPath &path);
309 
310  /// Attempt to ensure a \a UsdPrim adhering to this schema at \p path
311  /// is defined (according to UsdPrim::IsDefined()) on this stage.
312  ///
313  /// If a prim adhering to this schema at \p path is already defined on this
314  /// stage, return that prim. Otherwise author an \a SdfPrimSpec with
315  /// \a specifier == \a SdfSpecifierDef and this schema's prim type name for
316  /// the prim at \p path at the current EditTarget. Author \a SdfPrimSpec s
317  /// with \p specifier == \a SdfSpecifierDef and empty typeName at the
318  /// current EditTarget for any nonexistent, or existing but not \a Defined
319  /// ancestors.
320  ///
321  /// The given \a path must be an absolute prim path that does not contain
322  /// any variant selections.
323  ///
324  /// If it is impossible to author any of the necessary PrimSpecs, (for
325  /// example, in case \a path cannot map to the current UsdEditTarget's
326  /// namespace) issue an error and return an invalid \a UsdPrim.
327  ///
328  /// Note that this method may return a defined prim whose typeName does not
329  /// specify this schema class, in case a stronger typeName opinion overrides
330  /// the opinion at the current EditTarget.
331  ///
333  static UsdGeomPointInstancer
334  Define(const UsdStagePtr &stage, const SdfPath &path);
335 
336 protected:
337  /// Returns the kind of schema this class belongs to.
338  ///
339  /// \sa UsdSchemaKind
341  UsdSchemaKind _GetSchemaKind() const override;
342 
343 private:
344  // needs to invoke _GetStaticTfType.
345  friend class UsdSchemaRegistry;
347  static const TfType &_GetStaticTfType();
348 
349  static bool _IsTypedSchema();
350 
351  // override SchemaBase virtuals.
353  const TfType &_GetTfType() const override;
354 
355 public:
356  // --------------------------------------------------------------------- //
357  // PROTOINDICES
358  // --------------------------------------------------------------------- //
359  /// <b>Required property</b>. Per-instance index into
360  /// \em prototypes relationship that identifies what geometry should be
361  /// drawn for each instance. <b>Topology attribute</b> - can be animated,
362  /// but at a potential performance impact for streaming.
363  ///
364  /// | ||
365  /// | -- | -- |
366  /// | Declaration | `int[] protoIndices` |
367  /// | C++ Type | VtArray<int> |
368  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->IntArray |
371 
372  /// See GetProtoIndicesAttr(), and also
373  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
374  /// If specified, author \p defaultValue as the attribute's default,
375  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
376  /// the default for \p writeSparsely is \c false.
378  UsdAttribute CreateProtoIndicesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
379 
380 public:
381  // --------------------------------------------------------------------- //
382  // IDS
383  // --------------------------------------------------------------------- //
384  /// Ids are optional; if authored, the ids array should be the same
385  /// length as the \em protoIndices array, specifying (at each timeSample if
386  /// instance identities are changing) the id of each instance. The
387  /// type is signed intentionally, so that clients can encode some
388  /// binary state on Id'd instances without adding a separate primvar.
389  /// See also \ref UsdGeomPointInstancer_varyingTopo
390  ///
391  /// | ||
392  /// | -- | -- |
393  /// | Declaration | `int64[] ids` |
394  /// | C++ Type | VtArray<int64_t> |
395  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Int64Array |
397  UsdAttribute GetIdsAttr() const;
398 
399  /// See GetIdsAttr(), and also
400  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
401  /// If specified, author \p defaultValue as the attribute's default,
402  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
403  /// the default for \p writeSparsely is \c false.
405  UsdAttribute CreateIdsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
406 
407 public:
408  // --------------------------------------------------------------------- //
409  // POSITIONS
410  // --------------------------------------------------------------------- //
411  /// <b>Required property</b>. Per-instance position. See also
412  /// \ref UsdGeomPointInstancer_transform .
413  ///
414  /// | ||
415  /// | -- | -- |
416  /// | Declaration | `point3f[] positions` |
417  /// | C++ Type | VtArray<GfVec3f> |
418  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Point3fArray |
421 
422  /// See GetPositionsAttr(), and also
423  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
424  /// If specified, author \p defaultValue as the attribute's default,
425  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
426  /// the default for \p writeSparsely is \c false.
428  UsdAttribute CreatePositionsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
429 
430 public:
431  // --------------------------------------------------------------------- //
432  // ORIENTATIONS
433  // --------------------------------------------------------------------- //
434  /// If authored, per-instance orientation of each instance about its
435  /// prototype's origin, represented as a unit length quaternion, which
436  /// allows us to encode it with sufficient precision in a compact GfQuath.
437  ///
438  /// It is client's responsibility to ensure that authored quaternions are
439  /// unit length; the convenience API below for authoring orientations from
440  /// rotation matrices will ensure that quaternions are unit length, though
441  /// it will not make any attempt to select the "better (for interpolation
442  /// with respect to neighboring samples)" of the two possible quaternions
443  /// that encode the rotation.
444  ///
445  /// See also \ref UsdGeomPointInstancer_transform .
446  ///
447  /// | ||
448  /// | -- | -- |
449  /// | Declaration | `quath[] orientations` |
450  /// | C++ Type | VtArray<GfQuath> |
451  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->QuathArray |
454 
455  /// See GetOrientationsAttr(), and also
456  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
457  /// If specified, author \p defaultValue as the attribute's default,
458  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
459  /// the default for \p writeSparsely is \c false.
461  UsdAttribute CreateOrientationsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
462 
463 public:
464  // --------------------------------------------------------------------- //
465  // ORIENTATIONSF
466  // --------------------------------------------------------------------- //
467  /// If authored, per-instance orientation of each instance about its
468  /// prototype's origin, represented as a unit length quaternion, encoded
469  /// as a GfQuatf to support higher precision computations.
470  ///
471  /// It is client's responsibility to ensure that authored quaternions are
472  /// unit length; the convenience API below for authoring orientations from
473  /// rotation matrices will ensure that quaternions are unit length, though
474  /// it will not make any attempt to select the "better (for interpolation
475  /// with respect to neighboring samples)" of the two possible quaternions
476  /// that encode the rotation. Note that if the earliest time sample (or
477  /// default value if there are no time samples) of orientationsf is not empty
478  /// orientationsf will be preferred over orientations if both are authored.
479  ///
480  /// See also \ref UsdGeomPointInstancer_transform .
481  ///
482  /// | ||
483  /// | -- | -- |
484  /// | Declaration | `quatf[] orientationsf` |
485  /// | C++ Type | VtArray<GfQuatf> |
486  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->QuatfArray |
489 
490  /// See GetOrientationsfAttr(), and also
491  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
492  /// If specified, author \p defaultValue as the attribute's default,
493  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
494  /// the default for \p writeSparsely is \c false.
496  UsdAttribute CreateOrientationsfAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
497 
498 public:
499  // --------------------------------------------------------------------- //
500  // SCALES
501  // --------------------------------------------------------------------- //
502  /// If authored, per-instance scale to be applied to
503  /// each instance, before any rotation is applied.
504  ///
505  /// See also \ref UsdGeomPointInstancer_transform .
506  ///
507  /// | ||
508  /// | -- | -- |
509  /// | Declaration | `float3[] scales` |
510  /// | C++ Type | VtArray<GfVec3f> |
511  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Float3Array |
513  UsdAttribute GetScalesAttr() const;
514 
515  /// See GetScalesAttr(), and also
516  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
517  /// If specified, author \p defaultValue as the attribute's default,
518  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
519  /// the default for \p writeSparsely is \c false.
521  UsdAttribute CreateScalesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
522 
523 public:
524  // --------------------------------------------------------------------- //
525  // VELOCITIES
526  // --------------------------------------------------------------------- //
527  /// If provided, per-instance 'velocities' will be used to
528  /// compute positions between samples for the 'positions' attribute,
529  /// rather than interpolating between neighboring 'positions' samples.
530  /// Velocities should be considered mandatory if both \em protoIndices
531  /// and \em positions are animated. Velocity is measured in position
532  /// units per second, as per most simulation software. To convert to
533  /// position units per UsdTimeCode, divide by
534  /// UsdStage::GetTimeCodesPerSecond().
535  ///
536  /// See also \ref UsdGeomPointInstancer_transform,
537  /// \ref UsdGeom_VelocityInterpolation .
538  ///
539  /// | ||
540  /// | -- | -- |
541  /// | Declaration | `vector3f[] velocities` |
542  /// | C++ Type | VtArray<GfVec3f> |
543  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Vector3fArray |
546 
547  /// See GetVelocitiesAttr(), and also
548  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
549  /// If specified, author \p defaultValue as the attribute's default,
550  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
551  /// the default for \p writeSparsely is \c false.
553  UsdAttribute CreateVelocitiesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
554 
555 public:
556  // --------------------------------------------------------------------- //
557  // ACCELERATIONS
558  // --------------------------------------------------------------------- //
559  /// If authored, per-instance 'accelerations' will be used with
560  /// velocities to compute positions between samples for the 'positions'
561  /// attribute rather than interpolating between neighboring 'positions'
562  /// samples. Acceleration is measured in position units per second-squared.
563  /// To convert to position units per squared UsdTimeCode, divide by the
564  /// square of UsdStage::GetTimeCodesPerSecond().
565  ///
566  /// | ||
567  /// | -- | -- |
568  /// | Declaration | `vector3f[] accelerations` |
569  /// | C++ Type | VtArray<GfVec3f> |
570  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Vector3fArray |
573 
574  /// See GetAccelerationsAttr(), and also
575  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
576  /// If specified, author \p defaultValue as the attribute's default,
577  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
578  /// the default for \p writeSparsely is \c false.
580  UsdAttribute CreateAccelerationsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
581 
582 public:
583  // --------------------------------------------------------------------- //
584  // ANGULARVELOCITIES
585  // --------------------------------------------------------------------- //
586  /// If authored, per-instance angular velocity vector to be used for
587  /// interoplating orientations. Angular velocities should be considered
588  /// mandatory if both \em protoIndices and \em orientations are animated.
589  /// Angular velocity is measured in <b>degrees</b> per second. To convert
590  /// to degrees per UsdTimeCode, divide by
591  /// UsdStage::GetTimeCodesPerSecond().
592  ///
593  /// See also \ref UsdGeomPointInstancer_transform .
594  ///
595  /// | ||
596  /// | -- | -- |
597  /// | Declaration | `vector3f[] angularVelocities` |
598  /// | C++ Type | VtArray<GfVec3f> |
599  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Vector3fArray |
602 
603  /// See GetAngularVelocitiesAttr(), and also
604  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
605  /// If specified, author \p defaultValue as the attribute's default,
606  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
607  /// the default for \p writeSparsely is \c false.
609  UsdAttribute CreateAngularVelocitiesAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
610 
611 public:
612  // --------------------------------------------------------------------- //
613  // INVISIBLEIDS
614  // --------------------------------------------------------------------- //
615  /// A list of id's to make invisible at the evaluation time.
616  /// See \ref UsdGeomPointInstancer_invisibleIds .
617  ///
618  /// | ||
619  /// | -- | -- |
620  /// | Declaration | `int64[] invisibleIds = []` |
621  /// | C++ Type | VtArray<int64_t> |
622  /// | \ref Usd_Datatypes "Usd Type" | SdfValueTypeNames->Int64Array |
625 
626  /// See GetInvisibleIdsAttr(), and also
627  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create.
628  /// If specified, author \p defaultValue as the attribute's default,
629  /// sparsely (when it makes sense to do so) if \p writeSparsely is \c true -
630  /// the default for \p writeSparsely is \c false.
632  UsdAttribute CreateInvisibleIdsAttr(VtValue const &defaultValue = VtValue(), bool writeSparsely=false) const;
633 
634 public:
635  // --------------------------------------------------------------------- //
636  // PROTOTYPES
637  // --------------------------------------------------------------------- //
638  /// <b>Required property</b>. Orders and targets the prototype root
639  /// prims, which can be located anywhere in the scenegraph that is convenient,
640  /// although we promote organizing prototypes as children of the
641  /// PointInstancer. The position of a prototype in this relationship defines
642  /// the value an instance would specify in the \em protoIndices attribute to
643  /// instance that prototype. Since relationships are uniform, this property
644  /// cannot be animated.
645  ///
648 
649  /// See GetPrototypesRel(), and also
650  /// \ref Usd_Create_Or_Get_Property for when to use Get vs Create
653 
654 public:
655  // ===================================================================== //
656  // Feel free to add custom code below this line, it will be preserved by
657  // the code generator.
658  //
659  // Just remember to:
660  // - Close the class declaration with };
661  // - Close the namespace with PXR_NAMESPACE_CLOSE_SCOPE
662  // - Close the include guard with #endif
663  // ===================================================================== //
664  // --(BEGIN CUSTOM CODE)--
665 
666  // --------------------------------------------------------------------- //
667  /// \name Id-based Instance Masking/Pruning
668  /// See \ref UsdGeomPointInstancer_masking
669  /// @{
670  // --------------------------------------------------------------------- //
671 
672  /// Ensure that the instance identified by \p id is active over all time.
673  /// This activation is encoded sparsely, affecting no other instances.
674  ///
675  /// This does not guarantee that the instance will be rendered, because
676  /// it may still be "invisible" due to \p id being present in the
677  /// \em invisibleIds attribute (see VisId(), InvisId())
679  bool ActivateId(int64_t id) const;
680 
681  /// Ensure that the instances identified by \p ids are active over all time.
682  /// This activation is encoded sparsely, affecting no other instances.
683  ///
684  /// This does not guarantee that the instances will be rendered, because
685  /// each may still be "invisible" due to its presence in the
686  /// \em invisibleIds attribute (see VisId(), InvisId())
688  bool ActivateIds(VtInt64Array const &ids) const;
689 
690  /// Ensure that all instances are active over all time.
691  ///
692  /// This does not guarantee that the instances will be rendered, because
693  /// each may still be "invisible" due to its presence in the
694  /// \em invisibleIds attribute (see VisId(), InvisId())
696  bool ActivateAllIds() const;
697 
698  /// Ensure that the instance identified by \p id is inactive over all time.
699  /// This deactivation is encoded sparsely, affecting no other instances.
700  ///
701  /// A deactivated instance is guaranteed not to render if the renderer
702  /// honors masking.
704  bool DeactivateId(int64_t id) const;
705 
706  /// Ensure that the instances identified by \p ids are inactive over all time.
707  /// This deactivation is encoded sparsely, affecting no other instances.
708  ///
709  /// A deactivated instance is guaranteed not to render if the renderer
710  /// honors masking.
712  bool DeactivateIds(VtInt64Array const &ids) const;
713 
714 
715  /// Ensure that the instance identified by \p id is visible at \p time.
716  /// This will cause \em invisibleIds to first be broken down (keyed)
717  /// at \p time, causing all animation in weaker layers that the current
718  /// UsdEditTarget to be overridden. Has no effect on any timeSamples other
719  /// than the one at \p time. If the \em invisibleIds attribute is not
720  /// authored or is blocked, this operation is a no-op.
721  ///
722  /// This does not guarantee that the instance will be rendered, because
723  /// it may still be "inactive" due to \p id being present in the
724  /// \em inactivevIds metadata (see ActivateId(), DeactivateId())
726  bool VisId(int64_t id, UsdTimeCode const &time) const;
727 
728  /// Ensure that the instances identified by \p ids are visible at \p time.
729  /// This will cause \em invisibleIds to first be broken down (keyed)
730  /// at \p time, causing all animation in weaker layers that the current
731  /// UsdEditTarget to be overridden. Has no effect on any timeSamples other
732  /// than the one at \p time. If the \em invisibleIds attribute is not
733  /// authored or is blocked, this operation is a no-op.
734  ///
735  /// This does not guarantee that the instances will be rendered, because
736  /// each may still be "inactive" due to \p id being present in the
737  /// \em inactivevIds metadata (see ActivateId(), DeactivateId())
739  bool VisIds(VtInt64Array const &ids, UsdTimeCode const &time) const;
740 
741  /// Ensure that all instances are visible at \p time.
742  /// Operates by authoring an empty array at \p time.
743  ///
744  /// This does not guarantee that the instances will be rendered, because
745  /// each may still be "inactive" due to its id being present in the
746  /// \em inactivevIds metadata (see ActivateId(), DeactivateId())
748  bool VisAllIds(UsdTimeCode const &time) const;
749 
750  /// Ensure that the instance identified by \p id is invisible at \p time.
751  /// This will cause \em invisibleIds to first be broken down (keyed)
752  /// at \p time, causing all animation in weaker layers that the current
753  /// UsdEditTarget to be overridden. Has no effect on any timeSamples other
754  /// than the one at \p time.
755  ///
756  /// An invised instance is guaranteed not to render if the renderer
757  /// honors masking.
759  bool InvisId(int64_t id, UsdTimeCode const &time) const;
760 
761  /// Ensure that the instances identified by \p ids are invisible at \p time.
762  /// This will cause \em invisibleIds to first be broken down (keyed)
763  /// at \p time, causing all animation in weaker layers that the current
764  /// UsdEditTarget to be overridden. Has no effect on any timeSamples other
765  /// than the one at \p time.
766  ///
767  /// An invised instance is guaranteed not to render if the renderer
768  /// honors masking.
770  bool InvisIds(VtInt64Array const &ids, UsdTimeCode const &time) const;
771 
772  /// Computes a presence mask to be applied to per-instance data arrays
773  /// based on authored \em inactiveIds, \em invisibleIds, and \em ids .
774  ///
775  /// If no \em ids attribute has been authored, then the values in
776  /// \em inactiveIds and \em invisibleIds will be interpreted directly
777  /// as indices of \em protoIndices .
778  ///
779  /// If \p ids is non-NULL, it is assumed to be the id-mapping to apply,
780  /// and must match the length of \em protoIndices at \p time .
781  /// If NULL, we will call GetIdsAttr().Get(time)
782  ///
783  /// \note If all "live" instances at UsdTimeCode \p time pass the mask,
784  /// we will return an <b>empty</b> mask so that clients can trivially
785  /// recognize the common "no masking" case.
786  ///
787  /// The returned mask can be used with ApplyMaskToArray(), and will contain
788  /// a \c true value for every element that should survive.
790  std::vector<bool> ComputeMaskAtTime(UsdTimeCode time,
791  VtInt64Array const *ids = nullptr) const;
792 
793  /// Contract \p dataArray in-place to contain only the elements whose
794  /// index in \p mask is \c true.
795  ///
796  /// \note an empty \p mask specifies "all pass", in which case \p dataArray
797  /// is trivially unmodified
798  ///
799  /// - It is an error for \p dataArray to be NULL .
800  /// - If \em elementSize times \em mask.size() does not equal
801  /// \em dataArray->size(), warn and fail.
802  ///
803  /// \return true on success, false on failure.
804  /// \sa ComputeMaskAtTime()
805  template <class T>
806  static bool ApplyMaskToArray(std::vector<bool> const &mask,
807  VtArray<T> *dataArray,
808  const int elementSize = 1);
809 
810  /// Determines if we should prefer orientationsf over orientations
811  /// based on whether or not orientationsf has been authored to a non
812  /// empty array. Assumes that orientationsf is empty if the earliest time
813  /// sample or default value if there are no time samples are empty
814  ///
815  /// \param rotationsAttr the outparameter for the corresponding attribute. If
816  /// this function returns true then orientationsf will be
817  /// stored in rotationsAttr, and orientations if not
819  bool UsesOrientationsf(UsdAttribute *rotationsAttr) const;
820 
821  /// \overload same functionality as
822  /// UsesOrientationsf(UsdAttribute &rotationsAttr) but populates a
823  /// TfToken instead
824  ///
825  /// \param rotationsToken (optional) the outparameter for the corresponding
826  /// attribute. If this function returns true then
827  /// UsdGeomTokens->orientationsf will be stored in UsdToken,
828  /// and UsdGeomTokens->orientations if not
830  bool UsesOrientationsf(TfToken *rotationsToken = nullptr) const;
831 
832  // --------------------------------------------------------------------- //
833  /// @}
834  // --------------------------------------------------------------------- //
835 
836  /// \enum ProtoXformInclusion
837  ///
838  /// Encodes whether to include each prototype's root prim's transformation
839  /// as the most-local component of computed instance transforms.
841  IncludeProtoXform, //!< Include the transform on the proto's root
842  ExcludeProtoXform //!< Exclude the transform on the proto's root
843  };
844 
845 
846  /// \enum MaskApplication
847  ///
848  /// Encodes whether to evaluate and apply the PointInstancer's
849  /// mask to computed results.
850  /// \sa ComputeMaskAtTime()
852  ApplyMask, //!< Compute and apply the PointInstancer mask
853  IgnoreMask //!< Ignore the PointInstancer mask
854  };
855 
856 
857  /// Compute the per-instance, "PointInstancer relative" transforms given
858  /// the positions, scales, orientations, velocities and angularVelocities
859  /// at \p time, as described in \ref UsdGeomPointInstancer_transform .
860  ///
861  /// This will return \c false and leave \p xforms untouched if:
862  /// - \p xforms is NULL
863  /// - one of \p time and \p baseTime is numeric and the other is
864  /// UsdTimeCode::Default() (they must either both be numeric or both be
865  /// default)
866  /// - there is no authored \em protoIndices attribute or \em positions
867  /// attribute
868  /// - the size of any of the per-instance attributes does not match the
869  /// size of \em protoIndices
870  /// - \p doProtoXforms is \c IncludeProtoXform but an index value in
871  /// \em protoIndices is outside the range [0, prototypes.size())
872  /// - \p applyMask is \c ApplyMask and a mask is set but the size of the
873  /// mask does not match the size of \em protoIndices.
874  ///
875  /// If there is no error, we will return \c true and \p xforms will contain
876  /// the computed transformations.
877  ///
878  /// \param xforms - the out parameter for the transformations. Its size
879  /// will depend on the authored data and \p applyMask
880  /// \param time - UsdTimeCode at which we want to evaluate the transforms
881  /// \param baseTime - required for correct interpolation between samples
882  /// when \em velocities or \em angularVelocities are
883  /// present. If there are samples for \em positions and
884  /// \em velocities at t1 and t2, normal value resolution
885  /// would attempt to interpolate between the two samples,
886  /// and if they could not be interpolated because they
887  /// differ in size (common in cases where velocity is
888  /// authored), will choose the sample at t1. When
889  /// sampling for the purposes of motion-blur, for example,
890  /// it is common, when rendering the frame at t2, to
891  /// sample at [ t2-shutter/2, t2+shutter/2 ] for a
892  /// shutter interval of \em shutter. The first sample
893  /// falls between t1 and t2, but we must sample at t2
894  /// and apply velocity-based interpolation based on those
895  /// samples to get a correct result. In such scenarios,
896  /// one should provide a \p baseTime of t2 when querying
897  /// \em both samples. If your application does not care
898  /// about off-sample interpolation, it can supply the
899  /// same value for \p baseTime that it does for \p time.
900  /// When \p baseTime is less than or equal to \p time,
901  /// we will choose the lower bracketing timeSample.
902  /// Selecting sample times with respect to baseTime will
903  /// be performed independently for positions and
904  /// orientations.
905  /// \param doProtoXforms - specifies whether to include the root
906  /// transformation of each instance's prototype in the
907  /// instance's transform. Default is to include it, but
908  /// some clients may want to apply the proto transform as
909  /// part of the prototype itself, so they can specify
910  /// \c ExcludeProtoXform instead.
911  /// \param applyMask - specifies whether to apply ApplyMaskToArray() to the
912  /// computed result. The default is \c ApplyMask.
914  bool
916  VtArray<GfMatrix4d>* xforms,
917  const UsdTimeCode time,
918  const UsdTimeCode baseTime,
919  const ProtoXformInclusion doProtoXforms = IncludeProtoXform,
920  const MaskApplication applyMask = ApplyMask) const;
921 
922  /// Compute the per-instance transforms as in
923  /// ComputeInstanceTransformsAtTime, but using multiple sample times. An
924  /// array of matrix arrays is returned where each matrix array contains the
925  /// instance transforms for the corresponding time in \p times .
926  ///
927  /// \param times - A vector containing the UsdTimeCodes at which we want to
928  /// sample.
930  bool
932  std::vector<VtArray<GfMatrix4d>>* xformsArray,
933  const std::vector<UsdTimeCode>& times,
934  const UsdTimeCode baseTime,
935  const ProtoXformInclusion doProtoXforms = IncludeProtoXform,
936  const MaskApplication applyMask = ApplyMask) const;
937 
938  /// \overload
939  /// Perform the per-instance transform computation as described in
940  /// \ref UsdGeomPointInstancer_transform . This does the same computation as
941  /// the non-static ComputeInstanceTransformsAtTime method, but takes all
942  /// data as parameters rather than accessing authored data.
943  ///
944  /// \param xforms - the out parameter for the transformations. Its size
945  /// will depend on the given data and \p applyMask
946  /// \param stage - the UsdStage
947  /// \param time - time at which we want to evaluate the transforms
948  /// \param protoIndices - array containing all instance prototype indices.
949  /// \param positions - array containing all instance positions. This array
950  /// must be the same size as \p protoIndices .
951  /// \param velocities - array containing all instance velocities. This array
952  /// must be either the same size as \p protoIndices or
953  /// empty. If it is empty, transforms are computed as if
954  /// all velocities were zero in all dimensions.
955  /// \param velocitiesSampleTime - time at which the samples from
956  /// \p velocities were taken.
957  /// \param accelerations - array containing all instance accelerations.
958  /// This array must be either the same size as
959  /// \p protoIndicesor empty. If it is empty, transforms
960  /// are computed as if all accelerations were zero in
961  /// all dimensions.
962  /// \param scales - array containing all instance scales. This array must be
963  /// either the same size as \p protoIndices or empty. If it
964  /// is empty, transforms are computed with no change in
965  /// scale.
966  /// \param orientations - array containing all instance orientations. This
967  /// array must be either the same size as
968  /// \p protoIndices or empty. If it is empty,
969  /// transforms are computed with no change in
970  /// orientation
971  /// \param angularVelocities - array containing all instance angular
972  /// velocities. This array must be either the
973  /// same size as \p protoIndices or empty. If it
974  /// is empty, transforms are computed as if all
975  /// angular velocities were zero in all
976  /// dimensions.
977  /// \param angularVelocitiesSampleTime - time at which the samples from
978  /// \p angularVelocities were taken.
979  /// \param protoPaths - array containing the paths for all instance
980  /// prototypes. If this array is not empty, prototype
981  /// transforms are applied to the instance transforms.
982  /// \param mask - vector containing a mask to apply to the computed result.
983  /// This vector must be either the same size as
984  /// \p protoIndices or empty. If it is empty, no mask is
985  /// applied.
986  /// \param velocityScale - \deprecated.
988  static bool
990  VtArray<GfMatrix4d>* xforms,
991  UsdStageWeakPtr& stage,
993  const VtIntArray& protoIndices,
994  const VtVec3fArray& positions,
995  const VtVec3fArray& velocities,
996  UsdTimeCode velocitiesSampleTime,
997  const VtVec3fArray& accelerations,
998  const VtVec3fArray& scales,
999  const VtQuatfArray& orientations,
1000  const VtVec3fArray& angularVelocities,
1001  UsdTimeCode angularVelocitiesSampleTime,
1002  const SdfPathVector& protoPaths,
1003  const std::vector<bool>& mask,
1004  float velocityScale = 1.0);
1005 
1006  /// \overload Perform the per-instance transform computation as described
1007  /// in \ref UsdGeomPointInstancer_transform . This does the same
1008  /// computation as the static ComputeInstanceTransformsAtTime method, but
1009  /// supports half precision rotations
1010  USDGEOM_API
1011  static bool
1013  VtArray<GfMatrix4d>* xforms,
1014  UsdStageWeakPtr& stage,
1015  UsdTimeCode time,
1016  const VtIntArray& protoIndices,
1017  const VtVec3fArray& positions,
1018  const VtVec3fArray& velocities,
1019  UsdTimeCode velocitiesSampleTime,
1020  const VtVec3fArray& accelerations,
1021  const VtVec3fArray& scales,
1022  const VtQuathArray& orientations,
1023  const VtVec3fArray& angularVelocities,
1024  UsdTimeCode angularVelocitiesSampleTime,
1025  const SdfPathVector& protoPaths,
1026  const std::vector<bool>& mask,
1027  float velocityScale = 1.0);
1028 
1029 private:
1030 
1031  // Get the authored prototype paths. Fail if there are no authored prototype
1032  // paths or the prototype indices are out of bounds.
1033  bool _GetPrototypePathsForInstanceTransforms(
1034  const VtIntArray& protoIndices,
1035  SdfPathVector* protoPaths) const;
1036 
1037  // Get the authored prototype indices for instance transform computation.
1038  // Fail if prototype indices are not authored.
1039  bool _GetProtoIndicesForInstanceTransforms(
1040  UsdTimeCode baseTime,
1041  VtIntArray* protoIndices) const;
1042 
1043  // Fetches data from attributes specific to UsdGeomPointInstancer
1044  // required for instance transform calculations; this includes
1045  // protoIndices, protoPaths, and the mask.
1046  bool _ComputePointInstancerAttributesPreamble(
1047  const UsdTimeCode baseTime,
1048  const ProtoXformInclusion doProtoXforms,
1049  const MaskApplication applyMask,
1050  VtIntArray* protoIndices,
1051  SdfPathVector* protoPaths,
1052  std::vector<bool>* mask) const;
1053 
1054  /// Compute the per-instance transforms as in
1055  /// ComputeInstanceTransformsAtTime, but using multiple sample times.
1056  /// Returns am array of matrix arrays where each matrix array contains the
1057  /// instance transforms for the corresponding time in \p times . Templated
1058  /// to support both full and half precision rotations.
1059  template<class QuatType>
1060  bool _DoComputeInstanceTransformsAtTimes(
1061  std::vector<VtArray<GfMatrix4d>>* xformsArray,
1062  const std::vector<UsdTimeCode>& times,
1063  const UsdTimeCode baseTime,
1064  const ProtoXformInclusion doProtoXforms,
1065  const MaskApplication applyMask,
1066  const UsdAttribute orientationsAttr) const;
1067 
1068  /// Helper implementation for static ComputeInstanceTransformsAtTime
1069  template <class QuatType>
1070  static bool _DoComputeInstanceTransformsAtTime(
1071  VtArray<GfMatrix4d>* xforms,
1072  UsdStageWeakPtr& stage,
1073  UsdTimeCode time,
1074  const VtIntArray& protoIndices,
1075  const VtVec3fArray& positions,
1076  const VtVec3fArray& velocities,
1077  UsdTimeCode velocitiesSampleTime,
1078  const VtVec3fArray& accelerations,
1079  const VtVec3fArray& scales,
1080  const VtArray<QuatType>& orientations,
1081  const VtVec3fArray& angularVelocities,
1082  UsdTimeCode angularVelocitiesSampleTime,
1083  const SdfPathVector& protoPaths,
1084  const std::vector<bool>& mask,
1085  float velocityScale = 1.0);
1086 
1087 public:
1088 
1089  /// Compute the extent of the point instancer based on the per-instance,
1090  /// "PointInstancer relative" transforms at \p time, as described in
1091  /// \ref UsdGeomPointInstancer_transform .
1092  ///
1093  /// If there is no error, we return \c true and \p extent will be the
1094  /// tightest bounds we can compute efficiently. If an error occurs,
1095  /// \c false will be returned and \p extent will be left untouched.
1096  ///
1097  /// For now, this uses a UsdGeomBBoxCache with the "default", "proxy", and
1098  /// "render" purposes.
1099  ///
1100  /// \param extent - the out parameter for the extent. On success, it will
1101  /// contain two elements representing the min and max.
1102  /// \param time - UsdTimeCode at which we want to evaluate the extent
1103  /// \param baseTime - required for correct interpolation between samples
1104  /// when \em velocities or \em angularVelocities are
1105  /// present. If there are samples for \em positions and
1106  /// \em velocities at t1 and t2, normal value resolution
1107  /// would attempt to interpolate between the two samples,
1108  /// and if they could not be interpolated because they
1109  /// differ in size (common in cases where velocity is
1110  /// authored), will choose the sample at t1. When
1111  /// sampling for the purposes of motion-blur, for example,
1112  /// it is common, when rendering the frame at t2, to
1113  /// sample at [ t2-shutter/2, t2+shutter/2 ] for a
1114  /// shutter interval of \em shutter. The first sample
1115  /// falls between t1 and t2, but we must sample at t2
1116  /// and apply velocity-based interpolation based on those
1117  /// samples to get a correct result. In such scenarios,
1118  /// one should provide a \p baseTime of t2 when querying
1119  /// \em both samples. If your application does not care
1120  /// about off-sample interpolation, it can supply the
1121  /// same value for \p baseTime that it does for \p time.
1122  /// When \p baseTime is less than or equal to \p time,
1123  /// we will choose the lower bracketing timeSample.
1124  USDGEOM_API
1125  bool ComputeExtentAtTime(
1126  VtVec3fArray* extent,
1127  const UsdTimeCode time,
1128  const UsdTimeCode baseTime) const;
1129 
1130  /// \overload
1131  /// Computes the extent as if the matrix \p transform was first applied.
1132  USDGEOM_API
1133  bool ComputeExtentAtTime(
1134  VtVec3fArray* extent,
1135  const UsdTimeCode time,
1136  const UsdTimeCode baseTime,
1137  const GfMatrix4d& transform) const;
1138 
1139  /// Compute the extent of the point instancer as in
1140  /// \ref ComputeExtentAtTime , but across multiple \p times . This is
1141  /// equivalent to, but more efficient than, calling ComputeExtentAtTime
1142  /// several times. Each element in \p extents is the computed extent at the
1143  /// corresponding time in \p times .
1144  ///
1145  /// As in \ref ComputeExtentAtTime, if there is no error, we return \c true
1146  /// and \p extents will be the tightest bounds we can compute efficiently.
1147  /// If an error occurs computing the extent at any time, \c false will be
1148  /// returned and \p extents will be left untouched.
1149  ///
1150  /// \param times - A vector containing the UsdTimeCodes at which we want to
1151  /// sample.
1152  USDGEOM_API
1153  bool ComputeExtentAtTimes(
1154  std::vector<VtVec3fArray>* extents,
1155  const std::vector<UsdTimeCode>& times,
1156  const UsdTimeCode baseTime) const;
1157 
1158  /// \overload
1159  /// Computes the extent as if the matrix \p transform was first applied at
1160  /// each time.
1161  USDGEOM_API
1162  bool ComputeExtentAtTimes(
1163  std::vector<VtVec3fArray>* extents,
1164  const std::vector<UsdTimeCode>& times,
1165  const UsdTimeCode baseTime,
1166  const GfMatrix4d& transform) const;
1167 
1168  /// Returns the number of instances as defined by the size of the
1169  /// _protoIndices_ array at _timeCode_.
1170  ///
1171  /// \snippetdoc snippets.dox GetCount
1172  /// \sa GetProtoIndicesAttr()
1173  USDGEOM_API
1174  size_t GetInstanceCount(UsdTimeCode timeCode = UsdTimeCode::Default()) const;
1175 
1176 private:
1177 
1178  bool _ComputeExtentAtTimePreamble(
1179  UsdTimeCode baseTime,
1180  VtIntArray* protoIndices,
1181  std::vector<bool>* mask,
1182  UsdRelationship* prototypes,
1183  SdfPathVector* protoPaths) const;
1184 
1185  bool _ComputeExtentFromTransforms(
1186  VtVec3fArray* extent,
1187  const VtIntArray& protoIndices,
1188  const std::vector<bool>& mask,
1189  const UsdRelationship& prototypes,
1190  const SdfPathVector& protoPaths,
1191  const VtMatrix4dArray& instanceTransforms,
1192  UsdTimeCode time,
1193  const GfMatrix4d* transform) const;
1194 
1195  bool _ComputeExtentAtTime(
1196  VtVec3fArray* extent,
1197  const UsdTimeCode time,
1198  const UsdTimeCode baseTime,
1199  const GfMatrix4d* transform) const;
1200 
1201  bool _ComputeExtentAtTimes(
1202  std::vector<VtVec3fArray>* extent,
1203  const std::vector<UsdTimeCode>& times,
1204  const UsdTimeCode baseTime,
1205  const GfMatrix4d* transform) const;
1206 };
1207 
1208 template <class T>
1209 bool
1211  VtArray<T> *dataArray,
1212  const int elementSize)
1213 {
1214  if (!dataArray) {
1215  TF_CODING_ERROR("NULL dataArray.");
1216  return false;
1217  }
1218  size_t maskSize = mask.size();
1219  if (maskSize == 0 || dataArray->size() == (size_t)elementSize){
1220  return true;
1221  }
1222  else if ((maskSize * elementSize) != dataArray->size()){
1223  TF_WARN("Input mask's size (%zu) is not compatible with the "
1224  "input dataArray (%zu) and elementSize (%d).",
1225  maskSize, dataArray->size(), elementSize);
1226  return false;
1227  }
1228 
1229  T* beginData = dataArray->data();
1230  T* currData = beginData;
1231  size_t numPreserved = 0;
1232  for (size_t i = 0; i < maskSize; ++i) {
1233  // XXX Could add a fast-path for elementSize == 1 ?
1234  if (mask[i]) {
1235  for (int j = 0; j < elementSize; ++j) {
1236  *currData = beginData[i + j];
1237  ++currData;
1238  }
1239  numPreserved += elementSize;
1240  }
1241  }
1242  if (numPreserved < dataArray->size()) {
1243  dataArray->resize(numPreserved);
1244  }
1245  return true;
1246 }
1247 
1248 /// Returns true if list ops should be composed with SdfListOp::ApplyOperations()
1249 /// Returns false if list ops should be composed with SdfListOp::ComposeOperations().
1251 bool
1253 
1254 /// Applies a list operation of type \p op using \p items
1255 /// over the existing list operation on \p prim with the name
1256 /// \p metadataName.
1257 USDGEOM_API
1258 bool
1259 UsdGeomPointInstancerSetOrMergeOverOp(std::vector<int64_t> const &items,
1260  SdfListOpType op,
1261  UsdPrim const &prim,
1262  TfToken const &metadataName);
1263 
1265 
1266 #endif
Exclude the transform on the proto's root.
UsdGeomPointInstancer(const UsdSchemaBase &schemaObj)
Compute and apply the PointInstancer mask.
USDGEOM_API UsdRelationship CreatePrototypesRel() const
USDGEOM_API bool DeactivateIds(VtInt64Array const &ids) const
static constexpr UsdTimeCode Default()
Definition: timeCode.h:113
USDGEOM_API bool ComputeExtentAtTimes(std::vector< VtVec3fArray > *extents, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime) const
USDGEOM_API UsdAttribute CreateOrientationsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GT_API const UT_StringHolder time
USDGEOM_API UsdAttribute CreatePositionsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateIdsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
GLsizei const GLchar *const * path
Definition: glcorearb.h:3341
#define TF_CODING_ERROR
static const UsdSchemaKind schemaKind
USDGEOM_API bool ActivateId(int64_t id) const
USDGEOM_API UsdRelationship GetPrototypesRel() const
USDGEOM_API UsdAttribute CreateAngularVelocitiesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
UsdGeomPointInstancer(const UsdPrim &prim=UsdPrim())
USDGEOM_API UsdAttribute CreateAccelerationsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
UsdStagePtr UsdStageWeakPtr
Definition: common.h:38
USDGEOM_API UsdAttribute CreateScalesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute CreateProtoIndicesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
static bool ApplyMaskToArray(std::vector< bool > const &mask, VtArray< T > *dataArray, const int elementSize=1)
static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames(bool includeInherited=true)
Definition: token.h:70
Represents a concrete typed schema.
USDGEOM_API UsdAttribute GetOrientationsAttr() const
USDGEOM_API UsdAttribute GetPositionsAttr() const
USDGEOM_API bool InvisIds(VtInt64Array const &ids, UsdTimeCode const &time) const
std::vector< class SdfPath > SdfPathVector
SdfListOpType
Definition: listOp.h:29
#define TF_WARN
USDGEOM_API size_t GetInstanceCount(UsdTimeCode timeCode=UsdTimeCode::Default()) const
USDGEOM_API bool UsdGeomPointInstancerSetOrMergeOverOp(std::vector< int64_t > const &items, SdfListOpType op, UsdPrim const &prim, TfToken const &metadataName)
GLint GLuint mask
Definition: glcorearb.h:124
USDGEOM_API UsdAttribute GetScalesAttr() const
USDGEOM_API UsdAttribute GetAccelerationsAttr() const
Definition: prim.h:116
virtual USDGEOM_API ~UsdGeomPointInstancer()
Destructor.
std::vector< TfToken > TfTokenVector
Convenience types.
Definition: token.h:440
USDGEOM_API bool ComputeExtentAtTime(VtVec3fArray *extent, const UsdTimeCode time, const UsdTimeCode baseTime) const
Definition: types.h:153
Definition: path.h:273
static USDGEOM_API UsdGeomPointInstancer Get(const UsdStagePtr &stage, const SdfPath &path)
USDGEOM_API std::vector< bool > ComputeMaskAtTime(UsdTimeCode time, VtInt64Array const *ids=nullptr) const
GA_API const UT_StringHolder transform
USDGEOM_API UsdSchemaKind _GetSchemaKind() const override
USDGEOM_API UsdAttribute CreateInvisibleIdsAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API bool UsdGeomPointInstancerApplyNewStyleListOps()
USDGEOM_API UsdAttribute GetVelocitiesAttr() const
UsdSchemaKind
Definition: common.h:112
GLint j
Definition: glad.h:2733
GLsizeiptr size
Definition: glcorearb.h:664
USDGEOM_API UsdAttribute GetAngularVelocitiesAttr() const
USDGEOM_API bool VisId(int64_t id, UsdTimeCode const &time) const
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
USDGEOM_API UsdAttribute GetInvisibleIdsAttr() const
USDGEOM_API bool ActivateAllIds() const
USDGEOM_API UsdAttribute GetOrientationsfAttr() const
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
USDGEOM_API bool InvisId(int64_t id, UsdTimeCode const &time) const
Definition: type.h:47
static USDGEOM_API UsdGeomPointInstancer Define(const UsdStagePtr &stage, const SdfPath &path)
USDGEOM_API bool VisIds(VtInt64Array const &ids, UsdTimeCode const &time) const
USDGEOM_API bool ActivateIds(VtInt64Array const &ids) const
USDGEOM_API UsdAttribute CreateVelocitiesAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API bool ComputeInstanceTransformsAtTime(VtArray< GfMatrix4d > *xforms, const UsdTimeCode time, const UsdTimeCode baseTime, const ProtoXformInclusion doProtoXforms=IncludeProtoXform, const MaskApplication applyMask=ApplyMask) const
#define USDGEOM_API
Definition: api.h:23
USDGEOM_API bool VisAllIds(UsdTimeCode const &time) const
USDGEOM_API UsdAttribute GetProtoIndicesAttr() const
Ignore the PointInstancer mask.
USDGEOM_API bool UsesOrientationsf(UsdAttribute *rotationsAttr) const
GLuint * ids
Definition: glcorearb.h:652
USDGEOM_API bool ComputeInstanceTransformsAtTimes(std::vector< VtArray< GfMatrix4d >> *xformsArray, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime, const ProtoXformInclusion doProtoXforms=IncludeProtoXform, const MaskApplication applyMask=ApplyMask) const
Definition: value.h:146
USDGEOM_API UsdAttribute CreateOrientationsfAttr(VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
USDGEOM_API UsdAttribute GetIdsAttr() const
USDGEOM_API bool DeactivateId(int64_t id) const
Include the transform on the proto's root.