|
HDK
|
#include <pointInstancer.h>
Inheritance diagram for UsdGeomPointInstancer:Public Types | |
| enum | ProtoXformInclusion { IncludeProtoXform, ExcludeProtoXform } |
| enum | MaskApplication { ApplyMask, IgnoreMask } |
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 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 TfTokenVector & | GetSchemaAttributeNames (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 | |
| 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 |
| template<class T > | |
| static bool | ApplyMaskToArray (std::vector< bool > const &mask, VtArray< T > *dataArray, const int elementSize=1) |
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.
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.
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:
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 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:
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().
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()
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()
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,
Definition at line 278 of file pointInstancer.h.
Encodes whether to evaluate and apply the PointInstancer's mask to computed results.
| Enumerator | |
|---|---|
| ApplyMask |
Compute and apply the PointInstancer mask. |
| IgnoreMask |
Ignore the PointInstancer mask. |
Definition at line 811 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 800 of file pointInstancer.h.
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.
|
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 |
Destructor.
|
overrideprotectedvirtual |
Returns the kind of schema this class belongs to.
Reimplemented from UsdGeomBoundable.
| USDGEOM_API bool UsdGeomPointInstancer::ActivateAllIds | ( | ) | const |
| 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())
|
static |
Contract dataArray in-place to contain only the elements whose index in mask is true.
mask specifies "all pass", in which case dataArray is trivially unmodifieddataArray to be NULL .Definition at line 1114 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.
| 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.
| 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 NULLtime and baseTime is numeric and the other is UsdTimeCode::Default() (they must either both be numeric or both be default)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.
| 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 |
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.
| 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 | - |
| 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 .
| 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)
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::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 |
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 |
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:
| 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
| 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::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 |
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::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())
|
friend |
Definition at line 362 of file pointInstancer.h.
|
static |
Compile time constant representing what kind of schema this class is.
Definition at line 284 of file pointInstancer.h.
1.8.6