HDK
 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 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 std::vector< std::pair
< SdfPropertySpecHandle,
SdfLayerOffset > > 
GetPropertyStackWithLayerOffsets (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 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
 
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
 
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
 

Friends

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, 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 128 of file relationship.h.

Constructor & Destructor Documentation

UsdRelationship::UsdRelationship ( )
inline

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 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

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.

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.

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.

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 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 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.

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 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

friend class Usd_PrimData
friend

Definition at line 246 of file relationship.h.

friend class UsdObject
friend

Definition at line 244 of file relationship.h.

friend class UsdPrim
friend

Definition at line 245 of file relationship.h.

template<class A0 , class A1 >
friend struct UsdPrim_TargetFinder
friend

Definition at line 248 of file relationship.h.


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