UsdGeomMotionAPI

Fully qualified name: usdrt::UsdGeomMotionAPI

class UsdGeomMotionAPI : public usdrt::UsdAPISchemaBase

UsdGeomMotionAPI encodes data that can live on any prim that may affect computations involving:

• computed motion for motion blur

• sampling for motion blur

The motion:blurScale attribute allows artists to scale the amount of motion blur to be rendered for parts of the scene without changing the recorded animation. See UsdGeomMotionAPI_blurScale for use and implementation details.

Public Functions

inline explicit UsdGeomMotionAPI(const UsdPrim &prim = UsdPrim())

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

inline explicit UsdGeomMotionAPI(const UsdSchemaBase &schemaObj)

Construct a UsdGeomMotionAPI on the prim held by schemaObj . Should be preferred over UsdGeomMotionAPI(schemaObj.GetPrim()), as it preserves SchemaBase state.

inline virtual ~UsdGeomMotionAPI()

Destructor.

inline UsdAttribute GetMotionBlurScaleAttr() const

BlurScale is an inherited float attribute that stipulates the rendered motion blur (as typically specified via UsdGeomCamera’s shutter:open and shutter:close properties) should be scaled for all objects at and beneath the prim in namespace on which the motion:blurScale value is specified.

Without changing any other data in the scene, blurScale allows artists to “dial in” the amount of blur on a per-object basis. A blurScale value of zero removes all blur, a value of 0.5 reduces blur by half, and a value of 2.0 doubles the blur. The legal range for blurScale is [0, inf), although very high values may result in extremely expensive renders, and may exceed the capabilities of some renderers.

Although renderers are free to implement this feature however they see fit, see UsdGeomMotionAPI_blurScale for our guidance on implementing the feature universally and efficiently.

Declaration	float motion:blurScale = 1
C++ Type	float
Usd Type	SdfValueTypeNames->Float

See also

ComputeMotionBlurScale()

inline UsdAttribute CreateMotionBlurScaleAttr() const

See GetMotionBlurScaleAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetVelocityScaleAttr() const

Deprecated:

VelocityScale is an inherited float attribute that velocity-based schemas (e.g. PointBased, PointInstancer) can consume to compute interpolated positions and orientations by applying velocity and angularVelocity, which is required for interpolating between samples when topology is varying over time. Although these quantities are generally physically computed by a simulator, sometimes we require more or less motion-blur to achieve the desired look. VelocityScale allows artists to dial-in, as a post-sim correction, a scale factor to be applied to the velocity prior to computing interpolated positions from it.

Declaration	float motion:velocityScale = 1
C++ Type	float
Usd Type	SdfValueTypeNames->Float

inline UsdAttribute CreateVelocityScaleAttr() const

See GetVelocityScaleAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

inline UsdAttribute GetNonlinearSampleCountAttr() const

Determines the number of position or transformation samples created when motion is described by attributes contributing non-linear terms.

To give an example, imagine an application (such as a renderer) consuming ‘points’ and the USD document also contains ‘accelerations’ for the same prim. Unless the application can consume these ‘accelerations’ itself, an intermediate layer has to compute samples within the sampling interval for the point positions based on the value of ‘points’, ‘velocities’ and ‘accelerations’. The number of these samples is given by ‘nonlinearSampleCount’. The samples are equally spaced within the sampling interval.

Another example involves the PointInstancer where ‘nonlinearSampleCount’ is relevant when ‘angularVelocities’ or ‘accelerations’ are authored.

‘nonlinearSampleCount’ is an inherited attribute, also see ComputeNonlinearSampleCount()

Declaration	int motion:nonlinearSampleCount = 3
C++ Type	int
Usd Type	SdfValueTypeNames->Int

inline UsdAttribute CreateNonlinearSampleCountAttr() const

See GetNonlinearSampleCountAttr(), and also Create vs Get Property Methods for when to use Get vs Create. If specified, author defaultValue as the attribute’s default, sparsely (when it makes sense to do so) if writeSparsely is true - the default for writeSparsely is false.

UsdPrim GetPrim() const

Return this schema object’s held prim.

SdfPath GetPath() const

Return the SdfPath to this schema object’s held prim.

inline explicit operator bool() const

Check if this schema object is compatible with it’s held prim and that the prim is valid.

A typed schema object is compatible if the held prim’s type is or is a subtype of the schema’s type. Based on prim.IsA().

An API schema object is compatible if the API is of type SingleApplyAPI or UsdSchemaType::MultipleApplyAPI, and the schema has been applied to the prim. Based on prim.HasAPI.

This method invokes polymorphic behaviour.

See also

UsdSchemaBase::_IsCompatible()

Returns:

True if the help prim is valid, and the schema object is compatible with its held prim.

Public Static Functions

static inline UsdGeomMotionAPI Apply(const UsdPrim &prim)

Applies this single-apply API schema to the given prim. This information is stored by adding “MotionAPI” to the token-valued, listOp metadata apiSchemas on the prim.

See also

UsdPrim::GetAppliedSchemas()

See also

UsdPrim::HasAPI()

See also

UsdPrim::ApplyAPI()

See also

UsdPrim::RemoveAPI()

Returns:

A valid UsdGeomMotionAPI object is returned upon success. An invalid (or empty) UsdGeomMotionAPI object is returned upon failure. See UsdPrim::ApplyAPI() for conditions resulting in failure.

Public Static Attributes

static const UsdSchemaType schemaType = UsdSchemaType::SingleApplyAPI

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

See also

UsdSchemaType

Protected Functions

inline const TfToken &_GetInstanceName() const

Returns the instance name of the API schema object belonging to a multiple-apply API schema.

The returned instance name will be empty for non-applied and single-apply API schemas.

inline virtual bool _IsCompatible() const

Check whether this APISchema object is valid for the currently held prim.

If this is an applied API schema, this returns true if the held prim is valid and already has the API schema applied to it, along with the instanceName (in the case of multiple-apply). The instanceName should not be empty in the case of a multiple-apply API schema.

This check is performed when clients invoke the explicit bool conversion operator, implemented in UsdSchemaBase.

See also

UsdPrim::HasAPI()

inline const TfToken _GetType() const

Helper for subclasses to get this schema’s type token.

Note

This diverges from Usd and returns a TfToken, since we don’t implements TfType.

Returns:

The token representing the schema’s TfType.