HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdGeomPointInstancer Class Reference

#include <pointInstancer.h>

+ Inheritance diagram for UsdGeomPointInstancer:

Public Types

enum  ProtoXformInclusion { IncludeProtoXform, ExcludeProtoXform }
 
enum  MaskApplication { ApplyMask, IgnoreMask }
 

Public Member Functions

 UsdGeomPointInstancer (const UsdPrim &prim=UsdPrim())
 
 UsdGeomPointInstancer (const UsdSchemaBase &schemaObj)
 
virtual USDGEOM_API ~UsdGeomPointInstancer ()
 Destructor. More...
 
USDGEOM_API UsdAttribute GetProtoIndicesAttr () const
 
USDGEOM_API UsdAttribute CreateProtoIndicesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetIdsAttr () const
 
USDGEOM_API UsdAttribute CreateIdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetPositionsAttr () const
 
USDGEOM_API UsdAttribute CreatePositionsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetOrientationsAttr () const
 
USDGEOM_API UsdAttribute CreateOrientationsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetOrientationsfAttr () const
 
USDGEOM_API UsdAttribute CreateOrientationsfAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetScalesAttr () const
 
USDGEOM_API UsdAttribute CreateScalesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetVelocitiesAttr () const
 
USDGEOM_API UsdAttribute CreateVelocitiesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetAccelerationsAttr () const
 
USDGEOM_API UsdAttribute CreateAccelerationsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetAngularVelocitiesAttr () const
 
USDGEOM_API UsdAttribute CreateAngularVelocitiesAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetInvisibleIdsAttr () const
 
USDGEOM_API UsdAttribute CreateInvisibleIdsAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdRelationship GetPrototypesRel () const
 
USDGEOM_API UsdRelationship CreatePrototypesRel () const
 
USDGEOM_API bool ComputeInstanceTransformsAtTime (VtArray< GfMatrix4d > *xforms, const UsdTimeCode time, const UsdTimeCode baseTime, const ProtoXformInclusion doProtoXforms=IncludeProtoXform, const MaskApplication applyMask=ApplyMask) const
 
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
 
USDGEOM_API bool ComputeExtentAtTime (VtVec3fArray *extent, const UsdTimeCode time, const UsdTimeCode baseTime) const
 
USDGEOM_API bool ComputeExtentAtTime (VtVec3fArray *extent, const UsdTimeCode time, const UsdTimeCode baseTime, const GfMatrix4d &transform) const
 
USDGEOM_API bool ComputeExtentAtTimes (std::vector< VtVec3fArray > *extents, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime) const
 
USDGEOM_API bool ComputeExtentAtTimes (std::vector< VtVec3fArray > *extents, const std::vector< UsdTimeCode > &times, const UsdTimeCode baseTime, const GfMatrix4d &transform) const
 
USDGEOM_API size_t GetInstanceCount (UsdTimeCode timeCode=UsdTimeCode::Default()) const
 
- Public Member Functions inherited from UsdGeomBoundable
 UsdGeomBoundable (const UsdPrim &prim=UsdPrim())
 
 UsdGeomBoundable (const UsdSchemaBase &schemaObj)
 
virtual USDGEOM_API ~UsdGeomBoundable ()
 Destructor. More...
 
USDGEOM_API UsdAttribute GetExtentAttr () const
 
USDGEOM_API UsdAttribute CreateExtentAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API bool ComputeExtent (const UsdTimeCode &time, VtVec3fArray *extent)
 
- Public Member Functions inherited from UsdGeomXformable
 UsdGeomXformable (const UsdPrim &prim=UsdPrim())
 
 UsdGeomXformable (const UsdSchemaBase &schemaObj)
 
virtual USDGEOM_API ~UsdGeomXformable ()
 Destructor. More...
 
USDGEOM_API UsdAttribute GetXformOpOrderAttr () const
 
