usg::Layer Class Reference

#include <Layer.h>

Public Member Functions
bool	isValid () const
	Returns true if the layer has a wrapped layer.
	operator bool () const
class Layer::Handle *	getSdfLayerRefPtr (int usd_version)
const class Layer::Handle *	getSdfLayerRefPtr (int usd_version) const
void	clear ()
bool	isEmpty () const
	Returns true if the layer contains no prims.
void	reload ()
	Restores the layer to a state as if it had just been created with findOrOpen().
const std::string &	getIdentifier () const
	Returns the identifier string passed originally to the constructor.
void	setIdentifier (const std::string &identifier)
	Sets the layer identifier.
void	combineSubLayers (const LayerRef &layer)
	Adds all sublayers of layer to this layer.
fdk::StringList	getSubLayers () const
	Fetches the sublayer identifier list for this layer.
size_t	getSubLayers (fdk::StringList &sublayerIdentifiers) const
	Fetches the sublayer identifier list for this layer. Returns the number of sublayers.
void	setSubLayers (const fdk::StringList &sublayerIdentifiers)
	Sets the list of the layer sublayers.
void	setSubLayers (const LayerRef &layer)
	Sets the list of the layer sublayers to be the same as layer.
void	insertSubLayer (const std::string &sublayerIdentifier, int index=-1)
void	insertSubLayer (const LayerRef &sublayer, int index=-1)
size_t	getNumSubLayers () const
	Returns the number of sublayers..
void	setCustomLayerData (const Token &key, const Value &value)
	Sets a value in the custom data for this layer.
Value	getCustomLayerData (const Token &key) const
	Returns the value for key in the custom data for this l;ayer.
void	setModifiedPaths (const PathArray &paths)
	Sets the list of modified paths for this layer. This can be used by ops to signal the last-modified prims to downstream ops.
PathArray	getModifiedPaths () const
	Returns the list of modified paths for this layer.
void	setCreatedPaths (const PathArray &paths)
	Sets the list of created paths for this layer. This can be used by ops to signal the created prims to downstream ops.
PathArray	getCreatedPaths () const
	Returns the list of created paths for this layer.
void	setDefaultParentPath (const Path &path)
	Sets the list of default parent path for this layer. This can be used by ops to specify a default parent path for downstream ops.
Path	getDefaultParentPath () const
	Returns the list of default parent path for this layer.
void	setOwner (const std::string &owner)
	Sets the layer's owner.
std::string	getOwner () const
	Gets the layer's owner.
void	clearOwner ()
	Clears the layer's owner.
void	setSessionOwner (const std::string &sessionOwner)
	Sets the layer's session owner.
std::string	getSessionOwner () const
	Gets the layer's session owner.
void	setComment (const std::string &comment)
	Sets the layer's comment.
std::string	getComment () const
	Gets the layer's comment.
void	setDocumentation (const std::string &documentation)
	Sets the layer's documentation.
std::string	getDocumentation () const
	Gets the layer's documentation.
void	setColorConfiguration (const AssetPath &colorConfiguration)
	Sets the layer's color configuration.
AssetPath	getColorConfiguration () const
	Gets the layer's color configuration.
void	setColorManagementSystem (const Token &colorManagementSystem)
	Sets the layer's color configuration.
Token	getColorManagementSystem () const
	Gets the layer's color configuration.
void	setStartTimeCode (double timeCode)
	Sets the start time code.
double	getStartTimeCode () const
	Gets the start time code.
void	setEndTimeCode (double timeCode)
	Sets the end time code.
double	getEndTimeCode () const
	Gets the end time code.
void	setFramesPerSecond (double framesPerSecond)
	Sets the frames per second.
double	getFramesPerSecond () const
	Gets the frames per second.
void	setTimeCodesPerSecond (double timeCodesPerSecond)
	Sets the time codes per second.
double	getTimeCodesPerSecond () const
	Gets the time codes per second.
void	setFramePrecision (int framePrecision)
	Sets the frame precision.
int	getFramePrecision () const
	Gets the frame precision.
