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