USDGEOM_API UsdAttribute CreateXformOpOrderAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdGeomXformOp AddXformOp (UsdGeomXformOp::Type const opType, UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetXformOp (UsdGeomXformOp::Type const opType, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddTranslateOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetTranslateOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddScaleOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetScaleOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateXYZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateXYZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateXZYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateXZYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateYXZOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateYXZOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateYZXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateYZXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateZXYOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateZXYOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddRotateZYXOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetRotateZYXOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddOrientOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionFloat, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetOrientOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp AddTransformOp (UsdGeomXformOp::Precision const precision=UsdGeomXformOp::PrecisionDouble, TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API UsdGeomXformOp GetTransformOp (TfToken const &opSuffix=TfToken(), bool isInverseOp=false) const
 
USDGEOM_API bool SetResetXformStack (bool resetXform) const
 
USDGEOM_API bool GetResetXformStack () const
 
USDGEOM_API bool SetXformOpOrder (std::vector< UsdGeomXformOp > const &orderedXformOps, bool resetXformStack=false) const
 
USDGEOM_API std::vector
< UsdGeomXformOp
GetOrderedXformOps (bool *resetsXformStack) const
 
USDGEOM_API bool ClearXformOpOrder () const
 Clears the local transform stack. More...
 
USDGEOM_API UsdGeomXformOp MakeMatrixXform () const
 
USDGEOM_API bool TransformMightBeTimeVarying () const
 
USDGEOM_API bool TransformMightBeTimeVarying (const std::vector< UsdGeomXformOp > &ops) const
 
USDGEOM_API bool GetTimeSamples (std::vector< double > *times) const
 
USDGEOM_API bool GetTimeSamplesInInterval (const GfInterval &interval, std::vector< double > *times) const
 
USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, bool *resetsXformStack, const UsdTimeCode time=UsdTimeCode::Default()) const
 
USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, bool *resetsXformStack, const std::vector< UsdGeomXformOp > &ops, const UsdTimeCode time=UsdTimeCode::Default()) const
 
- Public Member Functions inherited from UsdGeomImageable
 UsdGeomImageable (const UsdPrim &prim=UsdPrim())
 
 UsdGeomImageable (const UsdSchemaBase &schemaObj)
 
virtual USDGEOM_API ~UsdGeomImageable ()
 Destructor. More...
 
USDGEOM_API UsdAttribute GetVisibilityAttr () const
 
USDGEOM_API UsdAttribute CreateVisibilityAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdAttribute GetPurposeAttr () const
 
USDGEOM_API UsdAttribute CreatePurposeAttr (VtValue const &defaultValue=VtValue(), bool writeSparsely=false) const
 
USDGEOM_API UsdRelationship GetProxyPrimRel () const
 
USDGEOM_API UsdRelationship CreateProxyPrimRel () const
 
USDGEOM_API void MakeVisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 
USDGEOM_API void MakeInvisible (const UsdTimeCode &time=UsdTimeCode::Default()) const
 
USDGEOM_API TfToken ComputeVisibility (UsdTimeCode const &time=UsdTimeCode::Default()) const
 
USDGEOM_API UsdAttribute GetPurposeVisibilityAttr (const TfToken &purpose=UsdGeomTokens->default_) const
 
USDGEOM_API TfToken ComputeEffectiveVisibility (const TfToken &purpose=UsdGeomTokens->default_, const UsdTimeCode &time=UsdTimeCode::Default()) const
 
USDGEOM_API PurposeInfo ComputePurposeInfo () const
 
USDGEOM_API PurposeInfo ComputePurposeInfo (const PurposeInfo &parentPurposeInfo) const
 
USDGEOM_API TfToken ComputePurpose () const
 
USDGEOM_API UsdPrim ComputeProxyPrim (UsdPrim *renderPrim=NULL) const
 
USDGEOM_API bool SetProxyPrim (const UsdPrim &proxy) const
 
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
 
USDGEOM_API GfBBox3d ComputeLocalBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 
USDGEOM_API GfBBox3d ComputeUntransformedBound (UsdTimeCode const &time, TfToken const &purpose1=TfToken(), TfToken const &purpose2=TfToken(), TfToken const &purpose3=TfToken(), TfToken const &purpose4=TfToken()) const
 
USDGEOM_API GfMatrix4d ComputeLocalToWorldTransform (UsdTimeCode const &time) const
 
USDGEOM_API GfMatrix4d ComputeParentToWorldTransform (UsdTimeCode const &time) const
 
- Public Member Functions inherited from UsdTyped
 UsdTyped (const UsdPrim &prim=UsdPrim())
 
 UsdTyped (const UsdSchemaBase &schemaObj)
 
virtual USD_API ~UsdTyped ()
 Destructor. More...
 
- Public Member Functions inherited from UsdSchemaBase
bool IsConcrete () const
 
bool IsTyped () const
 
bool IsAPISchema () const
 Returns whether this is an API schema or not. More...
 
bool IsAppliedAPISchema () const
 
bool IsMultipleApplyAPISchema () const
 
UsdSchemaKind GetSchemaKind () const
 Returns the kind of schema this class is. More...
 
USD_API UsdSchemaBase (const UsdPrim &prim=UsdPrim())
 Construct and store prim as the held prim. More...
 
USD_API UsdSchemaBase (const UsdSchemaBase &otherSchema)
 Construct and store for the same prim held by otherSchema. More...
 
virtual USD_API ~UsdSchemaBase ()
 Destructor. More...
 
USD_API operator bool () const
 
UsdPrim GetPrim () const
 Return this schema object's held prim. More...
 
SdfPath GetPath () const
 Shorthand for GetPrim()->GetPath(). More...
 
USD_API const UsdPrimDefinitionGetSchemaClassPrimDefinition () const
 

Static Public Member Functions

static USDGEOM_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDGEOM_API
UsdGeomPointInstancer 
Get (const UsdStagePtr &stage, const SdfPath &path)
 
static USDGEOM_API
UsdGeomPointInstancer 
Define (const UsdStagePtr &stage, const SdfPath &path)
 
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 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
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDGEOM_API UsdGeomBoundable Get (const UsdStagePtr &stage, const SdfPath &path)
 
static USDGEOM_API bool ComputeExtentFromPlugins (const UsdGeomBoundable &boundable, const UsdTimeCode &time, VtVec3fArray *extent)
 
static USDGEOM_API bool ComputeExtentFromPlugins (const UsdGeomBoundable &boundable, const UsdTimeCode &time, const GfMatrix4d &transform, VtVec3fArray *extent)
 
- Static Public Member Functions inherited from UsdGeomXformable
static USDGEOM_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDGEOM_API UsdGeomXformable Get (const UsdStagePtr &stage, const SdfPath &path)
 
static USDGEOM_API bool GetTimeSamples (std::vector< UsdGeomXformOp > const &orderedXformOps, std::vector< double > *times)
 
static USDGEOM_API bool GetTimeSamplesInInterval (std::vector< UsdGeomXformOp > const &orderedXformOps, const GfInterval &interval, std::vector< double > *times)
 
static USDGEOM_API bool GetLocalTransformation (GfMatrix4d *transform, std::vector< UsdGeomXformOp > const &ops, const UsdTimeCode time)
 
static USDGEOM_API bool IsTransformationAffectedByAttrNamed (const TfToken &attrName)
 
- Static Public Member Functions inherited from UsdGeomImageable
static USDGEOM_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USDGEOM_API UsdGeomImageable Get (const UsdStagePtr &stage, const SdfPath &path)
 
static USDGEOM_API const
TfTokenVector
GetOrderedPurposeTokens ()
 
- Static Public Member Functions inherited from UsdTyped
static USD_API const
TfTokenVector
GetSchemaAttributeNames (bool includeInherited=true)
 
static USD_API UsdTyped Get (const UsdStagePtr &stage, const SdfPath &path)
 
- Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVectorGetSchemaAttributeNames (bool includeInherited=true)
 

Static Public Attributes

static const UsdSchemaKind schemaKind = UsdSchemaKind::ConcreteTyped
 
- Static Public Attributes inherited from UsdGeomBoundable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 
- Static Public Attributes inherited from UsdGeomXformable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 
- Static Public Attributes inherited from UsdGeomImageable
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractTyped
 
- Static Public Attributes inherited from UsdTyped
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 
- Static Public Attributes inherited from UsdSchemaBase
static const UsdSchemaKind schemaKind = UsdSchemaKind::AbstractBase
 

Protected Member Functions

USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 
- Protected Member Functions inherited from UsdGeomXformable
USDGEOM_API UsdSchemaKind _GetSchemaKind () const override
 
- Protected Member Functions inherited from UsdTyped
USD_API bool _IsCompatible () const override
 
- 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
 
USDGEOM_API bool ActivateIds (VtInt64Array const &ids) const
 
USDGEOM_API bool ActivateAllIds () const
 
USDGEOM_API bool DeactivateId (int64_t id) const
 
USDGEOM_API bool DeactivateIds (VtInt64Array const &ids) const
 
USDGEOM_API bool VisId (int64_t id, UsdTimeCode const &time) const
 
USDGEOM_API bool VisIds (VtInt64Array const &ids, UsdTimeCode const &time) const
 
USDGEOM_API bool VisAllIds (UsdTimeCode const &time) const
 
USDGEOM_API bool InvisId (int64_t id, UsdTimeCode const &time) const
 
USDGEOM_API bool InvisIds (VtInt64Array const &ids, UsdTimeCode const &time) const
 
USDGEOM_API std::vector< bool > ComputeMaskAtTime (UsdTimeCode time, VtInt64Array const *ids=nullptr) const
 
USDGEOM_API bool UsesOrientationsf (UsdAttribute &rotationsAttr) const
 
template<class T >
static bool ApplyMaskToArray (std::vector< bool > const &mask, VtArray< T > *dataArray, const int elementSize=1)
 

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 UsdGeom_VelocityInterpolation .

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 UsdGeom_VelocityInterpolation .

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 278 of file pointInstancer.h.

Member Enumeration Documentation

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 857 of file pointInstancer.h.

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 846 of file pointInstancer.h.

Constructor & Destructor Documentation

UsdGeomPointInstancer::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 290 of file pointInstancer.h.

UsdGeomPointInstancer::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 298 of file pointInstancer.h.

virtual USDGEOM_API UsdGeomPointInstancer::~UsdGeomPointInstancer ( )
virtual

Destructor.

Member Function Documentation

USDGEOM_API UsdSchemaKind UsdGeomPointInstancer::_GetSchemaKind ( ) const
overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also
UsdSchemaKind

Reimplemented from UsdGeomBoundable.

USDGEOM_API bool UsdGeomPointInstancer::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())