void	setOwnerNodeName (const std::string &owner)
	Sets the name of the node which owns this layer. This can be used to enable the node selection mechanism for custom layers.
std::string	getOwnerNodeName () const
	Returns the name of the node which owns this layer, or an empty string if none.
void	setLayerInfoAttribute (const Token &key, const Value &value)
	Sets a attribute value in the private layer info prim.
void	setLayerInfoRelationship (const Token &key, const PathArray &paths)
	Sets a relationship value in the private layer info prim.
Value	getLayerInfoAttribute (const Token &key) const
	Returns the value for key in the private layer info prim.
PathArray	getLayerInfoRelationship (const Token &key) const
	Returns the path array for key in the private layer info prim.
size_t	getCompositionAssetDependencies (fdk::StringList &assetIdentifiers) const
	Fetches the composition asset identifiers for this layer. Returns the number of assets.
Token	getUpAxis () const
	Returns the up axis for the layer. If not set, returns "Y"/.
void	setUpAxis (const Token &upAxis)
	Sets the up axis for the layer.
void	changeBlockPush ()
void	changeBlockPop ()
size_t	getTimeSamples (std::set< fdk::TimeValue > &times) const
	Fills in the list of unique times samples in the layer, and returns the total count.
void	setSubLayerScaleAndOffset (int index, double offset, double scale)
	Set the time scale and offset for the layer.
void	getSubLayerScaleAndOffset (int index, double &offset, double &scale) const
	Get the time scale and offset for the layer.
Prim	definePrim (const Path &path, const Token &typeName)
Prim	overridePrim (const Path &path, const Token &typeName)
	Same as definePrim() but the created Prim will have an 'over' specifier.
Prim	overridePrim (const Path &path)
	Same as overridePrim(path, typeName) but the created Prim will have an no Type.
Prim	overridePrim (const Prim &src_prim)
Prim	classPrim (const Path &path, const Token &typeName)
	Same as definePrim() but the created Prim will have an 'class' specifier.
Prim	getRootPrim () const
	Returns the root prim of the layer.
Prim	getPrimAtPath (const Path &path) const
	Returns the prim defined at the given path.
size_t	getPrimPaths (PathArray &prim_paths) const
	Returns all prim paths defined in this layer.
size_t	getAttrPaths (PathArray &attr_paths) const
	Returns all attribute paths defined in this layer.
bool	hasDefaultPrim () const
	Returns true if the layer has a default prim.
Token	defaultPrim () const
	Returns the name of the default prim of the layer, or a empty token if none.
void	setDefaultPrim (const Token &name)
	Sets the name of the default prim of the layer.
void	clearDefaultPrim ()
	Clears the default prim of the layer.
void	clearAuthoredPrims ()
void	clearAuthoredProperties ()
Prim	defineScopeParents (const Path &path, const Token &last_prim_schema="Scope")
Prim	defineScopeXformParents (const Path &path)
bool	isAnonymous () const
	Returns true if the layer is anonymous.
std::string	getRealPath () const
	Returns the resolved file path of the layer.
bool	save (bool force=false)
	Saves the layer.
bool	exportToFile (const std::string &filepath, const std::string &comment=std::string(), const FileFormatArgs &fileFormatArgs=FileFormatArgs()) const
	Exports the flattened layer to a file.
bool	exportToString (std::string &text) const
	Exports the flattened layer to a string.
bool	importFromString (const std::string &text) const
	Imports the layer from a string.
void	transferContent (const LayerRef &layer)
	Transfers the content of layer into this layer.
void	stitch (const LayerRef &weakLayer)
	Stitches the content of weakLayer into this layer.
void	copySpec (const Path &path, const LayerRef &targetLayer, const Path &targetPath)
PathArray	getModifiedPrimPaths () const
	Returns a list of paths which may have been modified. This means any prim with a 'def' specifier, or an over with property definitions.
void	printContents (const char *prefix, std::ostream &) const
	Output the contents of the layer to a stream. Calls exportToString().
	Layer (const Layer::Impl &)
	Wrapper abstraction for implementation type.
Layer::Impl *	impl ()
	Returns the handle to the wrapped object.
