Loading...
Searching...
No Matches
flattenUtils.h File Reference

Utilities for flattening layer stacks into a single layer. More...

+ Include dependency graph for flattenUtils.h:

Go to the source code of this file.

Classes

class  UsdFlattenResolveAssetPathContext
 Context object containing information used when resolving asset paths during layer stack flattening. More...
 

Typedefs

using UsdFlattenResolveAssetPathFn = std::function< std::string(const SdfLayerHandle &sourceLayer, const std::string &assetPath)>
 Callback function for overloaded version of UsdFlattenLayerStack.
 
using UsdFlattenResolveAssetPathAdvancedFn = std::function< std::string(const UsdFlattenResolveAssetPathContext &)>
 Callback function for UsdFlattenLayerStack.
 

Functions

 SDF_DECLARE_HANDLES (SdfLayer)
 
USD_API SdfLayerRefPtr UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const std::string &tag=std::string())
 Flatten layerStack into a single layer with the given optional tag.
 
USD_API SdfLayerRefPtr UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const UsdFlattenResolveAssetPathFn &resolveAssetPathFn, const std::string &tag=std::string())
 Flatten the layerStack into a single layer with the given optional tag and using the resolveAssetPathFn to resolve asset paths that are encountered.
 
USD_API std::string UsdFlattenLayerStackResolveAssetPath (const SdfLayerHandle &sourceLayer, const std::string &assetPath)
 Implements the default asset path flattening behavior for UsdFlattenLayerStack.
 
USD_API SdfLayerRefPtr UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const UsdFlattenResolveAssetPathAdvancedFn &resolveAssetPathFn, const std::string &tag=std::string())
 Flatten the layerStack into a single layer with the given optional tag and using the resolveAssetPathFn to resolve asset paths that are encountered.
 
USD_API std::string UsdFlattenLayerStackResolveAssetPathAdvanced (const UsdFlattenResolveAssetPathContext &context)
 Implements the default asset path flattening behavior for UsdFlattenLayerStack.
 

Detailed Description

Utilities for flattening layer stacks into a single layer.

Definition in file flattenUtils.h.


Class Documentation

◆ UsdFlattenResolveAssetPathContext

class UsdFlattenResolveAssetPathContext

Context object containing information used when resolving asset paths during layer stack flattening.

Definition at line 134 of file flattenUtils.h.

Class Members
string assetPath Authored asset path.
VtDictionary expressionVariables Expression variables from the layer stack.
SdfLayerHandle sourceLayer Layer where the asset path is authored.

Typedef Documentation

◆ UsdFlattenResolveAssetPathAdvancedFn

using UsdFlattenResolveAssetPathAdvancedFn = std::function< std::string(const UsdFlattenResolveAssetPathContext&)>

Callback function for UsdFlattenLayerStack.

The callback is given a UsdFlattenResolveAssetPathContext containing information needed to resolve a given asset path. It should return the std::string that should be authored in the flattened layer.

See also
UsdFlattenLayerStack

Definition at line 154 of file flattenUtils.h.

◆ UsdFlattenResolveAssetPathFn

using UsdFlattenResolveAssetPathFn = std::function<std::string( const SdfLayerHandle& sourceLayer, const std::string& assetPath)>

Callback function for overloaded version of UsdFlattenLayerStack.

The callback is given the sourceLayer and the assetPath authored in that layer. It should return the std::string that should be authored in the flattened layer.

See also
UsdFlattenLayerStackResolveAssetPath

Definition at line 79 of file flattenUtils.h.

Function Documentation

◆ UsdFlattenLayerStack() [1/3]

USD_API SdfLayerRefPtr UsdFlattenLayerStack ( const PcpLayerStackRefPtr &  layerStack,
const std::string &  tag = std::string() 
)

Flatten layerStack into a single layer with the given optional tag.

A composed UsdStage created from this flattened layer will be the same as a composed UsdStage whose root layer stack is the original layer stack.

Unlike UsdStage::Flatten(), this function does not flatten composition arcs, such as references, payloads, inherits, specializes, or variants.

Sublayer time offsets on the sublayers will be applied to remap any time-keyed scene description, such as timeSamples and clips.

Asset paths will be resolved to absolute form, to ensure that they continue to identify the same asset from the output layer.

Asset paths containing stage variable expressions will be evaluated using the variables from the root and session layer of layerStack before being resolved.

See also
UsdFlattenLayerStackResolveAssetPath

A few historical scene description features cannot be flattened into a single opinion because they unfortunately encode operations that are not closed under composition. Specifically, the SdfListOp operations "add" and "reorder" cannot be flattened. Instead, "add" will be converted to "append", and "reorder" will be discarded.

◆ UsdFlattenLayerStack() [2/3]

USD_API SdfLayerRefPtr UsdFlattenLayerStack ( const PcpLayerStackRefPtr &  layerStack,
const UsdFlattenResolveAssetPathAdvancedFn resolveAssetPathFn,
const std::string &  tag = std::string() 
)

Flatten the layerStack into a single layer with the given optional tag and using the resolveAssetPathFn to resolve asset paths that are encountered.

This is an advanced version of UsdFlattenLayerStack that provides full control over how asset paths are resolved during flattening via the resolveAssetPathFn callback. For example, the callback might maintain relative asset paths instead of resolving them to absolute form. As another example, the callback might maintain stage variable expressions in their unevaluated form.

◆ UsdFlattenLayerStack() [3/3]

USD_API SdfLayerRefPtr UsdFlattenLayerStack ( const PcpLayerStackRefPtr &  layerStack,
const UsdFlattenResolveAssetPathFn resolveAssetPathFn,
const std::string &  tag = std::string() 
)

Flatten the layerStack into a single layer with the given optional tag and using the resolveAssetPathFn to resolve asset paths that are encountered.

This is an advanced version of the above function.

One use case for this version of the function is to flatten a layer stack that contains relative asset paths that we want to preserve as relative paths. For example:

/source/root.usd # sublayers a.usd and b.usd
/source/a.usd # contains reference to ./subdir/layer.usd
/source/b.usd
/source/subdir/layer.usd

We may want to generate "/dest/root.flat.usd" knowing that we will (by some other means) also be copying "/source/subdir" into "/dest/subdir". It's useful then to preserve the relative paths.

Note, only the caller knows the ultimate destination of the flattened layer. So to accomplish this, we can provide a resolveAssetPathFn callback that captures the outputDir, tests if the authored path is relative, and if so, computes a new relative path (based on where it will eventually be exported).

Asset paths containing stage variable expressions will be evaluated using the variables from the root and session layer of layerStack. The evaluated asset path will be passed to the resolveAssetPathFn callback instead of the original asset path.

See also
UsdFlattenLayerStackResolveAssetPath.

◆ UsdFlattenLayerStackResolveAssetPath()

USD_API std::string UsdFlattenLayerStackResolveAssetPath ( const SdfLayerHandle &  sourceLayer,
const std::string &  assetPath 
)

Implements the default asset path flattening behavior for UsdFlattenLayerStack.

assetPath will be anchored to sourceLayer by calling SdfComputeAssetPathRelativeToLayer. This function assumes that assetPath does not contain a stage variable expression.

◆ UsdFlattenLayerStackResolveAssetPathAdvanced()

USD_API std::string UsdFlattenLayerStackResolveAssetPathAdvanced ( const UsdFlattenResolveAssetPathContext context)

Implements the default asset path flattening behavior for UsdFlattenLayerStack.

The asset path in context will be anchored to the source layer by calling SdfComputeAssetPathRelativeToLayer. If the asset path contains a stage variable expression, it will be evaluated using the expression variables in context before being anchored.