UsdShadeCoordSysAPI Class Reference

#include <coordSysAPI.h>

Inheritance diagram for UsdShadeCoordSysAPI:

Classes
struct	Binding

Public Member Functions
	UsdShadeCoordSysAPI (const UsdPrim &prim=UsdPrim(), const TfToken &name=TfToken())
	UsdShadeCoordSysAPI (const UsdSchemaBase &schemaObj, const TfToken &name)
virtual USDSHADE_API	~UsdShadeCoordSysAPI ()
	Destructor. More...
TfToken	GetName () const
	Returns the name of this multiple-apply schema instance. More...
USDSHADE_API UsdRelationship	GetBindingRel () const
USDSHADE_API UsdRelationship	CreateBindingRel () const
USDSHADE_API bool	HasLocalBindings () const
USDSHADE_API std::vector< Binding >	GetLocalBindings () const
USDSHADE_API Binding	GetLocalBinding () const
USDSHADE_API std::vector< Binding >	FindBindingsWithInheritance () const
USDSHADE_API Binding	FindBindingWithInheritance () const
USDSHADE_API bool	Bind (const TfToken &name, const SdfPath &path) const
USDSHADE_API bool	ApplyAndBind (const TfToken &name, const SdfPath &path) const
USDSHADE_API bool	Bind (const SdfPath &path) const
USDSHADE_API bool	ClearBinding (const TfToken &name, bool removeSpec) const
USDSHADE_API bool	ClearBinding (bool removeSpec) const
USDSHADE_API bool	BlockBinding (const TfToken &name) const
USDSHADE_API bool	BlockBinding () const
USDSHADE_API TfToken	GetBindingBaseName () 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 USDSHADE_API const TfTokenVector &	GetSchemaAttributeNames (bool includeInherited=true)
static USDSHADE_API TfTokenVector	GetSchemaAttributeNames (bool includeInherited, const TfToken &instanceName)
static USDSHADE_API UsdShadeCoordSysAPI	Get (const UsdStagePtr &stage, const SdfPath &path)
static USDSHADE_API UsdShadeCoordSysAPI	Get (const UsdPrim &prim, const TfToken &name)
static USDSHADE_API std::vector < UsdShadeCoordSysAPI >	GetAll (const UsdPrim &prim)
static USDSHADE_API bool	IsSchemaPropertyBaseName (const TfToken &baseName)
static USDSHADE_API bool	IsCoordSysAPIPath (const SdfPath &path, TfToken *name)
static USDSHADE_API bool	CanApply (const UsdPrim &prim, const TfToken &name, std::string *whyNot=nullptr)
static USDSHADE_API UsdShadeCoordSysAPI	Apply (const UsdPrim &prim, const TfToken &name)
static USDSHADE_API bool	HasLocalBindingsForPrim (const UsdPrim &prim)
static USDSHADE_API std::vector< Binding >	GetLocalBindingsForPrim (const UsdPrim &prim)
static USDSHADE_API std::vector< Binding >	FindBindingsWithInheritanceForPrim (const UsdPrim &prim)
static USDSHADE_API TfToken	GetCoordSysRelationshipName (const std::string &coordSysName)
static USDSHADE_API bool	CanContainPropertyName (const TfToken &name)
	Test whether a given name contains the "coordSys:" prefix. More...
static USDSHADE_API TfToken	GetBindingBaseName (const TfToken &name)
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::MultipleApplyAPI
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
USDSHADE_API UsdSchemaKind	_GetSchemaKind () const override
Protected Member Functions inherited from UsdAPISchemaBase
	UsdAPISchemaBase (const UsdPrim &prim, const TfToken &instanceName)
	UsdAPISchemaBase (const UsdSchemaBase &schemaObj, const TfToken &instanceName)
const TfToken &	_GetInstanceName () const
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

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

Detailed Description

UsdShadeCoordSysAPI provides a way to designate, name, and discover coordinate systems.

Coordinate systems are implicitly established by UsdGeomXformable prims, using their local space. That coordinate system may be bound (i.e., named) from another prim. The binding is encoded as a single-target relationship. Coordinate system bindings apply to descendants of the prim where the binding is expressed, but names may be re-bound by descendant prims.

CoordSysAPI is a multi-apply API schema, where instance names signify the named coordinate systems. The instance names are used with the "coordSys:" namespace to determine the binding to the UsdGeomXformable prim.