USDGEOM_API bool UsdGeomPointInstancer::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())

USDGEOM_API bool UsdGeomPointInstancer::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())

template<class T >
bool UsdGeomPointInstancer::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 1216 of file pointInstancer.h.

USDGEOM_API bool UsdGeomPointInstancer::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.
USDGEOM_API bool UsdGeomPointInstancer::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 UsdGeomPointInstancer::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.
USDGEOM_API bool UsdGeomPointInstancer::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 bool UsdGeomPointInstancer::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.
static USDGEOM_API bool UsdGeomPointInstancer::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:
.
static USDGEOM_API bool UsdGeomPointInstancer::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
USDGEOM_API bool UsdGeomPointInstancer::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.
USDGEOM_API std::vector<bool> UsdGeomPointInstancer::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.

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

See GetAccelerationsAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetAngularVelocitiesAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetIdsAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetInvisibleIdsAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetOrientationsAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetOrientationsfAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetPositionsAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetProtoIndicesAttr(), and also Usd_Create_Or_Get_Property 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.

USDGEOM_API UsdRelationship UsdGeomPointInstancer::CreatePrototypesRel ( ) const

See GetPrototypesRel(), and also Usd_Create_Or_Get_Property for when to use Get vs Create

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

See GetScalesAttr(), and also Usd_Create_Or_Get_Property 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.

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

