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