usg::Layer Class Reference

#include <Layer.h>

Public Member Functions
virtual	~Layer ()
	Abstraction handle for casting to underlying implementation type.
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	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.
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	setSubLayerScaleAndOffset (int index, double offset, double scale)
	Set the time scale and offset 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	setStartTimeCode (fdk::TimeValue time)
	Start of active time sample range.
fdk::TimeValue	getStartTimeCode ()
void	setEndTimeCode (fdk::TimeValue time)
	End of active time sample range.
fdk::TimeValue	getEndTimeCode ()
void	setTimeCodesPerSecond (double timeCodesPerSecond)
	Falls back to framesPerSecond, then to a default value of 24.0.
double	getTimeCodesPerSecond () const
void	setFramesPerSecond (double fps)
double	getFramesPerSecond () const
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 Prim &src_prim)
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	copySpec (const Path &path, const LayerRef &targetLayer, const Path &targetPath)
usg::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 &)
	Create a layer from a Layer::Impl.
Layer::Impl *	impl ()
	Returns the handle to the wrapped object.
const Layer::Impl *	impl () const
void	setPreEditCacheMetadata (uint64_t cache_hash)
	Update the cache layer metadata values. For internal use only.
bool	getPreEditCacheMetadata (std::string &cache_layer_id, uint64_t &cache_layer_hash)
	Retrieve the current cache layer metadata values, returning true on success. For internal use only.

Static Public Member Functions
static LayerRef	Create (const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
	Creates a new layer with the given identifier.
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 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 usg::LayerRef &anchor, const std::string &identifier, const fdk::KeyValueMapSorted &file_args=fdk::KeyValueMapSorted())
static LayerRef	FindOrOpenRelativeToLayer (const usg::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

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 usg::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 usg::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.