usdrt::RtXformable

Defined in usdrt/scenegraph/usd/rt/xformable.h

class RtXformable

RtXformable

The RtXformable class provides a schema for reading and writing the OmniHydra and Fabric Scene Delegate transform attributes.

Fabric Scene Delegate

As of Kit 105.2, Fabric Scene Delegate (active by default in USD Explorer, can be optionally enabled in any Kit-based application) leverages Fabric’s Connectivity API to represent scenegraph and transform hierarchies directly in Fabric without requiring a USD lookback for this information. This enables changes to the transform of a prim in Fabric to affect the transform of that prim’s descendants in Fabric without any coordination with USD stage (or without a USD stage or at all).

The Fabric Hierarchy local and world transform values are created and populated on every Imageable prim in Fabric at USD stage load time when Fabric Scene Delegate is enabled.

The primary way to set transform data for Fabric Scene Delegate is by operating on the Fabric Hierarchy local transform matrix of a prim. You can also query the world transform of the prim (computed by the IFabricHierarchy interface) through the world matrix attribute.

Name	Fabric Attribute Name	Type	APIs
fabric hierarchy local matrix	omni:fabric:localMatrix	matrix4d	Create/GetFabricHierarchyLocalMatrixAttr
fabric hierarchy world matrix	omni:fabric:worldMatrix	matrix4d	Create/GetFabricHeirarchyWorldMatrixAttr

OmniHydra Scene Delegate

The OmniHydra scene delegate (active in Composer and all other Kit-based applications) will query Fabric for changes to these special attributes when discovering transform data in the Hydra render index. This enables faster updates of prim transforms than USD and UsdImaging conventionally allow.

There are two ways to set transform data with this API:

world transform
local transform

If any world transform attribute is set on a prim in Fabric, it will take precedence over any other transform data from USD or Fabric. The world transform is specified in three parts.

Name	Fabric Attribute Name	Type	APIs
position	_worldPosition	double3	Create/GetWorldPositionAttr
orientation	_worldOrientation	quatf	Create/GetWorldOrientationAttr
scale	_worldScale	vec3f	Create/GetWorldScaleAttr

If only one or two of the world transform attributes exist in Fabric, OmniHydra will use default values for the remaining attributes.

If no world transform attributes are set in Fabric, a local transform may be specified for a prim. (If any world transform attribute is specified, a local transform is ignored). This local transform will take precedence over local transform data from USD for the prim, but otherwise continue to participate in the transform hierarchy - changes to parent prims will continue to affect the overall transform of the prim.

Name	Fabric Attribute Name	Type	APIs
localMatrix	_localMatrix	matrix4d	Create/GetLocalMatrixAttr

Helper methods are provided to set either the world-space transform attribute values or the local transform value in Fabric using the computed values from the USD prim:

SetWorldXformFromUsd()
SetLocalXformFromUsd()

Subclassed by usdrt::RtBoundable

Public Functions

inline RtXformable(const UsdPrim &prim = UsdPrim())

Construct a RtXformable instance from a UsdPrim. Providing an invalid UsdPrim will result in an invalid RtXformable.

Parameters: prim – The prim to use to construct the RtXformable

RtXformable(const RtXformable &xform) = default: Copy constructor.

inline operator bool() const: Returns true if the underlying UsdPrim is valid, False otherwise.

inline UsdPrim GetPrim() const: Return the held UsdPrim.

inline SdfPath GetPath() const: Return the SdfPath of the held UsdPrim.

inline UsdAttribute GetFabricHierarchyLocalMatrixAttr() const

Fabric Hierarchy local matrix is the local transform of the prim, relative to its parent when Fabric Scene Delegate is enabled. Changes to this attribute will cause the Fabric Hierarchy world matrix value to be updated on a subsequent call to IFabricHierarcy::updateWorldXforms - this happens automatically before each render frame when Fabric Scene Delegate is enabled.


C++ Type	GfMatrix4d
ValueTypeName	Matrix4d

inline UsdAttribute CreateFabricHierarchyLocalMatrixAttr(const GfMatrix4d &defaultValue = GfMatrix4d(1)) const

Create or get the existing Fabric Hierarchy local matrix attribute.

Parameters: defaultValue – The value to set when creating the local matrix attribute in Fabric

