UsdEditTarget Class Reference

Defines a mapping from scene graph paths to Sdf spec paths in a SdfLayer where edits should be directed, or up to where to perform partial composition. More...

Public Member Functions

USD_API UsdEditTarget ()
 Construct a null EditTarget. More...
 
USD_API UsdEditTarget (const SdfLayerHandle &layer, SdfLayerOffset offset=SdfLayerOffset())
 Constructor. More...
 
USD_API UsdEditTarget (const SdfLayerRefPtr &layer, SdfLayerOffset offset=SdfLayerOffset())
 Convenience implicit conversion from SdfLayerRefPtr. More...
 
USD_API UsdEditTarget (const SdfLayerHandle &layer, const PcpNodeRef &node)
 Construct an EditTarget with layer and node. More...
 
USD_API UsdEditTarget (const SdfLayerRefPtr &layer, const PcpNodeRef &node)
 Convenience constructor taking SdfLayerRefPtr. More...
 
USD_API bool operator== (const UsdEditTarget &other) const
 Equality comparison. More...
 
bool operator!= (const UsdEditTarget &other) const
 Inequality comparison. More...
 
bool IsNull () const
 Return true if this EditTarget is null. More...
 
bool IsValid () const
 Return true if this EditTarget is valid, false otherwise. More...
 
const SdfLayerHandle & GetLayer () const
 Return the layer this EditTarget contains. More...
 
USD_API SdfPath MapToSpecPath (const SdfPath &scenePath) const
 Map the provided scenePath into a SdfSpec path for the EditTarget's layer, according to the EditTarget's mapping. More...
 
USD_API SdfPrimSpecHandle GetPrimSpecForScenePath (const SdfPath &scenePath) const
 Convenience function for getting the PrimSpec in the edit target's layer for scenePath. More...
 
USD_API SdfPropertySpecHandle GetPropertySpecForScenePath (const SdfPath &scenePath) const
 
USD_API SdfSpecHandle GetSpecForScenePath (const SdfPath &scenePath) const
 
const PcpMapFunctionGetMapFunction () const
 Returns the PcpMapFunction representing the map from source specs (including any variant selections) to the stage. More...
 
USD_API UsdEditTarget ComposeOver (const UsdEditTarget &weaker) const
 Return a new EditTarget composed over weaker. More...
 

Static Public Member Functions

static USD_API UsdEditTarget ForLocalDirectVariant (const SdfLayerHandle &layer, const SdfPath &varSelPath)
 Convenience constructor for editing a direct variant in a local LayerStack. More...
 

Detailed Description

Defines a mapping from scene graph paths to Sdf spec paths in a SdfLayer where edits should be directed, or up to where to perform partial composition.

A UsdEditTarget can represent an arbitrary point in a composition graph for the purposes of placing edits and resolving values. This enables editing and resolving across references, classes, variants, and payloads.

In the simplest case, an EditTarget represents a single layer in a stage's local LayerStack. In this case, the mapping that transforms scene graph paths to spec paths in the layer is the identity function. That is, the UsdAttribute path '/World/Foo.avar' would map to the SdfPropertySpec path '/World/Foo.avar'.

For a more complex example, suppose '/World/Foo' in 'Shot.usda' is a reference to '/Model' in 'Model.usda'. One can construct a UsdEditTarget that maps scene graph paths from the 'Shot.usda' stage across the reference to the appropriate paths in the 'Model.usda' layer. For example, the UsdAttribute '/World/Foo.avar' would map to the SdfPropertySpec '/Model.avar'. Paths in the stage composed at 'Shot.usda' that weren't prefixed by '/World/Foo' would not have a valid mapping to 'Model.usda'.

EditTargets may also work for any other kind of arc or series of arcs. This allows for editing across variants, classes, and payloads, or in a variant on the far side of a reference, for example.

In addition to mapping scene paths to spec paths for editing, EditTargets may also be used to identify points in the composition graph for partial composition. Though it doesn't currently exist, a UsdCompose API that takes UsdEditTarget arguments may someday be provided.

For convenience and deployment ease, SdfLayerHandles will implicitly convert to UsdEditTargets. A UsdEditTarget constructed in this way means direct opinions in a layer in a stage's local LayerStack.

Definition at line 78 of file editTarget.h.

Constructor & Destructor Documentation

