|
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other prims, attributes, or relationships. More...
#include <relationship.h>
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 SdfPath & | GetPrimPath () 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 TfToken & | GetName () const |
Return the full name of this object, i.e. | |
template<class T > | |
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 |
A UsdRelationship creates dependencies between scenegraph objects by allowing a prim to target other prims, attributes, or relationships.
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.
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.
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:
Definition at line 111 of file relationship.h.
|
inline |
Construct an invalid relationship.
Definition at line 114 of file relationship.h.
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
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)
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.
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.
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.
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.
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.
|
friend |
Definition at line 227 of file relationship.h.
|
friend |
Definition at line 228 of file relationship.h.
|
friend |
Definition at line 231 of file relationship.h.