copyUtils.h File Reference

#include "pxr/pxr.h"
#include "pxr/usd/sdf/api.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/sdf/types.h"
#include <functional>
#include <optional>

Include dependency graph for copyUtils.h:

Go to the source code of this file.

Classes
class	SdfCopySpecsValueEdit

Functions
	SDF_DECLARE_HANDLES (SdfLayer)
Simple Spec Copying API
SDF_API bool	SdfCopySpec (const SdfLayerHandle &srcLayer, const SdfPath &srcPath, const SdfLayerHandle &dstLayer, const SdfPath &dstPath)

Advanced Spec Copying API
using	SdfShouldCopyValueFn = std::function< bool(SdfSpecType specType, const TfToken &field, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, std::optional< VtValue > *valueToCopy)>
using	SdfShouldCopyChildrenFn = std::function< bool(const TfToken &childrenField, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, std::optional< VtValue > *srcChildren, std::optional< VtValue > *dstChildren)>
SDF_API bool	SdfShouldCopyValue (const SdfPath &srcRootPath, const SdfPath &dstRootPath, SdfSpecType specType, const TfToken &field, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, std::optional< VtValue > *valueToCopy)
SDF_API bool	SdfShouldCopyChildren (const SdfPath &srcRootPath, const SdfPath &dstRootPath, const TfToken &childrenField, const SdfLayerHandle &srcLayer, const SdfPath &srcPath, bool fieldInSrc, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, bool fieldInDst, std::optional< VtValue > *srcChildren, std::optional< VtValue > *dstChildren)
SDF_API bool	SdfCopySpec (const SdfLayerHandle &srcLayer, const SdfPath &srcPath, const SdfLayerHandle &dstLayer, const SdfPath &dstPath, const SdfShouldCopyValueFn &shouldCopyValueFn, const SdfShouldCopyChildrenFn &shouldCopyChildrenFn)

Typedef Documentation

using SdfShouldCopyChildrenFn = std::function< bool(const TfToken& childrenField, const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc, const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst, std::optional<VtValue>* srcChildren, std::optional<VtValue>* dstChildren)>

Return true if childrenField and the child objects the field represents should be copied from the spec at srcPath in srcLayer to the spec at dstPath in dstLayer. fieldInSrc and fieldInDst indicates whether that field has values at the source and destination specs. Return false otherwise.

This function may modify which children are copied by filling in srcChildren and dstChildren with the children to copy and their destination. Both of these values must be set, and must contain the same number of children.

Note that if this function returns true and the source spec has no value for childrenField (e.g., fieldInSrc == false), the field in the destination spec will also be set to no value, causing any existing children to be removed.

Definition at line 156 of file copyUtils.h.

using SdfShouldCopyValueFn = std::function< bool(SdfSpecType specType, const TfToken& field, const SdfLayerHandle& srcLayer, const SdfPath& srcPath, bool fieldInSrc, const SdfLayerHandle& dstLayer, const SdfPath& dstPath, bool fieldInDst, std::optional<VtValue>* valueToCopy)>

Return true if field should be copied from the spec at srcPath in srcLayer to the spec at dstPath in dstLayer. fieldInSrc and fieldInDst indicates whether the field has values at the source and destination specs. Return false otherwise.

This function may modify the value that is copied by filling in valueToCopy with the desired value. valueToCopy may also be a SdfCopySpecsValueEdit that specifies an editing operation for this field. If valueToCopy is not set, the field value from the source spec will be used as-is. Setting valueToCopy to an empty VtValue indicates that the field should be removed from the destination spec, if it already exists.

Note that if this function returns true and the source spec has no value for field (e.g., fieldInSrc == false), the field in the destination spec will also be set to no value.

Definition at line 103 of file copyUtils.h.

Function Documentation

SDF_DECLARE_HANDLES

(

SdfLayer

)

