This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
UsdRelationship Class Reference

A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other prims, attributes, or relationships. More...

#include <relationship.h>

+ Inheritance diagram for UsdRelationship:

Public Member Functions

 UsdRelationship ()
 Construct an invalid relationship.
 
Editing Relationships at Current EditTarget
USD_API bool AddTarget (const SdfPath &target, UsdListPosition position=UsdListPositionBackOfPrependList) const
 Adds target to the list of targets, in the position specified by position.
 
USD_API bool RemoveTarget (const SdfPath &target) const
 Removes target from the list of targets.
 
USD_API bool SetTargets (const SdfPathVector &targets) const
 Make the authoring layer's opinion of the targets list explicit, and set exactly to targets.
 
USD_API bool ClearTargets (bool removeSpec) const
 Remove all opinions about the target list from the current edit target.
 
USD_API bool GetTargets (SdfPathVector *targets) const
 Compose this relationship's targets and fill targets with the result.
 
USD_API bool GetForwardedTargets (SdfPathVector *targets) const
 Compose this relationship's ultimate targets, taking into account "relationship forwarding", and fill targets with the result.
 
USD_API bool HasAuthoredTargets () const
 Returns true if any target path opinions have been authored.
 
- Public Member Functions inherited from UsdProperty
 UsdProperty ()
 Construct an invalid property.
 
USD_API SdfPropertySpecHandleVector GetPropertyStack (UsdTimeCode time=UsdTimeCode::Default()) const
 Returns a strength-ordered list of property specs that provide opinions for this property.
 
USD_API std::vector< std::pair< SdfPropertySpecHandle, SdfLayerOffset > > GetPropertyStackWithLayerOffsets (UsdTimeCode time=UsdTimeCode::Default()) const
 Returns a strength-ordered list of property specs that provide opinions for this property paired with the cumulative layer offset from the stage's root layer to the layer containing the property spec.
 
USD_API TfToken GetBaseName () const
 Return this property's name with all namespace prefixes removed, i.e.
 
USD_API TfToken GetNamespace () const
 Return this property's complete namespace prefix.
 
USD_API std::vector< std::string > SplitName () const
 Return this property's name elements including namespaces and its base name as the final element.
 
USD_API std::string GetDisplayGroup () const
 Return this property's display group (metadata).
 
USD_API bool SetDisplayGroup (const std::string &displayGroup) const
 Sets this property's display group (metadata).
 
USD_API bool ClearDisplayGroup () const
 Clears this property's display group (metadata) in the current EditTarget (only).
 
USD_API bool HasAuthoredDisplayGroup () const
 Returns true if displayGroup was explicitly authored and GetMetadata() will return a meaningful value for displayGroup.
 
USD_API std::vector< std::string > GetNestedDisplayGroups () const
 Return this property's displayGroup as a sequence of groups to be nested, or an empty vector if displayGroup is empty or not authored.
 
USD_API bool SetNestedDisplayGroups (const std::vector< std::string > &nestedGroups) const
 Sets this property's display group (metadata) to the nested sequence.
 
USD_API bool IsCustom () const
 Return true if this is a custom property (i.e., not part of a prim schema).
 
USD_API bool SetCustom (bool isCustom) const
 Set the value for custom at the current EditTarget, return true on success, false if the value can not be written.
 
USD_API bool IsDefined () const
 Return true if this is a builtin property or if the strongest authored SdfPropertySpec for this property's path matches this property's dynamic type.
 
USD_API bool IsAuthored () const
 Return true if there are any authored opinions for this property in any layer that contributes to this stage, false otherwise.
 
USD_API bool IsAuthoredAt (const class UsdEditTarget &editTarget) const
 Return true if there is an SdfPropertySpec authored for this property at the given editTarget, otherwise return false.
 
USD_API UsdProperty FlattenTo (const UsdPrim &parent) const
 Flattens this property to a property spec with the same name beneath the given parent prim in the edit target of its owning stage.
 
