This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdGeomPointInstancer Class Reference

Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters), which can be arbitrary prims/subtrees on a UsdStage. More...

#include <pointInstancer.h>

+ Inheritance diagram for UsdGeomPointInstancer:

Public Types

enum  ProtoXformInclusion { IncludeProtoXform , ExcludeProtoXform }
 Encodes whether to include each prototype's root prim's transformation as the most-local component of computed instance transforms. More...
 
enum  MaskApplication { ApplyMask , IgnoreMask }
 Encodes whether to evaluate and apply the PointInstancer's mask to computed results. More...
 

Public Member Functions

 UsdGeomPointInstancer (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomPointInstancer on UsdPrim prim .
 
 UsdGeomPointInstancer (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomPointInstancer on the prim held by schemaObj .
 
virtual USDGEOM_API ~UsdGeomPointInstancer ()
 Destructor.
 
USDGEOM_API UsdAttribute GetProtoIndicesAttr () const
 Required property.
 
USDGEOM_API UsdAttribute CreateProtoIndicesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetProtoIndicesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetIdsAttr () const
 Ids are optional; if authored, the ids array should be the same length as the protoIndices array, specifying (at each timeSample if instance identities are changing) the id of each instance.
 
USDGEOM_API UsdAttribute CreateIdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetIdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetPositionsAttr () const
 Required property.
 
USDGEOM_API UsdAttribute CreatePositionsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetPositionsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetOrientationsAttr () const
 If authored, per-instance orientation of each instance about its prototype's origin, represented as a unit length quaternion, which allows us to encode it with sufficient precision in a compact GfQuath.
 
USDGEOM_API UsdAttribute CreateOrientationsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetOrientationsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetOrientationsfAttr () const
 If authored, per-instance orientation of each instance about its prototype's origin, represented as a unit length quaternion, encoded as a GfQuatf to support higher precision computations.
 
USDGEOM_API UsdAttribute CreateOrientationsfAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetOrientationsfAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetScalesAttr () const
 If authored, per-instance scale to be applied to each instance, before any rotation is applied.
 
USDGEOM_API UsdAttribute CreateScalesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetScalesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetVelocitiesAttr () const
 If provided, per-instance 'velocities' will be used to compute positions between samples for the 'positions' attribute, rather than interpolating between neighboring 'positions' samples.
 
USDGEOM_API UsdAttribute CreateVelocitiesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetVelocitiesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetAccelerationsAttr () const
 If authored, per-instance 'accelerations' will be used with velocities to compute positions between samples for the 'positions' attribute rather than interpolating between neighboring 'positions' samples.
 
USDGEOM_API UsdAttribute CreateAccelerationsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetAccelerationsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetAngularVelocitiesAttr () const
 If authored, per-instance angular velocity vector to be used for interoplating orientations.
 
USDGEOM_API UsdAttribute CreateAngularVelocitiesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetAngularVelocitiesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetInvisibleIdsAttr () const
 A list of id's to make invisible at the evaluation time.
 
USDGEOM_API UsdAttribute CreateInvisibleIdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetInvisibleIdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdRelationship GetPrototypesRel () const
 Required property.
 
USDGEOM_API UsdRelationship CreatePrototypesRel () const
 See GetPrototypesRel(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API bool ComputeInstanceTransformsAtTime (VtArray< GfMatrix4d > *xforms, const UsdTimeCode time, const UsdTimeCode baseTime, const ProtoXformInclusion doProtoXforms=IncludeProtoXform, const MaskApplication applyMask=ApplyMask) const
 Compute the per-instance, "PointInstancer relative" transforms given the positions, scales, orientations, velocities and angularVelocities at time, as described in Computing an Instance Transform .
 
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
 Compute the per-instance transforms as in ComputeInstanceTransformsAtTime, but using multiple sample times.
 
USDGEOM_API bool ComputeExtentAtTime (VtVec3fArray *extent, const UsdTimeCode time, const UsdTimeCode baseTime) const
 Compute the extent of the point instancer based on the per-instance, "PointInstancer relative" transforms at time, as described in Computing an Instance Transform .
 
USDGEOM_API bool ComputeExtentAtTime (VtVec3fArray *extent, const UsdTimeCode time, const UsdTimeCode baseTime, const GfMatrix4d &transform) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix transform was first applied.
 
USDGEOM_API bool ComputeExtentAtTimes (std::vector< VtVec3fArray > *extents, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime) const
 Compute the extent of the point instancer as in ComputeExtentAtTime , but across multiple times .
 
USDGEOM_API bool ComputeExtentAtTimes (std::vector< VtVec3fArray > *extents, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime, const GfMatrix4d &transform) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix transform was first applied at each time.
 
USDGEOM_API size_t GetInstanceCount (UsdTimeCode timeCode=UsdTimeCode::Default()) const
 Returns the number of instances as defined by the size of the protoIndices array at timeCode.
 
- Public Member Functions inherited from UsdGeomBoundable
 UsdGeomBoundable (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomBoundable on UsdPrim prim .
 
 UsdGeomBoundable (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomBoundable on the prim held by schemaObj .
 
virtual USDGEOM_API ~UsdGeomBoundable ()
 Destructor.
 
USDGEOM_API UsdAttribute GetExtentAttr () const
 Extent is a three dimensional range measuring the geometric extent of the authored gprim in its own local space (i.e.
 
USDGEOM_API UsdAttribute CreateExtentAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetExtentAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API bool ComputeExtent (const UsdTimeCode &time, VtVec3fArray *extent) const
 If an extent is authored on this boundable, it queries the extent from the extent attribute, otherwise if ComputeExtentFunction is registered for the boundable's type, it computes the extent at time.
 
- Public Member Functions inherited from UsdGeomXformable
 UsdGeomXformable (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomXformable on UsdPrim prim .
 
 UsdGeomXformable (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomXformable on the prim held by schemaObj .
 
virtual USDGEOM_API ~UsdGeomXformable ()
 Destructor.
 
USDGEOM_API UsdAttribute GetXformOpOrderAttr () const
 Encodes the sequence of transformation operations in the order in which they should be pushed onto a transform stack while visiting a UsdStage's prims in a graph traversal that will effect the desired positioning for this prim and its descendant prims.
 
USDGEOM_API UsdAttribute CreateXformOpOrderAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetXformOpOrderAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdGeomXformOp AddXformOp (UsdGeomXformOp::Type const opType, UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add an affine transformation to the local stack represented by this Xformable.
 
USDGEOM_API UsdGeomXformOp GetXformOp (UsdGeomXformOp::Type const opType, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get an affine transformation from the local stack represented by this Xformable.
 
USDGEOM_API UsdGeomXformOp AddTranslateOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a translate operation to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetTranslateOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a translate operation from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddScaleOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a scale operation to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetScaleOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a scale operation from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation about the X-axis to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation about the X-axis from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation about the Y-axis to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation about the Y-axis from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation about the Z-axis to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation about the Z-axis from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateXYZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with XYZ rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateXYZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with XYZ rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateXZYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with XZY rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateXZYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with XZY rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateYXZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with YXZ rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateYXZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with YXZ rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateYZXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with YZX rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateYZXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with YZX rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateZXYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with ZXY rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateZXYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with ZXY rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddRotateZYXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a rotation op with ZYX rotation order to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetRotateZYXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a rotation op with ZYX rotation order from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddOrientOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a orient op (arbitrary axis/angle rotation) to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetOrientOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get an orient op (arbitrary axis/angle rotation) from the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp AddTransformOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Add a tranform op (4x4 matrix transformation) to the local stack represented by this xformable.
 
USDGEOM_API UsdGeomXformOp GetTransformOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 Get a tranform op (4x4 matrix transformation) from the local stack represented by this xformable.
 
USDGEOM_API bool SetResetXformStack (bool resetXform) const
 Specify whether this prim's transform should reset the transformation stack inherited from its parent prim.
 
USDGEOM_API bool GetResetXformStack () const
 Does this prim reset its parent's inherited transformation?
 
USDGEOM_API bool SetXformOpOrder (std::vector< UsdGeomXformOp > const &orderedXformOps, bool resetXformStack=false) const
 Reorder the already-existing transform ops on this prim.
 
USDGEOM_API std::vector< UsdGeomXformOpGetOrderedXformOps (bool *resetsXformStack) const
 Return the ordered list of transform operations to be applied to this prim, in least-to-most-local order.
 
USDGEOM_API bool ClearXformOpOrder () const
 Clears the local transform stack.
 
USDGEOM_API UsdGeomXformOp MakeMatrixXform () const
 Clears the existing local transform stack and creates a new xform op of type 'transform'.
 
USDGEOM_API bool TransformMightBeTimeVarying () const
 Determine whether there is any possibility that this prim's local transformation may vary over time.
 
USDGEOM_API bool TransformMightBeTimeVarying (const std::vector< UsdGeomXformOp > &ops) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Determine whether there is any possibility that this prim's local transformation may vary over time, using a pre-fetched (cached) list of ordered xform ops supplied by the client.
 
USDGEOM_API bool GetTimeSamples (std::vector< double > *times) const
 Sets times to the union of all the timesamples at which xformOps that are included in the xformOpOrder attribute are authored.
 
USDGEOM_API bool GetTimeSamplesInInterval (const GfInterval &interval, std::vector< double > *times) const
 Sets times to the union of all the timesamples in the interval, interval, at which xformOps that are included in the xformOpOrder attribute are authored.
 
USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, bool *resetsXformStack, const UsdTimeCode time=UsdTimeCode::Default()) const
 Computes the fully-combined, local-to-parent transformation for this prim.
 
USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, bool *resetsXformStack, const std::vector< UsdGeomXformOp > &ops, const UsdTimeCode time=UsdTimeCode::Default()) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the fully-combined, local-to-parent transformation for this prim as efficiently as possible, using a pre-fetched (cached) list of ordered xform ops supplied by the client.
 
- Public Member Functions inherited from UsdGeomImageable
 UsdGeomImageable (const UsdPrim &prim=UsdPrim())
 Construct a UsdGeomImageable on UsdPrim prim .
 
 UsdGeomImageable (const UsdSchemaBase &schemaObj)
 Construct a UsdGeomImageable on the prim held by schemaObj .
 
virtual USDGEOM_API ~UsdGeomImageable ()
 Destructor.
 
USDGEOM_API UsdAttribute GetVisibilityAttr () const
 Visibility is meant to be the simplest form of "pruning" visibility that is supported by most DCC apps.
 
USDGEOM_API UsdAttribute CreateVisibilityAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetVisibilityAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdAttribute GetPurposeAttr () const
 Purpose is a classification of geometry into categories that can each be independently included or excluded from traversals of prims on a stage, such as rendering or bounding-box computation traversals.
 
USDGEOM_API UsdAttribute CreatePurposeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 See GetPurposeAttr(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API UsdRelationship GetProxyPrimRel () const
 The proxyPrim relationship allows us to link a prim whose purpose is "render" to its (single target) purpose="proxy" prim.
 
USDGEOM_API UsdRelationship CreateProxyPrimRel () const
 See GetProxyPrimRel(), and also Create vs Get Property Methods for when to use Get vs Create.
 
USDGEOM_API void MakeVisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 Make the imageable visible if it is invisible at the given time.
 
USDGEOM_API void MakeInvisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 Makes the imageable invisible if it is visible at the given time.
 
USDGEOM_API TfToken ComputeVisibility (UsdTimeCode const &time=UsdTimeCode::Default()) const
 Calculate the effective visibility of this prim, as defined by its most ancestral authored "invisible" opinion, if any.
 
USDGEOM_API UsdAttribute GetPurposeVisibilityAttr (const TfToken &purpose=UsdGeomTokens->default_) const
 Return the attribute that is used for expressing visibility opinions for the given purpose.
 
USDGEOM_API TfToken ComputeEffectiveVisibility (const TfToken &purpose=UsdGeomTokens->default_, const UsdTimeCode &time=UsdTimeCode::Default()) const
 Calculate the effective purpose visibility of this prim for the given purpose, taking into account opinions for the corresponding purpose attribute, along with overall visibility opinions.
 
USDGEOM_API PurposeInfo ComputePurposeInfo () const
 Calculate the effective purpose information about this prim which includes final computed purpose value of the prim as well as whether the purpose value should be inherited by namespace children without their own purpose opinions.
 
USDGEOM_API PurposeInfo ComputePurposeInfo (const PurposeInfo &parentPurposeInfo) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Calculates the effective purpose information about this prim, given the computed purpose information of its parent prim.
 
USDGEOM_API TfToken ComputePurpose () const
 Calculate the effective purpose information about this prim.
 
USDGEOM_API UsdPrim ComputeProxyPrim (UsdPrim *renderPrim=NULL) const
 Find the prim whose purpose is proxy that serves as the proxy for this prim, as established by the GetProxyPrimRel(), or an invalid UsdPrim if this prim has no proxy.
 
USDGEOM_API bool SetProxyPrim (const UsdPrim &proxy) const
 Convenience function for authoring the renderProxy rel on this prim to target the given proxy prim.
 
USDGEOM_API bool SetProxyPrim (const UsdSchemaBase &proxy) const
 
USDGEOM_API GfBBox3d ComputeWorldBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 Compute the bound of this prim in world space, at the specified time, and for the specified purposes.
 
USDGEOM_API GfBBox3d ComputeLocalBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 Compute the bound of this prim in local space, at the specified time, and for the specified purposes.
 
USDGEOM_API GfBBox3d ComputeUntransformedBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 Compute the untransformed bound of this prim, at the specified time, and for the specified purposes.
 
USDGEOM_API GfMatrix4d ComputeLocalToWorldTransform (UsdTimeCode const &time) const
 Compute the transformation matrix for this prim at the given time, including the transform authored on the Prim itself, if present.
 
USDGEOM_API GfMatrix4d ComputeParentToWorldTransform (UsdTimeCode const &time) const
 Compute the transformation matrix for this prim at the given time, NOT including the transform authored on the prim itself.
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 Construct a UsdTyped on UsdPrim prim .
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 Construct a UsdTyped on the prim held by schemaObj .
 
virtual USD_API ~UsdTyped ()
 Destructor.
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 Returns whether or not this class corresponds to a concrete instantiable prim type in scene description.
 
bool IsTyped () const
 Returns whether or not this class inherits from UsdTyped.
 
bool IsAPISchema () const
 Returns whether this is an API schema or not.
 
bool IsAppliedAPISchema () const
 Returns whether this is an applied API schema or not.
 
bool IsMultipleApplyAPISchema () const
 Returns whether this is an applied API schema or not.
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is.
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim.
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema.
 
virtual USD_API ~UsdSchemaBase ()
 Destructor.
 
UsdPrim GetPrim () const
 Return this schema object's held prim.
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath().
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 Return the prim definition associated with this schema instance if one exists, otherwise return null.
 
USD_API operator bool () const
 Return true if this schema object is compatible with its held prim, false otherwise.
 

Static Public Member Functions

static USDGEOM_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDGEOM_API UsdGeomPointInstancer Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomPointInstancer holding the prim adhering to this schema at path on stage.
 
static USDGEOM_API UsdGeomPointInstancer Define (const UsdStagePtr &stage, const SdfPath &path)
 Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.
 
static USDGEOM_API bool ComputeInstanceTransformsAtTime (VtArray< GfMatrix4d > *xforms, UsdStageWeakPtr &stage, UsdTimeCode time, const VtIntArray &protoIndices, const VtVec3fArray &positions, const VtVec3fArray &velocities, UsdTimeCode velocitiesSampleTime, const VtVec3fArray &accelerations, const VtVec3fArray &scales, const VtQuatfArray &orientations, const VtVec3fArray &angularVelocities, UsdTimeCode angularVelocitiesSampleTime, const SdfPathVector &protoPaths, const std::vector< bool > &mask, float velocityScale=1.0)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Perform the per-instance transform computation as described in Computing an Instance Transform .
 
static USDGEOM_API bool ComputeInstanceTransformsAtTime (VtArray< GfMatrix4d > *xforms, UsdStageWeakPtr &stage, UsdTimeCode time, const VtIntArray &protoIndices, const VtVec3fArray &positions, const VtVec3fArray &velocities, UsdTimeCode velocitiesSampleTime, const VtVec3fArray &accelerations, const VtVec3fArray &scales, const VtQuathArray &orientations, const VtVec3fArray &angularVelocities, UsdTimeCode angularVelocitiesSampleTime, const SdfPathVector &protoPaths, const std::vector< bool > &mask, float velocityScale=1.0)
 
- Static Public Member Functions inherited from UsdGeomBoundable
static USDGEOM_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDGEOM_API UsdGeomBoundable Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomBoundable holding the prim adhering to this schema at path on stage.
 
static USDGEOM_API bool ComputeExtentFromPlugins (const UsdGeomBoundable &boundable, const UsdTimeCode &time, VtVec3fArray *extent)
 Compute the extent for the Boundable prim boundable at time time.
 
static USDGEOM_API bool ComputeExtentFromPlugins (const UsdGeomBoundable &boundable, const UsdTimeCode &time, const GfMatrix4d &transform, VtVec3fArray *extent)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix transform was first applied.
 
- Static Public Member Functions inherited from UsdGeomXformable
static USDGEOM_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDGEOM_API UsdGeomXformable Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomXformable holding the prim adhering to this schema at path on stage.
 
static USDGEOM_API bool GetTimeSamples (std::vector< UsdGeomXformOp > const &orderedXformOps, std::vector< double > *times)
 Returns the union of all the timesamples at which the attributes belonging to the given orderedXformOps are authored.
 
static USDGEOM_API bool GetTimeSamplesInInterval (std::vector< UsdGeomXformOp > const &orderedXformOps, const GfInterval &interval, std::vector< double > *times)
 Returns the union of all the timesamples in the interval at which the attributes belonging to the given orderedXformOps are authored.
 
static USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, std::vector< UsdGeomXformOp > const &ops, const UsdTimeCode time)
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This is a static version of the preceding function that takes a cached list of ordered xform ops.
 
static USDGEOM_API bool IsTransformationAffectedByAttrNamed (const TfToken &attrName)
 Returns true if the attribute named attrName could affect the local transformation of an xformable prim.
 
- Static Public Member Functions inherited from UsdGeomImageable
static USDGEOM_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USDGEOM_API UsdGeomImageable Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdGeomImageable holding the prim adhering to this schema at path on stage.
 
static USDGEOM_API const TfTokenVectorGetOrderedPurposeTokens ()
 Returns an ordered list of allowed values of the purpose attribute.
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.
 
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 Return a UsdTyped holding the prim adhering to this schema at path on stage.
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdGeomBoundable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdGeomXformable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdGeomImageable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 Compile time constant representing what kind of schema this class is.
 

Protected Member Functions

USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdGeomXformable
USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
- Protected Member Functions inherited from UsdTyped
USD_API UsdSchemaKind _GetSchemaKind () const override
 Returns the kind of schema this class belongs to.
 
USD_API bool _IsCompatible () const override
 Subclasses may override _IsCompatible to do specific compatibility checking with the given prim, such as type compatibility or value compatibility.
 
- Protected Member Functions inherited from UsdSchemaBase
virtual UsdSchemaKind _GetSchemaType () const
 
const TfType_GetType () const
 
USD_API UsdAttribute _CreateAttr (TfToken const &attrName, SdfValueTypeName const &typeName, bool custom, SdfVariability variability, VtValue const &defaultValue, bool writeSparsely) const
 

Friends

class UsdSchemaRegistry
 

Id-based Instance Masking/Pruning

See Masking Instances: "Deactivating" and Invising

USDGEOM_API bool ActivateId (int64_t id) const
 Ensure that the instance identified by id is active over all time.
 
USDGEOM_API bool ActivateIds (VtInt64Array const &ids) const
 Ensure that the instances identified by ids are active over all time.
 
USDGEOM_API bool ActivateAllIds () const
 Ensure that all instances are active over all time.
 
USDGEOM_API bool DeactivateId (int64_t id) const
 Ensure that the instance identified by id is inactive over all time.
 
USDGEOM_API bool DeactivateIds (VtInt64Array const &ids) const
 Ensure that the instances identified by ids are inactive over all time.
 
USDGEOM_API bool VisId (int64_t id, UsdTimeCode const &time) const
 Ensure that the instance identified by id is visible at time.
 
USDGEOM_API bool VisIds (VtInt64Array const &ids, UsdTimeCode const &time) const
 Ensure that the instances identified by ids are visible at time.
 
USDGEOM_API bool VisAllIds (UsdTimeCode const &time) const
 Ensure that all instances are visible at time.
 
USDGEOM_API bool InvisId (int64_t id, UsdTimeCode const &time) const
 Ensure that the instance identified by id is invisible at time.
 
USDGEOM_API bool InvisIds (VtInt64Array const &ids, UsdTimeCode const &time) const
 Ensure that the instances identified by ids are invisible at time.
 
USDGEOM_API std::vector< bool > ComputeMaskAtTime (UsdTimeCode time, VtInt64Array const *ids=nullptr) const
 Computes a presence mask to be applied to per-instance data arrays based on authored inactiveIds, invisibleIds, and ids .
 
USDGEOM_API bool UsesOrientationsf (UsdAttribute *rotationsAttr) const
 Determines if we should prefer orientationsf over orientations based on whether or not orientationsf has been authored to a non empty array.
 
USDGEOM_API bool UsesOrientationsf (TfToken *rotationsToken=nullptr) const
 
template<class T >
static bool ApplyMaskToArray (std::vector< bool > const &mask, VtArray< T > *dataArray, const int elementSize=1)
 Contract dataArray in-place to contain only the elements whose index in mask is true.
 

Detailed Description

Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters), which can be arbitrary prims/subtrees on a UsdStage.

PointInstancer is a "multi instancer", as it allows multiple prototypes to be scattered among its "points". We use a UsdRelationship prototypes to identify and order all of the possible prototypes, by targeting the root prim of each prototype. The ordering imparted by relationships associates a zero-based integer with each prototype, and it is these integers we use to identify the prototype of each instance, compactly, and allowing prototypes to be swapped out without needing to reauthor all of the per-instance data.

The PointInstancer schema is designed to scale to billions of instances, which motivates the choice to split the per-instance transformation into position, (quaternion) orientation, and scales, rather than a 4x4 matrix per-instance. In addition to requiring fewer bytes even if all elements are authored (32 bytes vs 64 for a single-precision 4x4 matrix), we can also be selective about which attributes need to animate over time, for substantial data reduction in many cases.

Note that PointInstancer is not a Gprim, since it is not a graphical primitive by any stretch of the imagination. It is, however, Boundable, since we will sometimes want to treat the entire PointInstancer similarly to a procedural, from the perspective of inclusion or framing.

Varying Instance Identity over Time

PointInstancers originating from simulations often have the characteristic that points/instances are "born", move around for some time period, and then die (or leave the area of interest). In such cases, billions of instances may be birthed over time, while at any specific time, only a much smaller number are actually alive. To encode this situation efficiently, the simulator may re-use indices in the instance arrays, when a particle dies, its index will be taken over by a new particle that may be birthed in a much different location. This presents challenges both for identity-tracking, and for motion-blur.

We facilitate identity tracking by providing an optional, animatable ids attribute, that specifies the 64 bit integer ID of the particle at each index, at each point in time. If the simulator keeps monotonically increasing a particle-count each time a new particle is birthed, it will serve perfectly as particle ids.

We facilitate motion blur for varying-topology particle streams by optionally allowing per-instance velocities and angularVelocities to be authored. If instance transforms are requested at a time between samples and either of the velocity attributes is authored, then we will not attempt to interpolate samples of positions or orientations. If not authored, and the bracketing samples have the same length, then we will interpolate.

Computing an Instance Transform

Each instance's transformation is a combination of the SRT affine transform described by its scale, orientation, and position, applied after (i.e. less locally than) the local to parent transformation computed at the root of the prototype it is instancing.

If your processing of prototype geometry naturally takes into account the transform of the prototype root, then this term can be omitted from the computation of each instance transform, and this can be controlled when computing instance transformation matrices using the UsdGeomPointInstancer::PrototypeXformInclusion enumeration.

To understand the computation of the instance transform, in order to put an instance of a PointInstancer into the space of the PointInstancer's parent prim we do the following:

  1. Apply (most locally) the authored local to parent transformation for prototypes[protoIndices[i]]
  2. If scales is authored, next apply the scaling matrix from scales[i]
  3. If orientations is authored: if angularVelocities is authored, first multiply orientations[i] by the unit quaternion derived by scaling angularVelocities[i] by the time differential from the left-bracketing timeSample for orientation to the requested evaluation time t, storing the result in R, else assign R directly from orientations[i]. Apply the rotation matrix derived from R.
  4. Apply the translation derived from positions[i]. If velocities is authored, apply the translation deriving from velocities[i] scaled by the time differential from the left-bracketing timeSample for positions to the requested evaluation time t.
  5. Least locally, apply the transformation authored on the PointInstancer prim itself (or the UsdGeomImageable::ComputeLocalToWorldTransform() of the PointInstancer to put the instance directly into world space)

If neither velocities nor angularVelocities are authored, we fallback to standard position and orientation computation logic (using linear interpolation between timeSamples) as described by Applying Timesampled Velocities to Geometry .

Scaling Velocities for Interpolation

When computing time-differentials by which to apply velocity or angularVelocity to positions or orientations, we must scale by ( 1.0 / UsdStage::GetTimeCodesPerSecond() ), because velocities are recorded in units/second, while we are interpolating in UsdTimeCode ordinates.

We provide both high and low-level API's for dealing with the transformation as a matrix, both will compute the instance matrices using multiple threads; the low-level API allows the client to cache unvarying inputs so that they need not be read duplicately when computing over time.

See also Applying Timesampled Velocities to Geometry .

Primvars on PointInstancer

Primvars authored on a PointInstancer prim should always be applied to each instance with constant interpolation at the root of the instance. When you are authoring primvars on a PointInstancer, think about it as if you were authoring them on a point-cloud (e.g. a UsdGeomPoints gprim). The same interpolation rules for points apply here, substituting "instance" for "point".

In other words, the (constant) value extracted for each instance from the authored primvar value depends on the authored interpolation and elementSize of the primvar, as follows:

  • constant or uniform : the entire authored value of the primvar should be applied exactly to each instance.
  • varying, vertex, or faceVarying: the first elementSize elements of the authored primvar array should be assigned to instance zero, the second elementSize elements should be assigned to instance one, and so forth.

Masking Instances: "Deactivating" and Invising

Often a PointInstancer is created "upstream" in a graphics pipeline, and the needs of "downstream" clients necessitate eliminating some of the instances from further consideration. Accomplishing this pruning by re-authoring all of the per-instance attributes is not very attractive, since it may mean destructively editing a large quantity of data. We therefore provide means of "masking" instances by ID, such that the instance data is unmolested, but per-instance transform and primvar data can be retrieved with the no-longer-desired instances eliminated from the (smaller) arrays. PointInstancer allows two independent means of masking instances by ID, each with different features that meet the needs of various clients in a pipeline. Both pruning features' lists of ID's are combined to produce the mask returned by ComputeMaskAtTime().

Note
If a PointInstancer has no authored ids attribute, the masking features will still be available, with the integers specifying element position in the protoIndices array rather than ID.

InactiveIds: List-edited, Unvarying Masking

The first masking feature encodes a list of IDs in a list-editable metadatum called inactiveIds, which, although it does not have any similar impact to stage population as prim activation, it shares with that feature that its application is uniform over all time. Because it is list-editable, we can sparsely add and remove instances from it in many layers.

This sparse application pattern makes inactiveIds a good choice when further downstream clients may need to reverse masking decisions made upstream, in a manner that is robust to many kinds of future changes to the upstream data.

See ActivateId(), ActivateIds(), DeactivateId(), DeactivateIds(), ActivateAllIds()

invisibleIds: Animatable Masking

The second masking feature encodes a list of IDs in a time-varying Int64Array-valued UsdAttribute called invisibleIds , since it shares with Imageable visibility the ability to animate object visibility.

Unlike inactiveIds, overriding a set of opinions for invisibleIds is not at all straightforward, because one will, in general need to reauthor (in the overriding layer) all timeSamples for the attribute just to change one Id's visibility state, so it cannot be authored sparsely. But it can be a very useful tool for situations like encoding pre-computed camera-frustum culling of geometry when either or both of the instances or the camera is animated.

See VisId(), VisIds(), InvisId(), InvisIds(), VisAllIds()

Processing and Not Processing Prototypes

Any prim in the scenegraph can be targeted as a prototype by the prototypes relationship. We do not, however, provide a specific mechanism for identifying prototypes as geometry that should not be drawn (or processed) in their own, local spaces in the scenegraph. We encourage organizing all prototypes as children of the PointInstancer prim that consumes them, and pruning "raw" processing and drawing traversals when they encounter a PointInstancer prim; this is what the UsdGeomBBoxCache and UsdImaging engines do.

There is a pattern one can deploy for organizing the prototypes such that they will automatically be skipped by basic UsdPrim::GetChildren() or UsdPrimRange traversals. Usd prims each have a specifier of "def", "over", or "class". The default traversals skip over prims that are "pure overs" or classes. So to protect prototypes from all generic traversals and processing, place them under a prim that is just an "over". For example,

01 def PointInstancer "Crowd_Mid"
02 {
03 rel prototypes = [ </Crowd_Mid/Prototypes/MaleThin_Business>, </Crowd_Mid/Prototypes/MaleThin_Casual> ]
04
05 over "Prototypes"
06 {
07 def "MaleThin_Business" (
08 references = [@MaleGroupA/usd/MaleGroupA.usd@</MaleGroupA>]
09 variants = {
10 string modelingVariant = "Thin"
11 string costumeVariant = "BusinessAttire"
12 }
13 )
14 { ... }
15
16 def "MaleThin_Casual"
17 ...
18 }
19 }

Definition at line 261 of file pointInstancer.h.

Member Enumeration Documentation

◆ MaskApplication

Encodes whether to evaluate and apply the PointInstancer's mask to computed results.

See also
ComputeMaskAtTime()
Enumerator
ApplyMask 

Compute and apply the PointInstancer mask.

IgnoreMask 

Ignore the PointInstancer mask.

Definition at line 851 of file pointInstancer.h.

◆ ProtoXformInclusion

Encodes whether to include each prototype's root prim's transformation as the most-local component of computed instance transforms.

Enumerator
IncludeProtoXform 

Include the transform on the proto's root.

ExcludeProtoXform 

Exclude the transform on the proto's root.

Definition at line 840 of file pointInstancer.h.

Constructor & Destructor Documentation

◆ UsdGeomPointInstancer() [1/2]

UsdGeomPointInstancer ( const UsdPrim prim = UsdPrim())
inlineexplicit

Construct a UsdGeomPointInstancer on UsdPrim prim .

Equivalent to UsdGeomPointInstancer::Get(prim.GetStage(), prim.GetPath()) for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 273 of file pointInstancer.h.

◆ UsdGeomPointInstancer() [2/2]

UsdGeomPointInstancer ( const UsdSchemaBase schemaObj)
inlineexplicit

Construct a UsdGeomPointInstancer on the prim held by schemaObj .

Should be preferred over UsdGeomPointInstancer(schemaObj.GetPrim()), as it preserves SchemaBase state.

Definition at line 281 of file pointInstancer.h.

◆ ~UsdGeomPointInstancer()

virtual USDGEOM_API ~UsdGeomPointInstancer ( )
virtual

Destructor.

Member Function Documentation

◆ _GetSchemaKind()

USDGEOM_API UsdSchemaKind _GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See also
UsdSchemaKind

Reimplemented from UsdGeomBoundable.

◆ ActivateAllIds()

USDGEOM_API bool ActivateAllIds ( ) const

Ensure that all instances are active over all time.

This does not guarantee that the instances will be rendered, because each may still be "invisible" due to its presence in the invisibleIds attribute (see VisId(), InvisId())

◆ ActivateId()

USDGEOM_API bool ActivateId ( int64_t  id) const

Ensure that the instance identified by id is active over all time.

This activation is encoded sparsely, affecting no other instances.

This does not guarantee that the instance will be rendered, because it may still be "invisible" due to id being present in the invisibleIds attribute (see VisId(), InvisId())

◆ ActivateIds()

USDGEOM_API bool ActivateIds ( VtInt64Array const &  ids) const

Ensure that the instances identified by ids are active over all time.

This activation is encoded sparsely, affecting no other instances.

This does not guarantee that the instances will be rendered, because each may still be "invisible" due to its presence in the invisibleIds attribute (see VisId(), InvisId())

◆ ApplyMaskToArray()

bool ApplyMaskToArray ( std::vector< bool > const &  mask,
VtArray< T > *  dataArray,
const int  elementSize = 1 
)
static

Contract dataArray in-place to contain only the elements whose index in mask is true.

Note
an empty mask specifies "all pass", in which case dataArray is trivially unmodified
  • It is an error for dataArray to be NULL .
  • If elementSize times mask.size() does not equal dataArray->size(), warn and fail.
Returns
true on success, false on failure.
See also
ComputeMaskAtTime()

Definition at line 1210 of file pointInstancer.h.

◆ ComputeExtentAtTime() [1/2]

USDGEOM_API bool ComputeExtentAtTime ( VtVec3fArray *  extent,
const UsdTimeCode  time,
const UsdTimeCode  baseTime 
) const

Compute the extent of the point instancer based on the per-instance, "PointInstancer relative" transforms at time, as described in Computing an Instance Transform .

If there is no error, we return true and extent will be the tightest bounds we can compute efficiently. If an error occurs, false will be returned and extent will be left untouched.

For now, this uses a UsdGeomBBoxCache with the "default", "proxy", and "render" purposes.

Parameters
extent- the out parameter for the extent. On success, it will contain two elements representing the min and max.
time- UsdTimeCode at which we want to evaluate the extent
baseTime- required for correct interpolation between samples when velocities or angularVelocities are present. If there are samples for positions and velocities at t1 and t2, normal value resolution would attempt to interpolate between the two samples, and if they could not be interpolated because they differ in size (common in cases where velocity is authored), will choose the sample at t1. When sampling for the purposes of motion-blur, for example, it is common, when rendering the frame at t2, to sample at [ t2-shutter/2, t2+shutter/2 ] for a shutter interval of shutter. The first sample falls between t1 and t2, but we must sample at t2 and apply velocity-based interpolation based on those samples to get a correct result. In such scenarios, one should provide a baseTime of t2 when querying both samples. If your application does not care about off-sample interpolation, it can supply the same value for baseTime that it does for time. When baseTime is less than or equal to time, we will choose the lower bracketing timeSample.

◆ ComputeExtentAtTime() [2/2]

USDGEOM_API bool ComputeExtentAtTime ( VtVec3fArray *  extent,
const UsdTimeCode  time,
const UsdTimeCode  baseTime,
const GfMatrix4d transform 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix transform was first applied.

◆ ComputeExtentAtTimes() [1/2]

USDGEOM_API bool ComputeExtentAtTimes ( std::vector< VtVec3fArray > *  extents,
const std::vector< UsdTimeCode > &  times,
const UsdTimeCode  baseTime 
) const

Compute the extent of the point instancer as in ComputeExtentAtTime , but across multiple times .

This is equivalent to, but more efficient than, calling ComputeExtentAtTime several times. Each element in extents is the computed extent at the corresponding time in times .

As in ComputeExtentAtTime, if there is no error, we return true and extents will be the tightest bounds we can compute efficiently. If an error occurs computing the extent at any time, false will be returned and extents will be left untouched.

Parameters
times- A vector containing the UsdTimeCodes at which we want to sample.

◆ ComputeExtentAtTimes() [2/2]

USDGEOM_API bool ComputeExtentAtTimes ( std::vector< VtVec3fArray > *  extents,
const std::vector< UsdTimeCode > &  times,
const UsdTimeCode  baseTime,
const GfMatrix4d transform 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Computes the extent as if the matrix transform was first applied at each time.

◆ ComputeInstanceTransformsAtTime() [1/2]

USDGEOM_API bool ComputeInstanceTransformsAtTime ( VtArray< GfMatrix4d > *  xforms,
const UsdTimeCode  time,
const UsdTimeCode  baseTime,
const ProtoXformInclusion  doProtoXforms = IncludeProtoXform,
const MaskApplication  applyMask = ApplyMask 
) const

Compute the per-instance, "PointInstancer relative" transforms given the positions, scales, orientations, velocities and angularVelocities at time, as described in Computing an Instance Transform .

This will return false and leave xforms untouched if:

  • xforms is NULL
  • one of time and baseTime is numeric and the other is UsdTimeCode::Default() (they must either both be numeric or both be default)
  • there is no authored protoIndices attribute or positions attribute
  • the size of any of the per-instance attributes does not match the size of protoIndices
  • doProtoXforms is IncludeProtoXform but an index value in protoIndices is outside the range [0, prototypes.size())
  • applyMask is ApplyMask and a mask is set but the size of the mask does not match the size of protoIndices.

If there is no error, we will return true and xforms will contain the computed transformations.

Parameters
xforms- the out parameter for the transformations. Its size will depend on the authored data and applyMask
time- UsdTimeCode at which we want to evaluate the transforms
baseTime- required for correct interpolation between samples when velocities or angularVelocities are present. If there are samples for positions and velocities at t1 and t2, normal value resolution would attempt to interpolate between the two samples, and if they could not be interpolated because they differ in size (common in cases where velocity is authored), will choose the sample at t1. When sampling for the purposes of motion-blur, for example, it is common, when rendering the frame at t2, to sample at [ t2-shutter/2, t2+shutter/2 ] for a shutter interval of shutter. The first sample falls between t1 and t2, but we must sample at t2 and apply velocity-based interpolation based on those samples to get a correct result. In such scenarios, one should provide a baseTime of t2 when querying both samples. If your application does not care about off-sample interpolation, it can supply the same value for baseTime that it does for time. When baseTime is less than or equal to time, we will choose the lower bracketing timeSample. Selecting sample times with respect to baseTime will be performed independently for positions and orientations.
doProtoXforms- specifies whether to include the root transformation of each instance's prototype in the instance's transform. Default is to include it, but some clients may want to apply the proto transform as part of the prototype itself, so they can specify ExcludeProtoXform instead.
applyMask- specifies whether to apply ApplyMaskToArray() to the computed result. The default is ApplyMask.

◆ ComputeInstanceTransformsAtTime() [2/2]

static USDGEOM_API bool ComputeInstanceTransformsAtTime ( VtArray< GfMatrix4d > *  xforms,
UsdStageWeakPtr &  stage,
UsdTimeCode  time,
const VtIntArray &  protoIndices,
const VtVec3fArray &  positions,
const VtVec3fArray &  velocities,
UsdTimeCode  velocitiesSampleTime,
const VtVec3fArray &  accelerations,
const VtVec3fArray &  scales,
const VtQuatfArray &  orientations,
const VtVec3fArray &  angularVelocities,
UsdTimeCode  angularVelocitiesSampleTime,
const SdfPathVector &  protoPaths,
const std::vector< bool > &  mask,
float  velocityScale = 1.0 
)
static

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Perform the per-instance transform computation as described in Computing an Instance Transform .

This does the same computation as the non-static ComputeInstanceTransformsAtTime method, but takes all data as parameters rather than accessing authored data.

Parameters
xforms- the out parameter for the transformations. Its size will depend on the given data and applyMask
stage- the UsdStage
time- time at which we want to evaluate the transforms
protoIndices- array containing all instance prototype indices.
positions- array containing all instance positions. This array must be the same size as protoIndices .
velocities- array containing all instance velocities. This array must be either the same size as protoIndices or empty. If it is empty, transforms are computed as if all velocities were zero in all dimensions.
velocitiesSampleTime- time at which the samples from velocities were taken.
accelerations- array containing all instance accelerations. This array must be either the same size as protoIndicesor empty. If it is empty, transforms are computed as if all accelerations were zero in all dimensions.
scales- array containing all instance scales. This array must be either the same size as protoIndices or empty. If it is empty, transforms are computed with no change in scale.
orientations- array containing all instance orientations. This array must be either the same size as protoIndices or empty. If it is empty, transforms are computed with no change in orientation
angularVelocities- array containing all instance angular velocities. This array must be either the same size as protoIndices or empty. If it is empty, transforms are computed as if all angular velocities were zero in all dimensions.
angularVelocitiesSampleTime- time at which the samples from angularVelocities were taken.
protoPaths- array containing the paths for all instance prototypes. If this array is not empty, prototype transforms are applied to the instance transforms.
mask- vector containing a mask to apply to the computed result. This vector must be either the same size as protoIndices or empty. If it is empty, no mask is applied.
velocityScale-
Deprecated:

◆ ComputeInstanceTransformsAtTimes()

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

Compute the per-instance transforms as in ComputeInstanceTransformsAtTime, but using multiple sample times.

An array of matrix arrays is returned where each matrix array contains the instance transforms for the corresponding time in times .

Parameters
times- A vector containing the UsdTimeCodes at which we want to sample.

◆ ComputeMaskAtTime()

USDGEOM_API std::vector< bool > ComputeMaskAtTime ( UsdTimeCode  time,
VtInt64Array const *  ids = nullptr 
) const

Computes a presence mask to be applied to per-instance data arrays based on authored inactiveIds, invisibleIds, and ids .

If no ids attribute has been authored, then the values in inactiveIds and invisibleIds will be interpreted directly as indices of protoIndices .

If ids is non-NULL, it is assumed to be the id-mapping to apply, and must match the length of protoIndices at time . If NULL, we will call GetIdsAttr().Get(time)

Note
If all "live" instances at UsdTimeCode time pass the mask, we will return an empty mask so that clients can trivially recognize the common "no masking" case.

The returned mask can be used with ApplyMaskToArray(), and will contain a true value for every element that should survive.

◆ CreateAccelerationsAttr()

USDGEOM_API UsdAttribute CreateAccelerationsAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetAccelerationsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateAngularVelocitiesAttr()

USDGEOM_API UsdAttribute CreateAngularVelocitiesAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetAngularVelocitiesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateIdsAttr()

USDGEOM_API UsdAttribute CreateIdsAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetIdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateInvisibleIdsAttr()

USDGEOM_API UsdAttribute CreateInvisibleIdsAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetInvisibleIdsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateOrientationsAttr()

USDGEOM_API UsdAttribute CreateOrientationsAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetOrientationsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateOrientationsfAttr()

USDGEOM_API UsdAttribute CreateOrientationsfAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetOrientationsfAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreatePositionsAttr()

USDGEOM_API UsdAttribute CreatePositionsAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetPositionsAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateProtoIndicesAttr()

USDGEOM_API UsdAttribute CreateProtoIndicesAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetProtoIndicesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreatePrototypesRel()

USDGEOM_API UsdRelationship CreatePrototypesRel ( ) const

See GetPrototypesRel(), and also Create vs Get Property Methods for when to use Get vs Create.

◆ CreateScalesAttr()

USDGEOM_API UsdAttribute CreateScalesAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetScalesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ CreateVelocitiesAttr()

USDGEOM_API UsdAttribute CreateVelocitiesAttr ( VtValue const &  defaultValue = VtValue(),
bool  writeSparsely = false 
) const

See GetVelocitiesAttr(), and also Create vs Get Property Methods for when to use Get vs Create.

If specified, author defaultValue as the attribute's default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

◆ DeactivateId()

USDGEOM_API bool DeactivateId ( int64_t  id) const

Ensure that the instance identified by id is inactive over all time.

This deactivation is encoded sparsely, affecting no other instances.

A deactivated instance is guaranteed not to render if the renderer honors masking.

◆ DeactivateIds()

USDGEOM_API bool DeactivateIds ( VtInt64Array const &  ids) const

Ensure that the instances identified by ids are inactive over all time.

This deactivation is encoded sparsely, affecting no other instances.

A deactivated instance is guaranteed not to render if the renderer honors masking.

◆ Define()

static USDGEOM_API UsdGeomPointInstancer Define ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Attempt to ensure a UsdPrim adhering to this schema at path is defined (according to UsdPrim::IsDefined()) on this stage.

If a prim adhering to this schema at path is already defined on this stage, return that prim. Otherwise author an SdfPrimSpec with specifier == SdfSpecifierDef and this schema's prim type name for the prim at path at the current EditTarget. Author SdfPrimSpec s with specifier == SdfSpecifierDef and empty typeName at the current EditTarget for any nonexistent, or existing but not Defined ancestors.

The given path must be an absolute prim path that does not contain any variant selections.

If it is impossible to author any of the necessary PrimSpecs, (for example, in case path cannot map to the current UsdEditTarget's namespace) issue an error and return an invalid UsdPrim.

Note that this method may return a defined prim whose typeName does not specify this schema class, in case a stronger typeName opinion overrides the opinion at the current EditTarget.

◆ Get()

static USDGEOM_API UsdGeomPointInstancer Get ( const UsdStagePtr &  stage,
const SdfPath path 
)
static

Return a UsdGeomPointInstancer holding the prim adhering to this schema at path on stage.

If no prim exists at path on stage, or if the prim at that path does not adhere to this schema, return an invalid schema object. This is shorthand for the following:

UsdGeomPointInstancer(stage->GetPrimAtPath(path));
Encodes vectorized instancing of multiple, potentially animated, prototypes (object/instance masters)...

◆ GetAccelerationsAttr()

USDGEOM_API UsdAttribute GetAccelerationsAttr ( ) const

If authored, per-instance 'accelerations' will be used with velocities to compute positions between samples for the 'positions' attribute rather than interpolating between neighboring 'positions' samples.

Acceleration is measured in position units per second-squared. To convert to position units per squared UsdTimeCode, divide by the square of UsdStage::GetTimeCodesPerSecond().

Declaration vector3f[] accelerations
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Vector3fArray

◆ GetAngularVelocitiesAttr()

USDGEOM_API UsdAttribute GetAngularVelocitiesAttr ( ) const

If authored, per-instance angular velocity vector to be used for interoplating orientations.

Angular velocities should be considered mandatory if both protoIndices and orientations are animated. Angular velocity is measured in degrees per second. To convert to degrees per UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond().

See also Computing an Instance Transform .

Declaration vector3f[] angularVelocities
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Vector3fArray

◆ GetIdsAttr()

USDGEOM_API UsdAttribute GetIdsAttr ( ) const

Ids are optional; if authored, the ids array should be the same length as the protoIndices array, specifying (at each timeSample if instance identities are changing) the id of each instance.

The type is signed intentionally, so that clients can encode some binary state on Id'd instances without adding a separate primvar. See also Varying Instance Identity over Time

Declaration int64[] ids
C++ Type VtArray<int64_t>
Usd Type SdfValueTypeNames->Int64Array

◆ GetInstanceCount()

USDGEOM_API size_t GetInstanceCount ( UsdTimeCode  timeCode = UsdTimeCode::Default()) const

Returns the number of instances as defined by the size of the protoIndices array at timeCode.

Note
For most code, this check will be performant. When using file formats where the cost of attribute reading is high and the time sampled array will be read into memory later, it may be better to explicitly read the value once and check the size of the array directly.

See also
GetProtoIndicesAttr()

◆ GetInvisibleIdsAttr()

USDGEOM_API UsdAttribute GetInvisibleIdsAttr ( ) const

A list of id's to make invisible at the evaluation time.

See invisibleIds: Animatable Masking .

Declaration int64[] invisibleIds = []
C++ Type VtArray<int64_t>
Usd Type SdfValueTypeNames->Int64Array

◆ GetOrientationsAttr()

USDGEOM_API UsdAttribute GetOrientationsAttr ( ) const

If authored, per-instance orientation of each instance about its prototype's origin, represented as a unit length quaternion, which allows us to encode it with sufficient precision in a compact GfQuath.

It is client's responsibility to ensure that authored quaternions are unit length; the convenience API below for authoring orientations from rotation matrices will ensure that quaternions are unit length, though it will not make any attempt to select the "better (for interpolation with respect to neighboring samples)" of the two possible quaternions that encode the rotation.

See also Computing an Instance Transform .

Declaration quath[] orientations
C++ Type VtArray<GfQuath>
Usd Type SdfValueTypeNames->QuathArray

◆ GetOrientationsfAttr()

USDGEOM_API UsdAttribute GetOrientationsfAttr ( ) const

If authored, per-instance orientation of each instance about its prototype's origin, represented as a unit length quaternion, encoded as a GfQuatf to support higher precision computations.

It is client's responsibility to ensure that authored quaternions are unit length; the convenience API below for authoring orientations from rotation matrices will ensure that quaternions are unit length, though it will not make any attempt to select the "better (for interpolation with respect to neighboring samples)" of the two possible quaternions that encode the rotation. Note that if the earliest time sample (or default value if there are no time samples) of orientationsf is not empty orientationsf will be preferred over orientations if both are authored.

See also Computing an Instance Transform .

Declaration quatf[] orientationsf
C++ Type VtArray<GfQuatf>
Usd Type SdfValueTypeNames->QuatfArray

◆ GetPositionsAttr()

USDGEOM_API UsdAttribute GetPositionsAttr ( ) const

Required property.

Per-instance position. See also Computing an Instance Transform .

Declaration point3f[] positions
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Point3fArray

◆ GetProtoIndicesAttr()

USDGEOM_API UsdAttribute GetProtoIndicesAttr ( ) const

Required property.

Per-instance index into prototypes relationship that identifies what geometry should be drawn for each instance. Topology attribute - can be animated, but at a potential performance impact for streaming.

Declaration int[] protoIndices
C++ Type VtArray<int>
Usd Type SdfValueTypeNames->IntArray

◆ GetPrototypesRel()

USDGEOM_API UsdRelationship GetPrototypesRel ( ) const

Required property.

Orders and targets the prototype root prims, which can be located anywhere in the scenegraph that is convenient, although we promote organizing prototypes as children of the PointInstancer. The position of a prototype in this relationship defines the value an instance would specify in the protoIndices attribute to instance that prototype. Since relationships are uniform, this property cannot be animated.

◆ GetScalesAttr()

USDGEOM_API UsdAttribute GetScalesAttr ( ) const

If authored, per-instance scale to be applied to each instance, before any rotation is applied.

See also Computing an Instance Transform .

Declaration float3[] scales
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Float3Array

◆ GetSchemaAttributeNames()

static USDGEOM_API const TfTokenVector & GetSchemaAttributeNames ( bool  includeInherited = true)
static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes.

Does not include attributes that may be authored by custom/extended methods of the schemas involved.

◆ GetVelocitiesAttr()

USDGEOM_API UsdAttribute GetVelocitiesAttr ( ) const

If provided, per-instance 'velocities' will be used to compute positions between samples for the 'positions' attribute, rather than interpolating between neighboring 'positions' samples.

Velocities should be considered mandatory if both protoIndices and positions are animated. Velocity is measured in position units per second, as per most simulation software. To convert to position units per UsdTimeCode, divide by UsdStage::GetTimeCodesPerSecond().

See also Computing an Instance Transform, Applying Timesampled Velocities to Geometry .

Declaration vector3f[] velocities
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Vector3fArray

◆ InvisId()

USDGEOM_API bool InvisId ( int64_t  id,
UsdTimeCode const &  time 
) const

Ensure that the instance identified by id is invisible at time.

This will cause invisibleIds to first be broken down (keyed) at time, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one at time.

An invised instance is guaranteed not to render if the renderer honors masking.

◆ InvisIds()

USDGEOM_API bool InvisIds ( VtInt64Array const &  ids,
UsdTimeCode const &  time 
) const

Ensure that the instances identified by ids are invisible at time.

This will cause invisibleIds to first be broken down (keyed) at time, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one at time.

An invised instance is guaranteed not to render if the renderer honors masking.

◆ UsesOrientationsf()

USDGEOM_API bool UsesOrientationsf ( UsdAttribute rotationsAttr) const

Determines if we should prefer orientationsf over orientations based on whether or not orientationsf has been authored to a non empty array.

Assumes that orientationsf is empty if the earliest time sample or default value if there are no time samples are empty

Parameters
rotationsAttrthe outparameter for the corresponding attribute. If this function returns true then orientationsf will be stored in rotationsAttr, and orientations if not

◆ VisAllIds()

USDGEOM_API bool VisAllIds ( UsdTimeCode const &  time) const

Ensure that all instances are visible at time.

Operates by authoring an empty array at time.

This does not guarantee that the instances will be rendered, because each may still be "inactive" due to its id being present in the inactivevIds metadata (see ActivateId(), DeactivateId())

◆ VisId()

USDGEOM_API bool VisId ( int64_t  id,
UsdTimeCode const &  time 
) const

Ensure that the instance identified by id is visible at time.

This will cause invisibleIds to first be broken down (keyed) at time, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one at time. If the invisibleIds attribute is not authored or is blocked, this operation is a no-op.

This does not guarantee that the instance will be rendered, because it may still be "inactive" due to id being present in the inactivevIds metadata (see ActivateId(), DeactivateId())

◆ VisIds()

USDGEOM_API bool VisIds ( VtInt64Array const &  ids,
UsdTimeCode const &  time 
) const

Ensure that the instances identified by ids are visible at time.

This will cause invisibleIds to first be broken down (keyed) at time, causing all animation in weaker layers that the current UsdEditTarget to be overridden. Has no effect on any timeSamples other than the one at time. If the invisibleIds attribute is not authored or is blocked, this operation is a no-op.

This does not guarantee that the instances will be rendered, because each may still be "inactive" due to id being present in the inactivevIds metadata (see ActivateId(), DeactivateId())

Friends And Related Function Documentation

◆ UsdSchemaRegistry

friend class UsdSchemaRegistry
friend

Definition at line 345 of file pointInstancer.h.

Member Data Documentation

◆ schemaKind

const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
static

Compile time constant representing what kind of schema this class is.

See also
UsdSchemaKind

Definition at line 267 of file pointInstancer.h.


The documentation for this class was generated from the following file: