UsdGeomXformCommonAPI Class Reference

#include <xformCommonAPI.h>

Inheritance diagram for UsdGeomXformCommonAPI:

Classes
struct	Ops

Public Types
enum	RotationOrder {   RotationOrderXYZ, RotationOrderXZY, RotationOrderYXZ, RotationOrderYZX,   RotationOrderZXY, RotationOrderZYX }
	Enumerates the rotation order of the 3-angle Euler rotation. More...
enum	OpFlags {   OpNone = 0, OpTranslate = 1, OpPivot = 2, OpRotate = 4,   OpScale = 8 }

Public Member Functions
	UsdGeomXformCommonAPI (const UsdPrim &prim=UsdPrim())
	UsdGeomXformCommonAPI (const UsdSchemaBase &schemaObj)
virtual USDGEOM_API	~UsdGeomXformCommonAPI ()
	Destructor. More...
USDGEOM_API bool	SetXformVectors (const GfVec3d &translation, const GfVec3f &rotation, const GfVec3f &scale, const GfVec3f &pivot, RotationOrder rotOrder, const UsdTimeCode time) const
USDGEOM_API bool	GetXformVectors (GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, RotationOrder *rotOrder, const UsdTimeCode time) const
USDGEOM_API bool	GetXformVectorsByAccumulation (GfVec3d *translation, GfVec3f *rotation, GfVec3f *scale, GfVec3f *pivot, UsdGeomXformCommonAPI::RotationOrder *rotOrder, const UsdTimeCode time) const
USDGEOM_API bool	GetResetXformStack () const
API for setting individual ops independently.
USDGEOM_API bool	SetTranslate (const GfVec3d &translation, const UsdTimeCode time=UsdTimeCode::Default()) const
	Set translation at time to translation. More...
USDGEOM_API bool	SetPivot (const GfVec3f &pivot, const UsdTimeCode time=UsdTimeCode::Default()) const
	Set pivot position at time to pivot. More...
USDGEOM_API bool	SetRotate (const GfVec3f &rotation, UsdGeomXformCommonAPI::RotationOrder rotOrder=RotationOrderXYZ, const UsdTimeCode time=UsdTimeCode::Default()) const
	Set rotation at time to rotation. More...
USDGEOM_API bool	SetScale (const GfVec3f &scale, const UsdTimeCode time=UsdTimeCode::Default()) const
	Set scale at time to scale. More...
USDGEOM_API bool	SetResetXformStack (bool resetXformStack) const
USDGEOM_API Ops	CreateXformOps (RotationOrder rotOrder, OpFlags op1=OpNone, OpFlags op2=OpNone, OpFlags op3=OpNone, OpFlags op4=OpNone) const
USDGEOM_API Ops	CreateXformOps (OpFlags op1=OpNone, OpFlags op2=OpNone, OpFlags op3=OpNone, OpFlags op4=OpNone) const
Public Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim=UsdPrim())
	UsdAPISchemaBase (const UsdSchemaBase &schemaObj)
virtual USD_API	~UsdAPISchemaBase ()=0
	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 UsdPrimDefinition *	GetSchemaClassPrimDefinition () const

Static Public Member Functions
static USDGEOM_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)
static USDGEOM_API UsdGeomXformCommonAPI	Get (const UsdStagePtr &stage, const SdfPath &path)
static USDGEOM_API UsdGeomXformOp::Type	ConvertRotationOrderToOpType (RotationOrder rotOrder)
static USDGEOM_API RotationOrder	ConvertOpTypeToRotationOrder (UsdGeomXformOp::Type opType)
static USDGEOM_API bool	CanConvertOpTypeToRotationOrder (UsdGeomXformOp::Type opType)
Computing transforms
static USDGEOM_API GfMatrix4d	GetRotationTransform (const GfVec3f &rotation, const UsdGeomXformCommonAPI::RotationOrder rotationOrder)
Static Public Member Functions inherited from UsdAPISchemaBase
static USD_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)
Static Public Member Functions inherited from UsdSchemaBase
static const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)

Static Public Attributes
static const UsdSchemaKind	schemaKind = UsdSchemaKind::NonAppliedAPI
Static Public Attributes inherited from UsdAPISchemaBase
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
USDGEOM_API bool	_IsCompatible () const override
	Returns whether the underlying xformable is compatible with the API. More...
Protected Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
	UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
const TfToken &	_GetInstanceName () const
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

Additional Inherited Members
Static Protected Member Functions inherited from UsdAPISchemaBase
static USD_API TfTokenVector	_GetMultipleApplyInstanceNames (const UsdPrim &prim, const TfType &schemaType)

Detailed Description

This class provides API for authoring and retrieving a standard set of component transformations which include a scale, a rotation, a scale-rotate pivot and a translation. The goal of the API is to enhance component-wise interchange. It achieves this by limiting the set of allowed basic ops and by specifying the order in which they are applied. In addition to the basic set of ops, the 'resetXformStack' bit can also be set to indicate whether the underlying xformable resets the parent transformation (i.e. does not inherit it's parent's transformation).