Named coordinate systems are useful in shading (and other) workflows. An example is projection paint, which projects a texture from a certain view (the paint coordinate system), encoded as (e.g.) "rel coordSys:paint:binding". Using the paint coordinate frame avoids the need to assign a UV set to the object, and can be a concise way to project paint across a collection of objects with a single shared paint coordinate system.

Definition at line 82 of file coordSysAPI.h.

Constructor & Destructor Documentation

UsdShadeCoordSysAPI::UsdShadeCoordSysAPI ( const UsdPrim &  prim = UsdPrim(), const TfToken &  name = TfToken()  )

inlineexplicit

Construct a UsdShadeCoordSysAPI on UsdPrim prim with name name . Equivalent to UsdShadeCoordSysAPI::Get( prim.GetStage(), prim.GetPath().AppendProperty( "coordSys:name"));

for a valid prim, but will not immediately throw an error for an invalid prim

Definition at line 99 of file coordSysAPI.h.

UsdShadeCoordSysAPI::UsdShadeCoordSysAPI ( const UsdSchemaBase &  schemaObj, const TfToken &  name  )

inlineexplicit

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

Definition at line 108 of file coordSysAPI.h.

virtual USDSHADE_API UsdShadeCoordSysAPI::~UsdShadeCoordSysAPI ( )

virtual

Destructor.

Member Function Documentation

USDSHADE_API UsdSchemaKind UsdShadeCoordSysAPI::_GetSchemaKind ( ) const

overrideprotectedvirtual

Returns the kind of schema this class belongs to.

See Also

UsdSchemaKind

Reimplemented from UsdAPISchemaBase.

static USDSHADE_API UsdShadeCoordSysAPI UsdShadeCoordSysAPI::Apply ( const UsdPrim &  prim, const TfToken &  name  )

static

Applies this multiple-apply API schema to the given prim along with the given instance name, name.

This information is stored by adding "CoordSysAPI:<i>name</i>" to the token-valued, listOp metadata apiSchemas on the prim. For example, if name is 'instance1', the token 'CoordSysAPI:instance1' is added to 'apiSchemas'.

Returns

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

See Also

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

USDSHADE_API bool UsdShadeCoordSysAPI::ApplyAndBind	(	const TfToken &	name,
		const SdfPath &	path
	)		const

A convinience API for clients to use to Apply schema in accordance with new UsdShadeCoordSysAPI schema constructs and appropriate Bind the target. Note that this is only for clients using old behavior.

Deprecated:

USDSHADE_API bool UsdShadeCoordSysAPI::Bind	(	const TfToken &	name,
		const SdfPath &	path
	)		const

Bind the name to the given path. The prim at the given path is expected to be UsdGeomXformable, in order for the binding to be succesfully resolved.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, adds a binding conforming to the new multi-apply UsdShadeCoordSysAPI schema. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to also bind to multi-apply API compliant relationship for the prim, along with backward compatible deprecated behavior.

USDSHADE_API bool UsdShadeCoordSysAPI::Bind

(

const SdfPath &

path

)

const

Bind the name to the given path. The prim at the given path is expected to be UsdGeomXformable, in order for the binding to be succesfully resolved.

USDSHADE_API bool UsdShadeCoordSysAPI::BlockBinding

(

const TfToken &

name

)

const

Block the indicated coordinate system binding on this prim by blocking targets on the underlying relationship.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, blocks binding conforming to the new multi-apply UsdShadeCoordSysAPI schema. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to also block binding for multi-apply API compliant relationship for the prim, along with backward compatible deprecated behavior.

USDSHADE_API bool UsdShadeCoordSysAPI::BlockBinding

(

)

const

Block the indicated coordinate system binding on this prim by blocking targets on the underlying relationship.

static USDSHADE_API bool UsdShadeCoordSysAPI::CanApply ( const UsdPrim &  prim, const TfToken &  name, std::string *  whyNot = nullptr  )

static

Returns true if this multiple-apply API schema can be applied, with the given instance name, name, to the given prim. If this schema can not be a applied the prim, this returns false and, if provided, populates whyNot with the reason it can not be applied.

Note that if CanApply returns false, that does not necessarily imply that calling Apply will fail. Callers are expected to call CanApply before calling Apply if they want to ensure that it is valid to apply a schema.