USD_API UsdProperty FlattenTo (const UsdPrim &parent, const TfToken &propName) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec with the given propName beneath the given parent prim in the edit target of its owning stage.
 
USD_API UsdProperty FlattenTo (const UsdProperty &property) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Flattens this property to a property spec for the given property in the edit target of its owning prim's stage.
 
- Public Member Functions inherited from UsdObject
 UsdObject ()
 Default constructor produces an invalid object.
 
template<typename T >
bool GetMetadata (const TfToken &key, T *value) const
 Resolve the requested metadatum named key into value, returning true on success.
 
USD_API bool GetMetadata (const TfToken &key, VtValue *value) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.Type-erased access.
 
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
 Set metadatum key's value to value.
 
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
USD_API bool ClearMetadata (const TfToken &key) const
 Clears the authored key's value at the current EditTarget, returning false on error.
 
USD_API bool HasMetadata (const TfToken &key) const
 Returns true if the key has a meaningful value, that is, if GetMetadata() will provide a value, either because it was authored or because a prim's metadata fallback will be provided.
 
USD_API bool HasAuthoredMetadata (const TfToken &key) const
 Returns true if the key has an authored value, false if no value was authored or the only value available is a prim's metadata fallback.
 
template<class T >
bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const
 Resolve the requested dictionary sub-element keyPath of dictionary-valued metadatum named key into value, returning true on success.
 
USD_API bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
 Author value to the field identified by key and keyPath at the current EditTarget.
 
USD_API bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
USD_API bool ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
 Clear any authored value identified by key and keyPath at the current EditTarget.
 
USD_API bool HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 Return true if there exists any authored or fallback opinion for key and keyPath.
 
USD_API bool HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
 Return true if there exists any authored opinion (excluding fallbacks) for key and keyPath.
 
USD_API UsdMetadataValueMap GetAllMetadata () const
 Resolve and return all metadata (including both authored and fallback values) on this object, sorted lexicographically.
 
USD_API UsdMetadataValueMap GetAllAuthoredMetadata () const
 Resolve and return all user-authored metadata on this object, sorted lexicographically.
 
USD_API bool IsHidden () const
 Gets the value of the 'hidden' metadata field, false if not authored.
 
USD_API bool SetHidden (bool hidden) const
 Sets the value of the 'hidden' metadata field.
 
USD_API bool ClearHidden () const
 Clears the opinion for "Hidden" at the current EditTarget.
 
USD_API bool HasAuthoredHidden () const
 Returns true if hidden was explicitly authored and GetMetadata() will return a meaningful value for Hidden.
 
USD_API VtDictionary GetCustomData () const
 Return this object's composed customData dictionary.
 
USD_API VtValue GetCustomDataByKey (const TfToken &keyPath) const
 Return the element identified by keyPath in this object's composed customData dictionary.
 
USD_API void SetCustomData (const VtDictionary &customData) const
 Author this object's customData dictionary to customData at the current EditTarget.
 
USD_API void SetCustomDataByKey (const TfToken &keyPath, const VtValue &value) const
 Author the element identified by keyPath in this object's customData dictionary at the current EditTarget.
 
USD_API void ClearCustomData () const
 Clear the authored opinion for this object's customData dictionary at the current EditTarget.
 
USD_API void ClearCustomDataByKey (const TfToken &keyPath) const
 Clear the authored opinion identified by keyPath in this object's customData dictionary at the current EditTarget.
 
USD_API bool HasCustomData () const
 Return true if there are any authored or fallback opinions for this object's customData dictionary, false otherwise.
 
USD_API bool HasCustomDataKey (const TfToken &keyPath) const
 Return true if there are any authored or fallback opinions for the element identified by keyPath in this object's customData dictionary, false otherwise.
 
USD_API bool HasAuthoredCustomData () const
 Return true if there are any authored opinions (excluding fallback) for this object's customData dictionary, false otherwise.
 