See Also

UsdGeomXformCommonAPI::GetResetXformStack()

UsdGeomXformCommonAPI::SetResetXformStack()

The operator-bool for the class will inform you whether an existing xformable is compatible with this API.

The scale-rotate pivot is represented by a pair of (translate, inverse-translate) xformOps around the scale and rotate operations. The rotation operation can be any of the six allowed Euler angle sets.

See Also

UsdGeomXformOp::Type.

The xformOpOrder of an xformable that has all of the supported basic ops is as follows: ["xformOp:translate", "xformOp:translate:pivot", "xformOp:rotateXYZ", "xformOp:scale", "!invert!xformOp:translate:pivot"].

It is worth noting that all of the ops are optional. For example, an xformable may have only a translate or a rotate. It would still be considered as compatible with this API. Individual SetTranslate(), SetRotate(), SetScale() and SetPivot() methods are provided by this API to allow such sparse authoring.

Definition at line 89 of file xformCommonAPI.h.

Member Enumeration Documentation

enum UsdGeomXformCommonAPI::OpFlags

Enumerates the categories of ops that can be handled by XformCommonAPI. For use with CreateXformOps().

Enumerator
OpNone
OpTranslate
OpPivot
OpRotate
OpScale

Definition at line 182 of file xformCommonAPI.h.

enum UsdGeomXformCommonAPI::RotationOrder

Enumerates the rotation order of the 3-angle Euler rotation.

Enumerator
RotationOrderXYZ
RotationOrderXZY
RotationOrderYXZ
RotationOrderYZX
RotationOrderZXY
RotationOrderZYX

Definition at line 171 of file xformCommonAPI.h.

Constructor & Destructor Documentation

UsdGeomXformCommonAPI::UsdGeomXformCommonAPI ( const UsdPrim &  prim = UsdPrim() )

inlineexplicit

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

Definition at line 101 of file xformCommonAPI.h.

UsdGeomXformCommonAPI::UsdGeomXformCommonAPI ( const UsdSchemaBase &  schemaObj )

inlineexplicit

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

Definition at line 109 of file xformCommonAPI.h.

virtual USDGEOM_API UsdGeomXformCommonAPI::~UsdGeomXformCommonAPI ( )

virtual

Destructor.

Member Function Documentation

USDGEOM_API UsdSchemaKind UsdGeomXformCommonAPI::_GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also

UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

USDGEOM_API bool UsdGeomXformCommonAPI::_IsCompatible ( ) const

overrideprotectedvirtual

Returns whether the underlying xformable is compatible with the API.

Reimplemented from UsdAPISchemaBase.

static USDGEOM_API bool UsdGeomXformCommonAPI::CanConvertOpTypeToRotationOrder ( UsdGeomXformOp::Type  opType )

static

Whether the given opType has a corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum (i.e., whether it is a three-axis rotation).

static USDGEOM_API RotationOrder UsdGeomXformCommonAPI::ConvertOpTypeToRotationOrder ( UsdGeomXformOp::Type  opType )

static

