flattenUtils.h File Reference

#include "pxr/pxr.h"
#include "pxr/usd/usd/api.h"
#include "pxr/usd/usd/stage.h"
#include "pxr/usd/sdf/declareHandles.h"
#include "pxr/usd/pcp/layerStackIdentifier.h"

Include dependency graph for flattenUtils.h:

Go to the source code of this file.

Classes
class	UsdFlattenResolveAssetPathContext

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

Functions
PXR_NAMESPACE_OPEN_SCOPE	SDF_DECLARE_HANDLES (SdfLayer)
USD_API SdfLayerRefPtr	UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const std::string &tag=std::string())
USD_API SdfLayerRefPtr	UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const UsdFlattenResolveAssetPathFn &resolveAssetPathFn, const std::string &tag=std::string())
USD_API std::string	UsdFlattenLayerStackResolveAssetPath (const SdfLayerHandle &sourceLayer, const std::string &assetPath)
USD_API SdfLayerRefPtr	UsdFlattenLayerStack (const PcpLayerStackRefPtr &layerStack, const UsdFlattenResolveAssetPathAdvancedFn &resolveAssetPathFn, const std::string &tag=std::string())
USD_API std::string	UsdFlattenLayerStackResolveAssetPathAdvanced (const UsdFlattenResolveAssetPathContext &context)

Detailed Description

Utilities for flattening layer stacks into a single layer.

Definition in file flattenUtils.h.

Typedef Documentation

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 155 of file flattenUtils.h.

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 81 of file flattenUtils.h.

Function Documentation

PXR_NAMESPACE_OPEN_SCOPE 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.

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.

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.

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.

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.

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.