USD_API bool HasAuthoredCustomDataKey (const TfToken &keyPath) const
 Return true if there are any authored opinions (excluding fallback) for the element identified by keyPath in this object's customData dictionary, false otherwise.
 
USD_API VtDictionary GetAssetInfo () const
 Return this object's composed assetInfo dictionary.
 
USD_API VtValue GetAssetInfoByKey (const TfToken &keyPath) const
 Return the element identified by keyPath in this object's composed assetInfo dictionary.
 
USD_API void SetAssetInfo (const VtDictionary &customData) const
 Author this object's assetInfo dictionary to assetInfo at the current EditTarget.
 
USD_API void SetAssetInfoByKey (const TfToken &keyPath, const VtValue &value) const
 Author the element identified by keyPath in this object's assetInfo dictionary at the current EditTarget.
 
USD_API void ClearAssetInfo () const
 Clear the authored opinion for this object's assetInfo dictionary at the current EditTarget.
 
USD_API void ClearAssetInfoByKey (const TfToken &keyPath) const
 Clear the authored opinion identified by keyPath in this object's assetInfo dictionary at the current EditTarget.
 
USD_API bool HasAssetInfo () const
 Return true if there are any authored or fallback opinions for this object's assetInfo dictionary, false otherwise.
 
USD_API bool HasAssetInfoKey (const TfToken &keyPath) const
 Return true if there are any authored or fallback opinions for the element identified by keyPath in this object's assetInfo dictionary, false otherwise.
 
USD_API bool HasAuthoredAssetInfo () const
 Return true if there are any authored opinions (excluding fallback) for this object's assetInfo dictionary, false otherwise.
 
USD_API bool HasAuthoredAssetInfoKey (const TfToken &keyPath) const
 Return true if there are any authored opinions (excluding fallback) for the element identified by keyPath in this object's assetInfo dictionary, false otherwise.
 
USD_API std::string GetDocumentation () const
 Return this object's documentation (metadata).
 
USD_API bool SetDocumentation (const std::string &doc) const
 Sets this object's documentation (metadata). Returns true on success.
 
USD_API bool ClearDocumentation () const
 Clears this object's documentation (metadata) in the current EditTarget (only).
 
USD_API bool HasAuthoredDocumentation () const
 Returns true if documentation was explicitly authored and GetMetadata() will return a meaningful value for documentation.
 
USD_API std::string GetDisplayName () const
 Return this object's display name (metadata).
 
USD_API bool SetDisplayName (const std::string &name) const
 Sets this object's display name (metadata).
 
USD_API bool ClearDisplayName () const
 Clears this object's display name (metadata) in the current EditTarget (only).
 
USD_API bool HasAuthoredDisplayName () const
 Returns true if displayName was explicitly authored and GetMetadata() will return a meaningful value for displayName.
 
bool IsValid () const
 Return true if this is a valid object, false otherwise.
 
 operator bool () const
 Returns true if this object is valid, false otherwise.
 
USD_API UsdStageWeakPtr GetStage () const
 Return the stage that owns the object, and to whose state and lifetime this object's validity is tied.
 
SdfPath GetPath () const
 Return the complete scene path to this object on its UsdStage, which may (UsdPrim) or may not (all other subclasses) return a cached result.
 
const SdfPathGetPrimPath () const
 Return this object's path if this object is a prim, otherwise this object's nearest owning prim's path.
 
UsdPrim GetPrim () const
 Return this object if it is a prim, otherwise return this object's nearest owning prim.
 
const TfTokenGetName () const
 Return the full name of this object, i.e.
 
template<class T >
As () const
 Convert this UsdObject to another object type T if possible.
 
template<class T >
bool Is () const
 Return true if this object is convertible to T.
 
USD_API std::string GetDescription () const
 Return a string that provides a brief summary description of the object.
 

Friends

class UsdObject
 
class UsdPrim
 
