This document is for a version of USD that is under development. See this page for the current release.
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages
copyUtils.h File Reference
+ Include dependency graph for copyUtils.h:

Go to the source code of this file.

Classes

class  SdfCopySpecsValueEdit
 Value containing an editing operation for SdfCopySpecs. More...
 

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)
 Utility function for copying spec data at srcPath in srcLayer to destPath in destLayer.
 

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)>
 Return true if field should be copied from the spec at srcPath in srcLayer to the spec at dstPath in dstLayer.
 
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.
 
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.
 
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.
 
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.
 

Typedef Documentation

◆ SdfShouldCopyChildrenFn

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 140 of file copyUtils.h.

◆ SdfShouldCopyValueFn

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

Function Documentation

◆ SdfCopySpec() [1/2]

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.

If srcLayer and dstLayer are the same, and either srcPath or dstPath is a prefix of the other (see SdfPath::HasPrefix()), then the source and destination overlap. In this case, to avoid modifying the source during the copy operation, SdfCopySpec() first creates a temporary anonymous layer and copies the source to it. Then it copies that temporary to the destination.

◆ SdfCopySpec() [2/2]

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.

If srcLayer and dstLayer are the same, and either srcPath or dstPath is a prefix of the other (see SdfPath::HasPrefix()), then the source and destination overlap. In this case, to avoid modifying the source during the copy operation, SdfCopySpec() first creates a temporary anonymous layer and copies the source to it using the SdfCopySpec() overload that does not take "shouldCopy" functions. Then it copies that temporary to the destination. In this case the shouldCopyValueFn and shouldCopyChildrenFn will be called with the temporary source layer rather than the original source layer, but the source paths will be the same.

◆ SdfShouldCopyChildren()

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.

◆ SdfShouldCopyValue()

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.