inline UsdAttribute GetFabricHierarchyWorldMatrixAttr() const

Fabric Hierarchy world matrix is the local-to-world transform of the prim when Fabric Scene Delegate is enabled. Changes to this attribute will cause the Fabric Hierarchy local matrix value to be updated on a subsequent call to IFabricHierarcy::updateWorldXforms, by computing the value relative to the computed world transform of the parent prim - this happens automatically before each render frame when Fabric Scene Delegate is enabled.


C++ Type	GfMatrix4d
ValueTypeName	Matrix4d

inline UsdAttribute CreateFabricHierarchyWorldMatrixAttr(const GfMatrix4d &defaultValue = GfMatrix4d(1)) const

Create or get the existing Fabric Hierarchy world matrix attribute.

Parameters: defaultValue – The value to set when creating the world matrix attribute in Fabric

inline UsdAttribute GetWorldPositionAttr() const

World Position is the absolute, world-space translation of the prim. If this attribute is set in Fabric, OmniHydra will disregard all other transform data for this prim and use this and any other world transform attributes in Fabric for the Hydra rprim.


C++ Type	GfVec3d
ValueTypeName	Double3

inline UsdAttribute CreateWorldPositionAttr(const GfVec3d &defaultValue = GfVec3d(0)) const

Create or get the existing world position attribute.

Parameters: defaultValue – The value to set when creating the world position attribute in Fabric

inline UsdAttribute GetWorldOrientationAttr() const

World Orientation is the absolute, world-space rotation of the prim. If this attribute is set in Fabric, OmniHydra will disregard all other transform data for this prim and use this and any other world transform attributes in Fabric for the Hydra rprim.


C++ Type	GfQuatf
ValueTypeName	Quatf

inline UsdAttribute CreateWorldOrientationAttr(const GfQuatf &defaultValue = GfQuatf(1)) const

Create or get the existing world orientation attribute.

Parameters: defaultValue – The value to set when creating the world orientation attribute in Fabric

inline UsdAttribute GetWorldScaleAttr() const

World Scale is the absolute, world-space scale of the prim. If this attribute is set in Fabric, OmniHydra will disregard all other transform data for this prim and use this and any other world transform attributes in Fabric for the Hydra rprim.


C++ Type	GfVec3f
ValueTypeName	Vector3f

inline UsdAttribute CreateWorldScaleAttr(const GfVec3f &defaultValue = GfVec3f(1)) const

Create or get the existing world scale attribute.

Parameters: defaultValue – The value to set when creating the world scale attribute in Fabric

inline UsdAttribute GetLocalMatrixAttr() const

Local Matrix is the local transform of the prim, relative to its parent. Updates to ancestor transforms will continue to affect the overall transform of this prim in OmniHydra. If this attribute is set in Fabric, OmniHydra will disregard any local transform data for this prim in USD. If any world transform attributes are set for the prim in Fabric, this attribute will be ignored by OmniHydra.


C++ Type	GfMatrix4d
ValueTypeName	Matrix4d

inline UsdAttribute CreateLocalMatrixAttr(const GfMatrix4d &defaultValue = GfMatrix4d(1)) const

Create or get the existing local matrix attribute.

Parameters: defaultValue – The value to set when creating the local matrix attribute in Fabric

inline bool HasWorldXform() const

Check if the Fabric prim has any world transform attributes.

Returns: true if any world transform attributes exist in Fabric

inline bool ClearWorldXform()

Remove any world transform attributes from the Fabric prim.

Returns: true if any world transform attributes existed and were removed

inline bool SetWorldXformFromUsd()

Set the world position, orientation, and scale from the underlying USD prim.

Returns: true if all world transform attributes were created and set or updated from USD

inline bool HasLocalXform() const

Check if the Fabric prim has the local transform attribute set.

Returns: true if the local transform attribute exists in Fabric

inline bool ClearLocalXform()

Remove the local transform attribute from the Fabric prim.

Returns: true if the local transform attribute existed and was removed

inline bool SetLocalXformFromUsd() const

Set the local transform attribute in Fabric from the underlying USD prim’s local transform relative to its parent.

Returns: true if the local transform attribute was created and set or updated from USD

Protected Attributes

UsdPrim m_prim