See Also

UsdPrim::GetAppliedSchemas()

UsdPrim::HasAPI()

UsdPrim::CanApplyAPI()

UsdPrim::ApplyAPI()

UsdPrim::RemoveAPI()

static USDSHADE_API bool UsdShadeCoordSysAPI::CanContainPropertyName ( const TfToken &  name )

static

Test whether a given name contains the "coordSys:" prefix.

USDSHADE_API bool UsdShadeCoordSysAPI::ClearBinding	(	const TfToken &	name,
		bool	removeSpec
	)		const

Clear the indicated coordinate system binding on this prim from the current edit target.

Only remove the spec if removeSpec is true (leave the spec to preserve meta-data we may have intentionally authored on the relationship)

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, clears a binding conforming to the new multi-apply UsdShadeCoordSysAPI schema. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to also clear binding for multi-apply API compliant relationship for the prim, along with backward compatible deprecated behavior.

USDSHADE_API bool UsdShadeCoordSysAPI::ClearBinding

(

bool

removeSpec

)

const

Clear the coordinate system binding on the prim corresponding to the instanceName of this UsdShadeCoordSysAPI, from the current edit target.

Only remove the spec if removeSpec is true (leave the spec to preserve meta-data we may have intentionally authored on the relationship)

USDSHADE_API UsdRelationship UsdShadeCoordSysAPI::CreateBindingRel

(

)

const

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

USDSHADE_API std::vector<Binding> UsdShadeCoordSysAPI::FindBindingsWithInheritance

(

)

const

Find the list of coordinate system bindings that apply to this prim, including inherited bindings.

This computation examines this prim and ancestors for the strongest binding for each name. A binding expressed by a child prim supercedes bindings on ancestors.

Note that this API does not validate the prims at the target paths; they may be of incorrect type, or missing entirely.

Binding relationships with no resolved targets are skipped.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, returns bindings conforming to the new multi-apply UsdShadeCoordSysAPI schema. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to get multi-apply API compliant local bindings for the prim, if none fallback to backward compatible deprecated behavior.

static USDSHADE_API std::vector<Binding> UsdShadeCoordSysAPI::FindBindingsWithInheritanceForPrim ( const UsdPrim &  prim )

static

Find the list of coordinate system bindings that apply to this prim, including inherited bindings.

This computation examines this prim and ancestors for the strongest binding for each name. A binding expressed by a child prim supercedes bindings on ancestors. Only prims which have the UsdShadeCoordSysAPI applied are considered and queried for a binding.

Note that this API does not validate the prims at the target paths; they may be of incorrect type, or missing entirely.

Binding relationships with no resolved targets are skipped.

USDSHADE_API Binding UsdShadeCoordSysAPI::FindBindingWithInheritance

(

)

const

Find the coordinate system bindings that apply to this prim, including inherited bindings.

This computation examines this prim and ancestors for the strongest binding for the specific instanceName. A binding expressed by a child prim supercedes bindings on ancestors. Only ancestor prims which have the UsdShadeCoordSysAPI:instanceName applied are considered.

Note that this API does not validate the prims at the target paths; they may be of incorrect type, or missing entirely.

Binding relationships with no resolved targets are skipped.

static USDSHADE_API UsdShadeCoordSysAPI UsdShadeCoordSysAPI::Get ( const UsdStagePtr &  stage, const SdfPath &  path  )

static

Return a UsdShadeCoordSysAPI 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. path must be of the format <path>.coordSys:name .

This is shorthand for the following:

TfToken name = SdfPath::StripNamespace(path.GetToken());
UsdShadeCoordSysAPI(
    stage->GetPrimAtPath(path.GetPrimPath()), name);

static USDSHADE_API UsdShadeCoordSysAPI UsdShadeCoordSysAPI::Get ( const UsdPrim &  prim, const TfToken &  name  )

static

Return a UsdShadeCoordSysAPI with name name holding the prim prim. Shorthand for UsdShadeCoordSysAPI(prim, name);

static USDSHADE_API std::vector<UsdShadeCoordSysAPI> UsdShadeCoordSysAPI::GetAll ( const UsdPrim &  prim )

static

Return a vector of all named instances of UsdShadeCoordSysAPI on the given prim.

static USDSHADE_API TfToken UsdShadeCoordSysAPI::GetBindingBaseName ( const TfToken &  name )