Converts the given opType to the corresponding value in the UsdGeomXformCommonAPI::RotationOrder enum. For example, TypeRotateYZX corresponds to RotationOrderYZX. Raises a coding error if opType is not convertible to RotationOrder (i.e., if it isn't a three-axis rotation) and returns the default RotationOrderXYZ instead.

static USDGEOM_API UsdGeomXformOp::Type UsdGeomXformCommonAPI::ConvertRotationOrderToOpType ( RotationOrder  rotOrder )

static

Converts the given rotOrder to the corresponding value in the UsdGeomXformOp::Type enum. For example, RotationOrderYZX corresponds to TypeRotateYZX. Raises a coding error if rotOrder is not one of the named enumerators of RotationOrder.

USDGEOM_API Ops UsdGeomXformCommonAPI::CreateXformOps	(	RotationOrder	rotOrder,
		OpFlags	op1 = OpNone,
		OpFlags	op2 = OpNone,
		OpFlags	op3 = OpNone,
		OpFlags	op4 = OpNone
	)		const

Creates the specified XformCommonAPI-compatible xform ops, or returns the existing ops if they already exist. If successful, returns an Ops object with all the ops on this prim, identified by type. If the requested xform ops couldn't be created or the prim is not XformCommonAPI-compatible, returns an Ops object with all invalid ops.

The rotOrder is only used if OpRotate is specified. Otherwise, it is ignored. (If you don't need to create a rotate op, you might find it helpful to use the other overload that takes no rotation order.)

USDGEOM_API Ops UsdGeomXformCommonAPI::CreateXformOps	(	OpFlags	op1 = OpNone,
		OpFlags	op2 = OpNone,
		OpFlags	op3 = OpNone,
		OpFlags	op4 = OpNone
	)		const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. This overload does not take a rotation order. If you specify OpRotate, then this overload assumes RotationOrderXYZ or the previously-authored rotation order. (If you do need to create a rotate op, you might find it helpful to use the other overload that explicitly takes a rotation order.)

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

static

Return a UsdGeomXformCommonAPI 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:

UsdGeomXformCommonAPI(stage->GetPrimAtPath(path));

USDGEOM_API bool UsdGeomXformCommonAPI::GetResetXformStack

(

)

const

Returns whether the xformable resets the transform stack. i.e., does not inherit the parent transformation.

static USDGEOM_API GfMatrix4d UsdGeomXformCommonAPI::GetRotationTransform ( const GfVec3f &  rotation, const UsdGeomXformCommonAPI::RotationOrder  rotationOrder  )

static

Return the 4x4 matrix that applies the rotation encoded by rotation vector rotation using the rotation order rotationOrder.

Deprecated:

Please use the result of ConvertRotationOrderToOpType() along with UsdGeomXformOp::GetOpTransform() instead.

static USDGEOM_API const TfTokenVector& UsdGeomXformCommonAPI::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 bool UsdGeomXformCommonAPI::GetXformVectors	(	GfVec3d *	translation,
		GfVec3f *	rotation,
		GfVec3f *	scale,
		GfVec3f *	pivot,
		RotationOrder *	rotOrder,
		const UsdTimeCode	time
	)		const

Retrieve values of the various component xformOps at a given time. Identity values are filled in for the component xformOps that don't exist or don't have an authored value.

Note

This method works even on prims with an incompatible xform schema, i.e. when the bool operator returns false.

When the underlying xformable has an incompatible xform schema, it performs a full-on matrix decomposition to XYZ rotation order.

USDGEOM_API bool UsdGeomXformCommonAPI::GetXformVectorsByAccumulation	(	GfVec3d *	translation,
		GfVec3f *	rotation,
		GfVec3f *	scale,
		GfVec3f *	pivot,
		UsdGeomXformCommonAPI::RotationOrder *	rotOrder,
		const UsdTimeCode	time
	)		const

Retrieve values of the various component xformOps at a given time. Identity values are filled in for the component xformOps that don't exist or don't have an authored value.

This method allows some additional flexibility for xform schemas that do not strictly adhere to the xformCommonAPI. For incompatible schemas, this method will attempt to reduce the schema into one from which component vectors can be extracted by accumulating xformOp transforms of the common types.

Note

When the underlying xformable has a compatible xform schema, the usual component value extraction method is used instead. When the xform schema is incompatible and it cannot be reduced by accumulating transforms, it performs a full-on matrix decomposition to XYZ rotation order.

USDGEOM_API bool UsdGeomXformCommonAPI::SetPivot	(	const GfVec3f &	pivot,
		const UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Set pivot position at time to pivot.

USDGEOM_API bool UsdGeomXformCommonAPI::SetResetXformStack

(

bool

resetXformStack

)

const

Set whether the xformable resets the transform stack. i.e., does not inherit the parent transformation.

USDGEOM_API bool UsdGeomXformCommonAPI::SetRotate	(	const GfVec3f &	rotation,
		UsdGeomXformCommonAPI::RotationOrder	rotOrder = RotationOrderXYZ,
		const UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Set rotation at time to rotation.

USDGEOM_API bool UsdGeomXformCommonAPI::SetScale	(	const GfVec3f &	scale,
		const UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Set scale at time to scale.

USDGEOM_API bool UsdGeomXformCommonAPI::SetTranslate	(	const GfVec3d &	translation,
		const UsdTimeCode	time = UsdTimeCode::Default()
	)		const

Set translation at time to translation.

USDGEOM_API bool UsdGeomXformCommonAPI::SetXformVectors	(	const GfVec3d &	translation,
		const GfVec3f &	rotation,
		const GfVec3f &	scale,
		const GfVec3f &	pivot,
		RotationOrder	rotOrder,
		const UsdTimeCode	time
	)		const

Set values for the various component xformOps at a given time.

Calling this method will call all of the supported ops to be created, even if they only contain default (identity) values.

To author individual operations selectively, use the Set[OpType]() API.

Note

Once the rotation order has been established for a given xformable (either because of an already defined (and compatible) rotate op or from calling SetXformVectors() or SetRotate()), it cannot be changed.

Friends And Related Function Documentation

friend class UsdSchemaRegistry

friend

Definition at line 148 of file xformCommonAPI.h.

Member Data Documentation

const UsdSchemaKind UsdGeomXformCommonAPI::schemaKind = UsdSchemaKind::NonAppliedAPI

static

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

See Also

UsdSchemaKind

Definition at line 95 of file xformCommonAPI.h.

---

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

• pxr/usd/usdGeom/xformCommonAPI.h