All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
stitch.h File Reference

Collection of module-scoped utilities for combining layers. More...

+ Include dependency graph for stitch.h:

Go to the source code of this file.

Functions

 SDF_DECLARE_HANDLES (SdfLayer)
 
USDUTILS_API void UsdUtilsStitchLayers (const SdfLayerHandle &strongLayer, const SdfLayerHandle &weakLayer)
 Merge all scene description in weakLayer into strongLayer.
 
USDUTILS_API void UsdUtilsStitchInfo (const SdfSpecHandle &strongObj, const SdfSpecHandle &weakObj)
 Merge the scene description for weakObj into strongObj.
 

Advanced Stitching API

enum class  UsdUtilsStitchValueStatus { NoStitchedValue , UseDefaultValue , UseSuppliedValue }
 Status enum returned by UsdUtilsStitchValueFn describing the desired value stitching behavior. More...
 
using UsdUtilsStitchValueFn = std::function< UsdUtilsStitchValueStatus(const TfToken &field, const SdfPath &path, const SdfLayerHandle &strongLayer, bool fieldInStrongLayer, const SdfLayerHandle &weakLayer, bool fieldInWeakLayer, VtValue *stitchedValue)>
 Callback for customizing how values are stitched together.
 
USDUTILS_API void UsdUtilsStitchLayers (const SdfLayerHandle &strongLayer, const SdfLayerHandle &weakLayer, const UsdUtilsStitchValueFn &stitchValueFn)
 Advanced version of UsdUtilsStitchLayers that accepts a stitchValueFn callback to customize how fields in strongLayer and weakLayer are stitched together.
 
USDUTILS_API void UsdUtilsStitchInfo (const SdfSpecHandle &strongObj, const SdfSpecHandle &weakObj, const UsdUtilsStitchValueFn &stitchValueFn)
 Advanced version of UsdUtilsStitchInfo that accepts a stitchValueFn callback to customize how fields in strongObj and weakObj are stitched together.
 

Detailed Description

Collection of module-scoped utilities for combining layers.

These utilize the convention of a strong and a weak layer. The strong layer will be the first parameter to the function and will always have precedence in conflicts during the merge.

Definition in file stitch.h.

Typedef Documentation

◆ UsdUtilsStitchValueFn

using UsdUtilsStitchValueFn = std::function< UsdUtilsStitchValueStatus( const TfToken& field, const SdfPath& path, const SdfLayerHandle& strongLayer, bool fieldInStrongLayer, const SdfLayerHandle& weakLayer, bool fieldInWeakLayer, VtValue* stitchedValue)>

Callback for customizing how values are stitched together.

This callback will be invoked for each field being stitched from the source spec at path in weakLayer to the destination spec at path in strongLayer. fieldInStrongLayer and fieldInWeakLayer indicates whether the field has values in either layer.

The callback should return a UsdUtilsStitchValueStatus to indicate the desired behavior. Note that if the callback returns UseSuppliedValue and supplies an empty VtValue in stitchedValue, the field will be removed from the destination spec.

Definition at line 89 of file stitch.h.

Enumeration Type Documentation

◆ UsdUtilsStitchValueStatus

enum class UsdUtilsStitchValueStatus
strong

Status enum returned by UsdUtilsStitchValueFn describing the desired value stitching behavior.

Enumerator
NoStitchedValue 

Don't stitch values for this field.

UseDefaultValue 

Use the default stitching behavior for this field.

UseSuppliedValue 

Use the value supplied in stitchedValue.

Definition at line 71 of file stitch.h.

Function Documentation

◆ UsdUtilsStitchInfo() [1/2]

USDUTILS_API void UsdUtilsStitchInfo ( const SdfSpecHandle &  strongObj,
const SdfSpecHandle &  weakObj 
)

Merge the scene description for weakObj into strongObj.

See documentation on UsdUtilsStitchLayers for a description of the merging behavior.

◆ UsdUtilsStitchInfo() [2/2]

USDUTILS_API void UsdUtilsStitchInfo ( const SdfSpecHandle &  strongObj,
const SdfSpecHandle &  weakObj,
const UsdUtilsStitchValueFn stitchValueFn 
)

Advanced version of UsdUtilsStitchInfo that accepts a stitchValueFn callback to customize how fields in strongObj and weakObj are stitched together.

See documentation on UsdUtilsStitchValueFn for more details.

◆ UsdUtilsStitchLayers() [1/2]

USDUTILS_API void UsdUtilsStitchLayers ( const SdfLayerHandle &  strongLayer,
const SdfLayerHandle &  weakLayer 
)

Merge all scene description in weakLayer into strongLayer.

Prims and properties in weakLayer that do not exist in strongLayer will be copied into strongLayer. Prims and properties that do exist in strongLayer will be merged with the existing scene description.

Merging prims and properties is done on a field-by-field basis. In general, if a field has a value in strongLayer, the value from weakLayer will be ignored. However, certain fields have special rules for merging values together:

  • For map and dictionary-valued fields (including time samples), a dictionary merge is performed; values in the weaker dictionary are copied into the stronger dictionary only if the key does not already exist.
  • For listOp-valued fields, the listOps will be combined into a single listOp. The historical "add" and "reorder" list op operations cannot be combined in this way; "add" will be converted to "append", and "reorder" will be discarded.
  • The minimum startTimeCode value and maximum endTimeCode value will be used.

◆ UsdUtilsStitchLayers() [2/2]

USDUTILS_API void UsdUtilsStitchLayers ( const SdfLayerHandle &  strongLayer,
const SdfLayerHandle &  weakLayer,
const UsdUtilsStitchValueFn stitchValueFn 
)

Advanced version of UsdUtilsStitchLayers that accepts a stitchValueFn callback to customize how fields in strongLayer and weakLayer are stitched together.

See documentation on UsdUtilsStitchValueFn for more details.