SDF_API bool SdfCopySpec	(	const SdfLayerHandle &	srcLayer,
		const SdfPath &	srcPath,
		const SdfLayerHandle &	dstLayer,
		const SdfPath &	dstPath
	)

Utility function for copying spec data at srcPath in srcLayer to destPath in destLayer.

Copying is performed recursively: all child specs are copied as well. Any destination specs that already exist will be overwritten.

Parent specs of the destination are not created, and must exist before SdfCopySpec is called, or a coding error will result. For prim parents, clients may find it convenient to call SdfCreatePrimInLayer before SdfCopySpec.

As a special case, if the top-level object to be copied is a relationship target or a connection, the destination spec must already exist. That is because we don't want SdfCopySpec to impose any policy on how list edits are made; client code should arrange for relationship targets and connections to be specified as prepended, appended, deleted, and/or ordered, as needed.

Variant specs may be copied to prim paths and vice versa. When copying a variant to a prim, the specifier and typename from the variant's parent prim will be used.

Attribute connections, relationship targets, inherit and specializes paths, and internal sub-root references that target an object beneath srcPath will be remapped to target objects beneath dstPath.

SDF_API bool SdfCopySpec	(	const SdfLayerHandle &	srcLayer,
		const SdfPath &	srcPath,
		const SdfLayerHandle &	dstLayer,
		const SdfPath &	dstPath,
		const SdfShouldCopyValueFn &	shouldCopyValueFn,
		const SdfShouldCopyChildrenFn &	shouldCopyChildrenFn
	)

Utility function for copying spec data at srcPath in srcLayer to destPath in destLayer. Various behaviors (such as which parts of the spec to copy) are controlled by the supplied shouldCopyValueFn and shouldCopyChildrenFn.

Copying is performed recursively: all child specs are copied as well, except where prevented by shouldCopyChildrenFn.

Parent specs of the destination are not created, and must exist before SdfCopySpec is called, or a coding error will result. For prim parents, clients may find it convenient to call SdfCreatePrimInLayer before SdfCopySpec.

Variant specs may be copied to prim paths and vice versa. When copying a variant to a prim, the specifier and typename from the variant's parent prim will be used.

As a special case, if the top-level object to be copied is a relationship target or a connection, the destination spec must already exist. That is because we don't want SdfCopySpec to impose any policy on how list edits are made; client code should arrange for relationship targets and connections to be specified as prepended, appended, deleted, and/or ordered, as needed.

SDF_API bool SdfShouldCopyChildren	(	const SdfPath &	srcRootPath,
		const SdfPath &	dstRootPath,
		const TfToken &	childrenField,
		const SdfLayerHandle &	srcLayer,
		const SdfPath &	srcPath,
		bool	fieldInSrc,
		const SdfLayerHandle &	dstLayer,
		const SdfPath &	dstPath,
		bool	fieldInDst,
		std::optional< VtValue > *	srcChildren,
		std::optional< VtValue > *	dstChildren
	)

SdfShouldCopyChildrenFn used by the simple version of SdfCopySpec.

Copies all child values from the source, transforming path-valued fields prefixed with srcRootPath to have the prefix dstRootPath.

Existing values in the destination will be overwritten by values in the source. Any fields in the destination that aren't in the source will be cleared.

SDF_API bool SdfShouldCopyValue	(	const SdfPath &	srcRootPath,
		const SdfPath &	dstRootPath,
		SdfSpecType	specType,
		const TfToken &	field,
		const SdfLayerHandle &	srcLayer,
		const SdfPath &	srcPath,
		bool	fieldInSrc,
		const SdfLayerHandle &	dstLayer,
		const SdfPath &	dstPath,
		bool	fieldInDst,
		std::optional< VtValue > *	valueToCopy
	)

SdfShouldCopyValueFn used by the simple version of SdfCopySpec.

Copies all values from the source, transforming path-valued fields prefixed with srcRootPath to have the prefix dstRootPath.

Existing values in the destination will be overwritten by values in the source. Any fields in the destination that aren't in the source will be cleared.