|
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 |
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.
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.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().
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().
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:
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 197 of file references.h.
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 AddReference | ( | const SdfReference & | ref, |
UsdListPosition | position = UsdListPositionBackOfPrependList |
||
) |
Adds a reference to the reference listOp at the current EditTarget, in the position specified by position
.
ref
and what return values and errors to expect, and ListOps and List Editing for details on list editing and composition of listOps. 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 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 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.
|
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 263 of file references.h.
|
inline |
Return the prim this object is bound to.
Definition at line 260 of file references.h.
|
inlineexplicit |
Definition at line 265 of file references.h.
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.
USD_API bool SetReferences | ( | const SdfReferenceVector & | items | ) |
Explicitly set the references, potentially blocking weaker opinions that add or remove items.
ref
and what return values and errors to expect, and ListOps and List Editing for details on list editing and composition of listOps.
|
friend |
Definition at line 198 of file references.h.