const Layer::Impl *	impl () const

Static Public Member Functions
static LayerRef	Create (const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
	Abstraction handle for casting to underlying implementation type.
static LayerRef	CreateAnonymous (const std::string &identifier=std::string(), const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
	Creates a new anonymous layer with the given identifier.
static std::vector< LayerRef >	GetLoadedLayers ()
	Gets a vector of all currently loaded layers.
static LayerRef	Find (const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
static LayerRef	FindOrOpen (const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
static LayerRef	FindRelativeToLayer (const LayerRef &anchor, const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
static LayerRef	FindOrOpenRelativeToLayer (const LayerRef &anchor, const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
static LayerRef	Create (const Layer::Impl &handle)
	Creates a layer wrapper from the given layer.

Friends
class	Prim
USG_API std::ostream &	operator<< (std::ostream &, const Layer &)
	Print out Layer components to a stream.
USG_API bool	operator== (const Layer &lhs, const Layer &rhs)
	Compares the handles to underlying sdf layers.
USG_API bool	operator!= (const Layer &lhs, const Layer &rhs)

Detailed Description

The wrapper class for a reference to a layer. When passing layer references, use LayerRef instead of Layer as that provides a pointer-like interface with access via the -> operator.

Member Function Documentation

Create()

static LayerRef usg::Layer::Create ( const std::string &  identifier, const fdk::KeyValueMapSorted &  file_args = fdk::KeyValueMapSorted()  )

static

Abstraction handle for casting to underlying implementation type.

Creates a new layer with the given identifier

Find()

static LayerRef usg::Layer::Find ( const std::string &  identifier, const fdk::KeyValueMapSorted &  file_args = fdk::KeyValueMapSorted()  )

static

Searches for a layer with the given identifier in the layer cache. If the identifier string is empty nothing happens and a null reference is returned. If the layer can't be found a null reference is returned.

The identifer can be just a local session name like 'MyEditLayer' or it can be a file path pointing at an external Usd file like '/Foo/MyEditLayer.usd'.

If this Layer will be written to a file you should provide the appropriate file extension (.usd, .usda, .usdc, etc) at this time, and any arguments to be passed to the file format plugin.

FindOrOpen()

static LayerRef usg::Layer::FindOrOpen ( const std::string &  identifier, const fdk::KeyValueMapSorted &  file_args = fdk::KeyValueMapSorted()  )

static

Searches for a layer with the given identifier in the layer cache, opening it if it's not already open. If the identifier string is empty nothing happens and a null reference is returned.

The identifer can be just a local session name like 'MyEditLayer' or it can be a file path pointing at an external Usd file like '/Foo/MyEditLayer.usd'.

If this Layer will be written to a file you should provide the appropriate file extension (.usd, .usda, .usdc, etc) at this time, and any arguments to be passed to the file format plugin.

FindRelativeToLayer()

static LayerRef usg::Layer::FindRelativeToLayer ( const LayerRef &  anchor, const std::string &  identifier, const fdk::KeyValueMapSorted &  file_args = fdk::KeyValueMapSorted()  )

static

Searches for a layer with the given identifier in the layer cache. If the identifier string is empty nothing happens and a null reference is returned. If the layer can't be found a null reference is returned.

The identifier will be resolved relative to the anchor layer. If the anchor layer is invalid nothing happens and a null reference is returned.

The identifer can be just a local session name like 'MyEditLayer' or it can be a file path pointing at an external Usd file like '/Foo/MyEditLayer.usd'.

If this Layer will be written to a file you should provide the appropriate file extension (.usd, .usda, .usdc, etc) at this time, and any arguments to be passed to the file format plugin.

FindOrOpenRelativeToLayer()

static LayerRef usg::Layer::FindOrOpenRelativeToLayer ( const LayerRef &  anchor, const std::string &  identifier, const fdk::KeyValueMapSorted &  file_args = fdk::KeyValueMapSorted()  )

static

Searches for a layer with the given identifier in the layer cache, opening it if it's not already open. If the identifier string is empty nothing happens and a null reference is returned.

The identifier will be resolved relative to the anchor layer. If the anchor layer is invalid nothing happens and a null reference is returned.

The identifer can be just a local session name like 'MyEditLayer' or it can be a file path pointing at an external Usd file like '/Foo/MyEditLayer.usd'.

If this Layer will be written to a file you should provide the appropriate file extension (.usd, .usda, .usdc, etc) at this time, and any arguments to be passed to the file format plugin.

getSdfLayerRefPtr()

class Layer::Handle * usg::Layer::getSdfLayerRefPtr

(

int

usd_version

)

Returns a pointer to the underlying SdfLayer object if the usd_version passed in matches the Usd version this library was built with, otherwise return null.

The version must match the one returned by usg::usdAPIVersion().

Caller should cast the returned pointer to an SdfLayerRefPtr* and possibly double-check its validity since a Layer can be created without a valid binding. However, if Layer::isValid() returns true then the underlying binding will also be valid.

clear()

void usg::Layer::clear

(

)

Clears the layer, clearing out any existing prims. Note that this will likely cause a Stage recompose since it's removing all prim and property definitions. Use clearAttributeContents() instead if you want to retain the definitions but empty all property value assignments.

insertSubLayer() [1/2]

void usg::Layer::insertSubLayer	(	const std::string &	sublayerIdentifier,
		int	index = -1
	)

Inserts a new sublayer at the given index. The default index of -1 means insert at the end. Sublayer index 0 has the strongest opinion and the last sublayer in the list has the weakest.

insertSubLayer() [2/2]

void usg::Layer::insertSubLayer	(	const LayerRef &	sublayer,
		int	index = -1
	)

Inserts a new sublayer. The default index of -1 means insert at the end. Sublayer index 0 has the strongest opinion and the last sublayer in the list has the weakest.

changeBlockPush()

void usg::Layer::changeBlockPush

(

)

Add/enable a level of change notification blocking so that a series of prim or property changes done to the layer can be bundled up as one big change.

changeBlockPop()

void usg::Layer::changeBlockPop

(

)

Remove one level of change blocking. If this is the last pop the blocker is removed and the change notification is done.

definePrim()

Prim usg::Layer::definePrim	(	const Path &	path,
		const Token &	typeName
	)

Defines an abstract Prim in this Layer assigned to the 'schema_class' name. The 'schema_class' is the prim's schema name like 'Mesh', 'Scope', 'Xform', etc. The created Prim will have a 'def' specifier.

If a prim already exists at 'path' it is returned unchanged.

If the parent prims in the path do not exist they will be created but will lack any specific schema and have an 'over' specifier.

overridePrim()

Prim usg::Layer::overridePrim

(

const Prim &

src_prim

)

Similar to definePrim() but the created Prim will have an 'over' specifier and the schema class is taken from the provided source Prim.

clearAuthoredPrims()

void usg::Layer::clearAuthoredPrims

(

)

Clears all authored prim definitions in the layer. This will cause Stage path-change notifications and a possible recompose. Note this is different than calling Layer::clear() which will remove everything from the Layer including sublayers and custom data.

clearAuthoredProperties()

void usg::Layer::clearAuthoredProperties

(

)

Clears all authored property/relationship values in the layer while retaining their definitions, avoiding Stage path-change notifications and a possible recompose. Clearing authored values will cause 'Info Path' change notifications, but these should not precipitate a Stage recomposition event.

Removes each property's default value and all time samples.

defineScopeParents()

Prim usg::Layer::defineScopeParents	(	const Path &	path,
		const Token &	last_prim_schema = "Scope"
	)

Defines a parenting path of Scope prims to anchor another prim set to. If the prims in the path already exist but are not Scope types they're left alone. Returns the last Prim in the path, regardless of whether it's a Scope or not.

defineScopeXformParents()

Prim usg::Layer::defineScopeXformParents ( const Path &  path )

inline

Defines a parenting path of Scope prims with a final Xform prim to anchor another prim to. If the prims in the path already exist but are not Scope types they're left alone. Returns the last Prim in the path, regardless of whether it's a Scope or not.