stitch.h File Reference

#include "pxr/pxr.h"
#include "pxr/usd/usdUtils/api.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/spec.h"
#include <functional>

Include dependency graph for stitch.h:

Go to the source code of this file.

Functions
PXR_NAMESPACE_OPEN_SCOPE	SDF_DECLARE_HANDLES (SdfLayer)
USDUTILS_API void	UsdUtilsStitchLayers (const SdfLayerHandle &strongLayer, const SdfLayerHandle &weakLayer)
USDUTILS_API void	UsdUtilsStitchInfo (const SdfSpecHandle &strongObj, const SdfSpecHandle &weakObj)

Advanced Stitching API
enum	UsdUtilsStitchValueStatus { UsdUtilsStitchValueStatus::NoStitchedValue, UsdUtilsStitchValueStatus::UseDefaultValue, UsdUtilsStitchValueStatus::UseSuppliedValue }
using	UsdUtilsStitchValueFn = std::function< UsdUtilsStitchValueStatus(const TfToken &field, const SdfPath &path, const SdfLayerHandle &strongLayer, bool fieldInStrongLayer, const SdfLayerHandle &weakLayer, bool fieldInWeakLayer, VtValue *stitchedValue)>
USDUTILS_API void	UsdUtilsStitchLayers (const SdfLayerHandle &strongLayer, const SdfLayerHandle &weakLayer, const UsdUtilsStitchValueFn &stitchValueFn)
USDUTILS_API void	UsdUtilsStitchInfo (const SdfSpecHandle &strongObj, const SdfSpecHandle &weakObj, const UsdUtilsStitchValueFn &stitchValueFn)

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

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 111 of file stitch.h.

Enumeration Type Documentation

enum 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 88 of file stitch.h.

Function Documentation

PXR_NAMESPACE_OPEN_SCOPE SDF_DECLARE_HANDLES

(

SdfLayer

)

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.

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.

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.

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.