template<class A0 , class A1 >
struct UsdPrim_TargetFinder
 

Additional Inherited Members

- Static Public Member Functions inherited from UsdObject
static char GetNamespaceDelimiter ()
 
- Protected Member Functions inherited from UsdProperty
template<class Derived >
 UsdProperty (_Null< Derived >)
 
bool _GetTargets (SdfSpecType specType, SdfPathVector *out, bool *foundErrors=nullptr) const
 
- Protected Member Functions inherited from UsdObject
template<class Derived >
 UsdObject (_Null< Derived >)
 
 UsdObject (const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath)
 
 UsdObject (UsdObjType objType, const Usd_PrimDataHandle &prim, const SdfPath &proxyPrimPath, const TfToken &propName)
 
UsdStage_GetStage () const
 
USD_API SdfSpecType _GetDefiningSpecType () const
 
const Usd_PrimDataHandle & _Prim () const
 
const TfToken_PropName () const
 
const SdfPath_ProxyPrimPath () const
 

Detailed Description

A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other prims, attributes, or relationships.

Relationship Characteristics

A UsdRelationship is a pointer to other objects, which are named by their scenegraph paths. When authoring relationships, the target parameters should be scenegraph paths in the composed namespace of the UsdStage into which you are authoring. If your edits are targeted to a different layer, across various composition arcs (because you specified a non-default UsdEditTarget), the target's path will be automatically translated into the proper namespace.

A single UsdRelationship can target multiple other objects, which can be of UsdPrim, UsdAttribute, or UsdRelationship type. UsdRelationship participates in "list editing", which means that stronger layers in a composed scene can add, remove, or reorder targets authored on the relationship in weaker layers without stomping the weaker opinions, although stomping behavior is still possible, via SetTargets().

An authored relationship creates a dependency of the targeting prim on the targeted prim(s). We consider these dependencies to be "load dependencies", which means that when we load the targeting prim's "load group", we will also load the targeted prims' load groups, to ensure that all the data required to render the model containing the targeting prim is composed and available.

Like UsdAttribute, UsdRelationship objects are meant to be ephemeral, live on the stack, and be cheap to refetch from their owning UsdPrim.

Unlike UsdAttribute s, which can either be uniform over all time or vary in value over time, UsdRelationship is always uniform.

Relationship Restrictions

When authoring relationship targets in a stage's local LayerStack, all target paths are legal (Note we may restrict this prior to launch to only allowing targeting of already-extant scenegraph objects). However, a relationship target that is legal in a local LayerStack may become unreachable when the stage's root layer is referenced into an aggregate, and will cause an error when attempting to load/compose the aggregate.

This can happen because references encapsulate just the tree whose root is targeted in the reference - no other scene description in the referenced layer will be composed into the aggregate. So if some descendant prim of the referenced root targets a relationship to another tree in the same layer, that relationship would dangle, and the client will error in GetTargets() or GetForwardedTargets().

Authoring targets to objects within prototypes is not allowed, since prototype prims do not have a stable identity across runs. Consumers must author targets to the object within an instance instead.

Relationships authored in a descendent prim of a referenced prim may not target the referenced prim itself or any of its immediate child properties if the referencing prim is instanceable. Allowing this would break the ability for this relationship to be instanced and shared by multiple instances – it would force consumers of relationships within prototypes to resolve targets in the context of each of that prototype's instances.

Relationship Forwarding

Because a relationship can target another relationship, we can and do provide the ability to resolve chained or forwarded relationships. This can be useful in several situations, including:

  • Combining relationships with VariantSets to create demultiplexers. A prim can host a relationship that serves as a "binding post" for other prims to target. The prim also hosts a "bindingVariant" UsdVariantSet whose variants each modulate the target of the binding-post relationship. We can now change the forwarded target of all prims targeting the binding-post by simply switching the bindingVariant VariantSet. We will work through this example in the USD reference manual.
  • Defining a relationship as part of a model's interface (so that it can be targeted in model hierarchy with no models loaded), which, inside the model's payload, forwards to prims useful to a client, the set of which may vary depending on the model's configured VariantSets.

