All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
UsdRelationship Class Reference

#include <relationship.h>

+ Inheritance diagram for UsdRelationship:

Public Member Functions

 UsdRelationship ()
 Construct an invalid relationship. More...
Editing Relationships at Current EditTarget
USD_API bool AddTarget (const SdfPath &target, UsdListPosition position=UsdListPositionBackOfPrependList) const
USD_API bool RemoveTarget (const SdfPath &target) const
USD_API bool BlockTargets () const
USD_API bool SetTargets (const SdfPathVector &targets) const
USD_API bool ClearTargets (bool removeSpec) const
USD_API bool GetTargets (SdfPathVector *targets) const
USD_API bool GetForwardedTargets (SdfPathVector *targets) const
USD_API bool HasAuthoredTargets () const
- Public Member Functions inherited from UsdProperty
 UsdProperty ()
 Construct an invalid property. More...
USD_API SdfPropertySpecHandleVector GetPropertyStack (UsdTimeCode time=UsdTimeCode::Default()) const
USD_API TfToken GetBaseName () const
USD_API TfToken GetNamespace () const
USD_API std::vector< std::stringSplitName () const
USD_API std::string GetDisplayGroup () const
USD_API bool SetDisplayGroup (const std::string &displayGroup) const
USD_API bool ClearDisplayGroup () const
USD_API bool HasAuthoredDisplayGroup () const
USD_API std::vector< std::stringGetNestedDisplayGroups () const
USD_API bool SetNestedDisplayGroups (const std::vector< std::string > &nestedGroups) const
USD_API std::string GetDisplayName () const
USD_API bool SetDisplayName (const std::string &name) const
USD_API bool ClearDisplayName () const
USD_API bool HasAuthoredDisplayName () const
USD_API bool IsCustom () const
USD_API bool SetCustom (bool isCustom) const
USD_API bool IsDefined () const
USD_API bool IsAuthored () const
USD_API bool IsAuthoredAt (const class UsdEditTarget &editTarget) const
USD_API UsdProperty FlattenTo (const UsdPrim &parent) const
USD_API UsdProperty FlattenTo (const UsdPrim &parent, const TfToken &propName) const
USD_API UsdProperty FlattenTo (const UsdProperty &property) const
- Public Member Functions inherited from UsdObject
 UsdObject ()
 Default constructor produces an invalid object. More...
template<typename T >
bool GetMetadata (const TfToken &key, T *value) const
USD_API bool GetMetadata (const TfToken &key, VtValue *value) const
template<typename T >
bool SetMetadata (const TfToken &key, const T &value) const
USD_API bool SetMetadata (const TfToken &key, const VtValue &value) const
USD_API bool ClearMetadata (const TfToken &key) const
USD_API bool HasMetadata (const TfToken &key) const
USD_API bool HasAuthoredMetadata (const TfToken &key) const
template<class T >
bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, T *value) const
USD_API bool GetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, VtValue *value) const
template<typename T >
bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const T &value) const
USD_API bool SetMetadataByDictKey (const TfToken &key, const TfToken &keyPath, const VtValue &value) const
USD_API bool ClearMetadataByDictKey (const TfToken &key, const TfToken &keyPath) const
USD_API bool HasMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
USD_API bool HasAuthoredMetadataDictKey (const TfToken &key, const TfToken &keyPath) const
USD_API UsdMetadataValueMap GetAllMetadata () const
USD_API UsdMetadataValueMap GetAllAuthoredMetadata () const
USD_API bool IsHidden () const
USD_API bool SetHidden (bool hidden) const
USD_API bool ClearHidden () const
 Clears the opinion for "Hidden" at the current EditTarget. More...
USD_API bool HasAuthoredHidden () const
USD_API VtDictionary GetCustomData () const
USD_API VtValue GetCustomDataByKey (const TfToken &keyPath) const
USD_API void SetCustomData (const VtDictionary &customData) const
USD_API void SetCustomDataByKey (const TfToken &keyPath, const VtValue &value) const
USD_API void ClearCustomData () const
USD_API void ClearCustomDataByKey (const TfToken &keyPath) const
USD_API bool HasCustomData () const
USD_API bool HasCustomDataKey (const TfToken &keyPath) const
USD_API bool HasAuthoredCustomData () const
USD_API bool HasAuthoredCustomDataKey (const TfToken &keyPath) const
USD_API VtDictionary GetAssetInfo () const
USD_API VtValue GetAssetInfoByKey (const TfToken &keyPath) const
USD_API void SetAssetInfo (const VtDictionary &customData) const
USD_API void SetAssetInfoByKey (const TfToken &keyPath, const VtValue &value) const
USD_API void ClearAssetInfo () const
USD_API void ClearAssetInfoByKey (const TfToken &keyPath) const
USD_API bool HasAssetInfo () const
USD_API bool HasAssetInfoKey (const TfToken &keyPath) const
USD_API bool HasAuthoredAssetInfo () const
USD_API bool HasAuthoredAssetInfoKey (const TfToken &keyPath) const
USD_API std::string GetDocumentation () const
USD_API bool SetDocumentation (const std::string &doc) const
 Sets this object's documentation (metadata). Returns true on success. More...
USD_API bool ClearDocumentation () const
USD_API bool HasAuthoredDocumentation () const
bool IsValid () const
 Return true if this is a valid object, false otherwise. More...
 operator bool () const
 Returns true if this object is valid, false otherwise. More...
USD_API UsdStageWeakPtr GetStage () const
SdfPath GetPath () const
const SdfPathGetPrimPath () const
UsdPrim GetPrim () const
const TfTokenGetName () const
template<class T >
T As () const
template<class T >
bool Is () const
USD_API std::string GetDescription () const


class UsdObject
class UsdPrim
class Usd_PrimData
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) 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 targetted 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 targetting prim on the targetted 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 targetted 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 targetted 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 masters is not allowed, since master 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 masters to resolve targets in the context of each of that master'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 targetting 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 targetted 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 128 of file relationship.h.

Constructor & Destructor Documentation

UsdRelationship::UsdRelationship ( )

Construct an invalid relationship.

Definition at line 131 of file relationship.h.

Member Function Documentation

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

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

Passing paths to master prims or any other objects in masters 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

USD_API bool UsdRelationship::BlockTargets ( ) const

Clears all target edits from the current EditTarget, and makes the opinion explicit, which means we are effectively resetting the composed value of the targets list to empty.

USD_API bool UsdRelationship::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)

USD_API bool UsdRelationship::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.

When composition errors occur, continue to collect successfully composed targets, but return 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.

USD_API bool UsdRelationship::GetTargets ( SdfPathVector targets) const

Compose this relationship's targets and fill targets with the result. All preexisting elements in targets are lost.

See Usd_ScenegraphInstancing_TargetsAndConnections for details on behavior when targets point to objects beneath instance prims.

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

USD_API bool UsdRelationship::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.

USD_API bool UsdRelationship::RemoveTarget ( const SdfPath target) const

Removes target from the list of targets.

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

USD_API bool UsdRelationship::SetTargets ( const SdfPathVector targets) const

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

Passing paths to master prims or any other objects in masters 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

friend class Usd_PrimData

Definition at line 237 of file relationship.h.

friend class UsdObject

Definition at line 235 of file relationship.h.

friend class UsdPrim

Definition at line 236 of file relationship.h.

template<class A0 , class A1 >
friend struct UsdPrim_TargetFinder

Definition at line 239 of file relationship.h.

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