static

Strips "coordSys:" from the relationship name and returns "<instanceName>:binding".

USDSHADE_API TfToken UsdShadeCoordSysAPI::GetBindingBaseName

(

)

const

Strips "coordSys:" from the relationship name and returns "<instanceName>:binding".

USDSHADE_API UsdRelationship UsdShadeCoordSysAPI::GetBindingRel

(

)

const

Prim binding expressing the appropriate coordinate systems.

static USDSHADE_API TfToken UsdShadeCoordSysAPI::GetCoordSysRelationshipName ( const std::string &  coordSysName )

static

Returns the fully namespaced coordinate system relationship name, given the coordinate system name.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI

USDSHADE_API Binding UsdShadeCoordSysAPI::GetLocalBinding

(

)

const

Get the coordinate system bindings local to this prim corresponding to this instance name. This does not process inherited bindings. It does not validate that a prim exists at the indicated path. If the binding relationship has multiple targets, only the first is used.

USDSHADE_API std::vector<Binding> UsdShadeCoordSysAPI::GetLocalBindings

(

)

const

Get the list of coordinate system bindings local to this prim. This does not process inherited bindings. It does not validate that a prim exists at the indicated path. If the binding relationship has multiple targets, only the first is used.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, returns bindings conforming to the new multi-apply UsdShadeCoordSysAPI schema. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to get multi-apply API compliant local bindings for the prim, if none fallback to backward compatible deprecated behavior.

static USDSHADE_API std::vector<Binding> UsdShadeCoordSysAPI::GetLocalBindingsForPrim ( const UsdPrim &  prim )

static

Get the list of coordinate system bindings local to this prim, across all multi-apply instanceNames. This does not process inherited bindings. It does not validate that a prim exists at the indicated path. If the binding relationship has multiple targets, only the first is used.

Note that this will always return empty vector of bindings if the prim being queried does not have UsdShadeCoordSysAPI applied.

TfToken UsdShadeCoordSysAPI::GetName ( ) const

inline

Returns the name of this multiple-apply schema instance.

Definition at line 134 of file coordSysAPI.h.

static USDSHADE_API const TfTokenVector& UsdShadeCoordSysAPI::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.

static USDSHADE_API TfTokenVector UsdShadeCoordSysAPI::GetSchemaAttributeNames ( bool  includeInherited, const TfToken &  instanceName  )

static

Return a vector of names of all pre-declared attributes for this schema class and all its ancestor classes for a given instance name. Does not include attributes that may be authored by custom/extended methods of the schemas involved. The names returned will have the proper namespace prefix.

USDSHADE_API bool UsdShadeCoordSysAPI::HasLocalBindings

(

)

const

Returns true if the prim has local coordinate system relationship exists.

Deprecated:

This method is deprecated as it operates on the old non-applied UsdShadeCoordSysAPI If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to True, if prim has appropriate API applied, that is conforming to the new behavior. If USD_SHADE_COORD_SYS_IS_MULTI_APPLY is set to Warn, try to see if multi-apply API compliant local bindings are present for the prim, if not fallback to backward compatible deprecated behavior.

static USDSHADE_API bool UsdShadeCoordSysAPI::HasLocalBindingsForPrim ( const UsdPrim &  prim )

static

Returns true if the prim has UsdShadeCoordSysAPI applied. Which implies it has the appropriate binding relationship(s).

static USDSHADE_API bool UsdShadeCoordSysAPI::IsCoordSysAPIPath ( const SdfPath &  path, TfToken *  name  )

static

Checks if the given path path is of an API schema of type CoordSysAPI. If so, it stores the instance name of the schema in name and returns true. Otherwise, it returns false.

static USDSHADE_API bool UsdShadeCoordSysAPI::IsSchemaPropertyBaseName ( const TfToken &  baseName )

static

Checks if the given name baseName is the base name of a property of CoordSysAPI.

Friends And Related Function Documentation

friend class UsdSchemaRegistry

friend

Definition at line 234 of file coordSysAPI.h.

Member Data Documentation

const UsdSchemaKind UsdShadeCoordSysAPI::schemaKind = UsdSchemaKind::MultipleApplyAPI

static

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

See Also

UsdSchemaKind

Definition at line 88 of file coordSysAPI.h.

---

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

• pxr/usd/usdShade/coordSysAPI.h