Definition at line 111 of file relationship.h.

Constructor & Destructor Documentation

◆ UsdRelationship()

UsdRelationship ( )
inline

Construct an invalid relationship.

Definition at line 114 of file relationship.h.

Member Function Documentation

◆ AddTarget()

USD_API bool AddTarget ( const SdfPath target,
UsdListPosition  position = UsdListPositionBackOfPrependList 
) const

Adds target to the list of targets, in the position specified by position.

Passing paths to prototype prims or any other objects in prototypes will cause an error to be issued. It is not valid to author targets to these objects.

What data this actually authors depends on what data is currently authored in the authoring layer, with respect to list-editing semantics, which we will document soon

◆ ClearTargets()

USD_API bool ClearTargets ( bool  removeSpec) const

Remove all opinions about the target list 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)

◆ GetForwardedTargets()

USD_API bool GetForwardedTargets ( SdfPathVector *  targets) const

Compose this relationship's ultimate targets, taking into account "relationship forwarding", and fill targets with the result.

All preexisting elements in targets are lost. This method never inserts relationship paths in targets.

Returns true if any of the visited relationships that are not "purely forwarding" has an authored opinion for its target paths and no composition errors were encountered while computing any targets. Purely forwarding, in this context, means the relationship has at least one target but all of its targets are paths to other relationships. Note that authored opinions may include opinions that clear the targets and a return value of true does not necessarily indicate that targets will not be empty.

Returns false otherwise. When composition errors occur, this function continues to collect successfully composed targets, but returns false to indicate to the caller that errors occurred.

When a forwarded target cannot be determined, e.g. due to a composition error, no value is returned for that target; the alternative would be to return the relationship path at which the forwarded targets could not be composed, however this would require all callers of GetForwardedTargets() to account for unexpected relationship paths being returned with the expected target results. For example, a particular caller may expect only prim paths in the target vector, but when composition errors occur, relationships would be included, potentially triggering additional down stream errors.

See Relationship Forwarding for details on the semantics.

The result is not cached, so will be recomputed on every query.

◆ GetTargets()

USD_API bool GetTargets ( SdfPathVector *  targets) const

Compose this relationship's targets and fill targets with the result.

All preexisting elements in targets are lost.

Returns true if any target path opinions have been authored and no composition errors were encountered, returns false otherwise. Note that authored opinions may include opinions that clear the targets and a return value of true does not necessarily indicate that targets will contain any target paths.

See Relationship Targets and Attribute Connections for details on behavior when targets point to objects beneath instance prims.

The result is not cached, so will be recomputed on every query.

◆ HasAuthoredTargets()

USD_API bool HasAuthoredTargets ( ) const

Returns true if any target path opinions have been authored.

Note that this may include opinions that clear targets and may not indicate that target paths will exist for this relationship.

◆ RemoveTarget()

USD_API bool RemoveTarget ( const SdfPath target) const

Removes target from the list of targets.

Passing paths to prototype prims or any other objects in prototypes will cause an error to be issued. It is not valid to author targets to these objects.

◆ SetTargets()

USD_API bool SetTargets ( const SdfPathVector &  targets) const

Make the authoring layer's opinion of the targets list explicit, and set exactly to targets.

Passing paths to prototype prims or any other objects in prototypes will cause an error to be issued. It is not valid to author targets to these objects.

If any target in targets is invalid, no targets will be authored and this function will return false.

Friends And Related Function Documentation

◆ UsdObject

friend class UsdObject
friend

Definition at line 227 of file relationship.h.

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 228 of file relationship.h.

◆ UsdPrim_TargetFinder

friend struct UsdPrim_TargetFinder
friend

Definition at line 231 of file relationship.h.


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