Loading...
Searching...
No Matches
Public Member Functions | Friends | List of all members
UsdReferences Class Reference

UsdReferences provides an interface to authoring and introspecting references in Usd. More...

#include <references.h>

Public Member Functions

USD_API bool AddReference (const SdfReference &ref, UsdListPosition position=UsdListPositionBackOfPrependList)
 Adds a reference to the reference listOp at the current EditTarget, in the position specified by position.
 
USD_API bool AddReference (const std::string &identifier, const SdfPath &primPath, const SdfLayerOffset &layerOffset=SdfLayerOffset(), UsdListPosition position=UsdListPositionBackOfPrependList)
 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 AddReference (const std::string &identifier, const SdfLayerOffset &layerOffset=SdfLayerOffset(), UsdListPosition position=UsdListPositionBackOfPrependList)
 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 AddInternalReference (const SdfPath &primPath, const SdfLayerOffset &layerOffset=SdfLayerOffset(), UsdListPosition position=UsdListPositionBackOfPrependList)
 Add an internal reference to the specified prim.
 
USD_API bool RemoveReference (const SdfReference &ref)
 Removes the specified reference from the references listOp at the current EditTarget.
 
USD_API bool ClearReferences ()
 Removes the authored reference listOp edits at the current EditTarget.
 
USD_API bool SetReferences (const SdfReferenceVector &items)
 Explicitly set the references, potentially blocking weaker opinions that add or remove items.
 
const UsdPrim & GetPrim () const
 Return the prim this object is bound to.
 
UsdPrim GetPrim ()
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
 
 operator bool ()
 

Friends

class UsdPrim
 

Detailed Description

UsdReferences provides an interface to authoring and introspecting references in Usd.

References are the primary operator for "encapsulated aggregation" of scene description. aggregation means that references let us build up rich scenes by composing scene description recorded in a (most often) different layer. A scene can reference the same layer many times at different locations in a scene's namespace. Referenced scene description can be overridden in the referencing (or stronger) layers, allowing each instance of the reference to be directly customized/overridden. Encapsulated means that regardless of how much scene description is in the referenced layer, only the scene description under and composed from (via other composition arcs in the referenced layer) the targeted prim will be composed into the aggregate scene. Multiple references to the same layer will result in the layer being opened and retained in memory only once, although each referencing prim will compose unique prim indices for the tree rooted at the referenced prim.

Important Qualities and Effective Use of References

  • Any prim can host zero, one or multiple references
  • References are list editable; that is, they compose differently than ordinary properties and metadata. In any given LayerStack, each authored reference operation at the same SdfPath location in each layer (i.e. on the same prim) will compose into an aggregate result by adding to, removing from, or replacing "weaker" references.
  • The identifier component of a reference in the provided API can be a resolvable asset-path to some external layer, empty, in which case the reference targets the root layer of the LayerStack containing the referencing layer, or the identifier of an existing anonymous, in-memory-only SdfLayer. Care should be exercised in the latter case: calling Export() on an anonymous layer to serialize it to a file will not attempt to replace any references to anonymous layers with references to file-backed layers.
  • Opinions brought in by reference on an ancestor prim are weaker than opinions brought in by references on a descendant prim.

Expressing references without prim paths

References may omit the target prim path if the referenced layer has the 'defaultPrim' metadata set. In this case, the reference targets the 'defaultPrim' in the referenced layer. A layer's defaultPrim can be authored and accessed on a UsdStage whose root layer is the layer in question: see UsdStage::GetDefaultPrim() and UsdStage::SetDefaultPrim(). One can also author defaultPrim directly on an SdfLayer - see SdfLayer::GetDefaultPrim(), SdfLayer::SetDefaultPrim().

Expressing "internal" references to the containing LayerStack

References may omit the identifier specifying the referenced layer. This creates an "internal" reference. During composition, the referenced layer will be resolved to the root layer of the LayerStack containing the layer where the reference was authored. See AddInternalReference().

Referencing sub-root prims

References may target any prim in a layer. In the simplest and most common case, a root prim in a layer will be referenced. However, referencing sub-root prims can be useful in a variety of other cases; for example, a user might organize prims into a meaningful hierarchy in a layer for display purposes, then use sub-root references to reference a selection from that hierarchy into a scene.

Sub-root references have subtle behaviors with respect to opinions and composition arcs authored on ancestors of the referenced prim. Users should carefully consider this when deciding whether to use sub-root references. These issues can be avoided by not authoring any properties or metadata on ancestors of prims that are meant to be referenced.

Consider the following example:

* shot.usda | * asset.usda
|
#usda 1.0 | #usda 1.0
|
over "Class" | class "Class"
{ | {
over "B" | }
{ |
over "Model" | def "A" (
{ | inherits = </Class>
int a = 3 | )
} | {
} | token purpose = "render"
} |
| def "B" (
over "A" | variantSets = "type"
{ | variants = {
over "B" ( | string type = "a"
# variant selection won't be used | }
variants = { | )
string type = "b" | {
} | variantSet "type" = {
) | "a" {
{ | def "Model"
} | {
} | int a = 1
| }
def "ReferencedModel" ( | }
references = @./asset.usda@</A/B/Model> | "b" {
) | def "Model"
{ | {
} | int a = 2
| }
| }
| }
| }
| }
  • Property and metadata opinions on the ancestors of the referenced prim are not present in the composed stage and will never contribute to any computations. In this example, the opinion for the attribute /A.purpose in asset.usda will never be visible in the UsdStage for shot.usda.
  • Property and metadata opinions due to ancestral composition arcs are present in the composed stage. In this example, the attribute /Class/B/Model.a in shot.usda will be present in the UsdStage for shot.usda, even though the inherit arc is authored on an ancestor of the referenced prim.
  • A consequence of these rules is that users might not be able to override ancestral variant selections that affect the referenced prim. In this example, the Model prim being referenced comes from the variant selection {type=a} on prim /A/B in asset.usda. The {type=b} variant cannot be selected in shot.usda, even if prims with the same hierarchy happen to exist there. There are various workarounds for this; in this example, the {type=b} variant selection could be authored on /Class/B/Model in shot.usda instead because of the inherit arc that was established on prim /A.

Reasons why adding a reference may fail, why adding a reference may succeed but still generate errors, and what it all means

AddReference() and SetReferences() can each fail for a number of reasons. If one of the specified prim targets for one of the references is not a prim, we will generate an error, fail to author any scene description, and return false. If anything goes wrong in attempting to write the reference, we also return false, and the reference will also remain unauthored. Otherwise, if the reference was successfully authored, we will return true. A successful reference authoring operation may still generate composition errors! Just because the reference you specified was syntactically correct and therefore successfully authored, does not imply it was meaningful. If you wish to ensure that the reference you are about to author will be meaningfully consumable by your stage, you are strongly encouraged to ensure it will resolve to an actual file by using UsdStage::ResolveIdentifierToEditTarget() before authoring the reference.

When adding an internal reference, the given prim path is expected to be in the namespace of the owning prim's stage. Sub-root prim paths will be translated from this namespace to the namespace of the current edit target, if necessary. If a path cannot be translated, a coding error will be issued and no changes will be made. Non-sub-root paths will not be translated.

Immediately upon successful authoring of the reference (before returning from AddReference(), RemoveReference(), ClearReferences(), or SetReferences()), the UsdStage on which the reference was authored will recompose the subtree rooted at the prim hosting the reference. If the provided identifier does not resolve to a layer that is already opened or that can be opened in the usd format, or if the provided primPath is not an actual prim in that layer, the stage's recomposition will fail, and pass on composition errors to the client.

Definition at line 214 of file references.h.

Member Function Documentation

◆ AddInternalReference()

USD_API bool AddInternalReference ( const SdfPath &  primPath,
const SdfLayerOffset &  layerOffset = SdfLayerOffset(),
UsdListPosition  position = UsdListPositionBackOfPrependList 
)

Add an internal reference to the specified prim.

See also
Internal References

◆ AddReference() [1/3]

USD_API bool AddReference ( const SdfReference &  ref,
UsdListPosition  position = UsdListPositionBackOfPrependList 
)

Adds a reference to the reference listOp at the current EditTarget, in the position specified by position.

See also
Why adding references may fail for explanation of expectations on ref and what return values and errors to expect, and ListOps and List Editing for details on list editing and composition of listOps.

◆ AddReference() [2/3]

USD_API bool AddReference ( const std::string &  identifier,
const SdfLayerOffset &  layerOffset = SdfLayerOffset(),
UsdListPosition  position = UsdListPositionBackOfPrependList 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

See also
References Without Prim Paths

◆ AddReference() [3/3]

USD_API bool AddReference ( const std::string &  identifier,
const SdfPath &  primPath,
const SdfLayerOffset &  layerOffset = SdfLayerOffset(),
UsdListPosition  position = UsdListPositionBackOfPrependList 
)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

◆ ClearReferences()

USD_API bool ClearReferences ( )

Removes the authored reference listOp edits at the current EditTarget.

The same caveats for Remove() apply to Clear(). In fact, Clear() may actually increase the number of composed references, if the listOp being cleared contained the "remove" operator.

See also
ListOps and List Editing

◆ GetPrim() [1/2]

UsdPrim GetPrim ( )
inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 280 of file references.h.

◆ GetPrim() [2/2]

const UsdPrim & GetPrim ( ) const
inline

Return the prim this object is bound to.

Definition at line 277 of file references.h.

◆ operator bool()

operator bool ( )
inlineexplicit

Definition at line 282 of file references.h.

◆ RemoveReference()

USD_API bool RemoveReference ( const SdfReference &  ref)

Removes the specified reference from the references listOp at the current EditTarget.

This does not necessarily eliminate the reference completely, as it may be added or set in another layer in the same LayerStack as the current EditTarget.

See also
ListOps and List Editing

◆ SetReferences()

USD_API bool SetReferences ( const SdfReferenceVector &  items)

Explicitly set the references, potentially blocking weaker opinions that add or remove items.

See also
Why adding references may fail for explanation of expectations on ref and what return values and errors to expect, and ListOps and List Editing for details on list editing and composition of listOps.

Friends And Related Function Documentation

◆ UsdPrim

friend class UsdPrim
friend

Definition at line 215 of file references.h.

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