◆ UsdEditTarget() [1/5]

USD_API UsdEditTarget ( )

Construct a null EditTarget.

A null EditTarget will return paths unchanged when asked to map paths.

◆ UsdEditTarget() [2/5]

USD_API UsdEditTarget ( const SdfLayerHandle &  layer,
SdfLayerOffset  offset = SdfLayerOffset() 
)

Constructor.

Allow implicit conversion from SdfLayerHandle. EditTargets constructed in this way specify layers in the scene's local LayerStack. This lets clients pass layers directly in this common case without explicitly having to construct a UsdEditTarget instance. To automatically supply the appropriate layer offset for the given layer, see UsdStage::GetEditTargetForLayer().

◆ UsdEditTarget() [3/5]

USD_API UsdEditTarget ( const SdfLayerRefPtr layer,
SdfLayerOffset  offset = SdfLayerOffset() 
)

Convenience implicit conversion from SdfLayerRefPtr.

See above constructor for more information.

◆ UsdEditTarget() [4/5]

USD_API UsdEditTarget ( const SdfLayerHandle &  layer,
const PcpNodeRef node 
)

Construct an EditTarget with layer and node.

The mapping will be used to map paths from the scene into the layer's namespace given the PcpNodeRef node's mapping.

◆ UsdEditTarget() [5/5]

USD_API UsdEditTarget ( const SdfLayerRefPtr layer,
const PcpNodeRef node 
)

Convenience constructor taking SdfLayerRefPtr.

See above constructor for more information.

Member Function Documentation

◆ ComposeOver()

USD_API UsdEditTarget ComposeOver ( const UsdEditTarget weaker) const

Return a new EditTarget composed over weaker.

This is typically used to make an EditTarget "explicit". For example, an edit target with a layer but with no mapping and no LayerStack identifier indicates a layer in the local LayerStack of a composed scene. However, an EditTarget with the same layer but an explicit identity mapping and the LayerStack identifier of the composed scene may be desired. This can be obtained by composing a partial (e.g. layer only) EditTarget over an explicit EditTarget with layer, mapping and layer stack identifier.

◆ ForLocalDirectVariant()

static USD_API UsdEditTarget ForLocalDirectVariant ( const SdfLayerHandle &  layer,
const SdfPath varSelPath 
)
static

Convenience constructor for editing a direct variant in a local LayerStack.

The varSelPath must be a prim variant selection path (see SdfPath::IsPrimVariantSelectionPath()).

◆ GetLayer()

const SdfLayerHandle& GetLayer ( ) const
inline

Return the layer this EditTarget contains.

Definition at line 140 of file editTarget.h.

◆ GetMapFunction()

const PcpMapFunction& GetMapFunction ( ) const
inline

Returns the PcpMapFunction representing the map from source specs (including any variant selections) to the stage.

Definition at line 170 of file editTarget.h.

◆ GetPrimSpecForScenePath()

USD_API SdfPrimSpecHandle GetPrimSpecForScenePath ( const SdfPath scenePath) const

Convenience function for getting the PrimSpec in the edit target's layer for scenePath.

This is equivalent to target.GetLayer()->GetPrimAtPath(target.MapToSpecPath(scenePath)) if target has a valid layer. If this target IsNull or there is no valid mapping from scenePath to a SdfPrimSpec path in the layer, return null.

◆ IsNull()

bool IsNull ( ) const
inline

Return true if this EditTarget is null.

Null EditTargets map paths unchanged, and have no layer or LayerStack identifier.

Definition at line 133 of file editTarget.h.

◆ IsValid()

bool IsValid ( ) const
inline

Return true if this EditTarget is valid, false otherwise.

Edit targets are considered valid when they have a layer.

Definition at line 137 of file editTarget.h.

◆ MapToSpecPath()

USD_API SdfPath MapToSpecPath ( const SdfPath scenePath) const

Map the provided scenePath into a SdfSpec path for the EditTarget's layer, according to the EditTarget's mapping.

Null edit targets and EditTargets for which IsLocalLayer are true return scenePath unchanged.

◆ operator!=()

bool operator!= ( const UsdEditTarget other) const
inline

Inequality comparison.

Definition at line 127 of file editTarget.h.

◆ operator==()

USD_API bool operator== ( const UsdEditTarget other) const

Equality comparison.


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