See GetVelocitiesAttr(), and also Usd_Create_Or_Get_Property 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.

USDGEOM_API bool UsdGeomPointInstancer::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.

USDGEOM_API bool UsdGeomPointInstancer::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.

static USDGEOM_API UsdGeomPointInstancer 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.

static USDGEOM_API UsdGeomPointInstancer 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));
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API size_t UsdGeomPointInstancer::GetInstanceCount ( UsdTimeCode  timeCode = UsdTimeCode::Default()) const

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

snippets.dox GetCount

See Also
GetProtoIndicesAttr()
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdAttribute UsdGeomPointInstancer::GetPositionsAttr ( ) const

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

Declaration point3f[] positions
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Point3fArray
USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
USDGEOM_API UsdRelationship UsdGeomPointInstancer::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.

USDGEOM_API UsdAttribute UsdGeomPointInstancer::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
static USDGEOM_API const TfTokenVector& UsdGeomPointInstancer::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.

USDGEOM_API UsdAttribute UsdGeomPointInstancer::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, UsdGeom_VelocityInterpolation .

Declaration vector3f[] velocities
C++ Type VtArray<GfVec3f>
Usd Type SdfValueTypeNames->Vector3fArray
USDGEOM_API bool UsdGeomPointInstancer::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.

USDGEOM_API bool UsdGeomPointInstancer::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.

USDGEOM_API bool UsdGeomPointInstancer::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
USDGEOM_API bool UsdGeomPointInstancer::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())

USDGEOM_API bool UsdGeomPointInstancer::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())

USDGEOM_API bool UsdGeomPointInstancer::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

friend class UsdSchemaRegistry
friend

Definition at line 362 of file pointInstancer.h.

Member Data Documentation

const UsdSchemaKind UsdGeomPointInstancer::schemaKind = UsdSchemaKind::ConcreteTyped
static

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

See Also
UsdSchemaKind

Definition at line 284 of file pointInstancer.h.


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