|
HDK
|
#include <relationship.h>
Inheritance diagram for UsdRelationship: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 |
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 128 of file relationship.h.
|
inline |
Construct an invalid relationship.
Definition at line 131 of file relationship.h.
| 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.
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.
|
friend |
Definition at line 246 of file relationship.h.
Definition at line 244 of file relationship.h.
Definition at line 245 of file relationship.h.
|
friend |
Definition at line 248 of file relationship.h.
1.8.6 
