usg::Stage Class Reference

#include <Stage.h>

Public Types
enum	LoadRule { AllRule , OnlyRule , NoneRule }
	Abstraction handle for casting to underlying implementation type. More...
enum class	TraversePolicy { DontTraverse , FirstInSubTree , All }
	Indicates how the stage should be traversed while searching for prims. More...
enum class	MaskOperation { Set , Clear , Union , Intersection }
	An operation for setPopulationMask.
typedef std::vector< std::pair< Path, LoadRule > >	LoadRules
	A Structure for passing load rules to the stage.

Public Member Functions
bool	isValid () const
	True if Stage::Impl is valid (has a valid object binding.)
	operator bool () const
Stage::Handle *	getUsdStageRefPtr (int usd_version)
const Stage::Handle *	getUsdStageRefPtr (int usd_version) const
void	setEditTarget (const LayerRef &edit_layer)
	Sets the edit target layer of the stage.
void	setLoadRules (const LoadRules &rules)
	Set the load rules for the stage.
LoadRules	getLoadRules ()
	Get the load rules for the stage.
PathSet	getLoadSet () const
	Returns a set of all loaded paths.
LayerRef	getRootLayer () const
	Returns the root layer of the stage.
LayerRef	getSessionLayer () const
	Returns the session layer of the stage.
Prim	getRootPrim () const
	Returns the root prim of the stage.
Prim	getPrimAtPath (const Path &path) const
	Returns the prim at path.
size_t	getPrimPaths (PathArray &prim_paths) const
std::vector< LayerRef >	getLayerStack () const
template<class T >
PathArray	findPrimsOfType (const PathArray &primPaths, TraversePolicy policy) const
template<class T >
PathArray	findPrimsOfType (const PathArray &primPaths, bool matchDescendents=true) const
template<class T >
std::vector< T >	findDescendentPrims (const PathArray &primPaths) const
PathArray	findLoadable (const Path &rootPath=Path::AbsoluteRootPath()) const
	Returns all paths that can be loaded from the stage.
void	load (const PathSet &pathSet, bool loadWithDescendants=true, bool replace=false)
	Batch load the given path set. This is equivalent to calling Prim::load()
void	loadAndUnload (const PathSet &loadSet, const PathSet &unloadSet, bool loadWithDescendants)
	Batch load and unload the given path sets. This is equivalent to calling Prim::load()
void	setPopulationMask (const PathArray &primPaths, MaskOperation op=MaskOperation::Set)
void	muteAndUnmuteLayers (const std::vector< std::string > &muteLayers, const std::vector< std::string > &unmuteLayers)
	Mutes and unmutes layers on the stage.
const std::vector< std::string >	getMutedLayers () const
	Returns the list of muted layers.
PrimRange	traverse () const
PrimRange	traverse (const Prim::FlagsPredicate &mask) const
	Build a PrimRange traverser using a specific predicate mask.
PrimRange	traverseAll () const
	Build a PrimRange traverser using the Prim::AllPrimsPredicate (ie no filtering.)
usg::PathArray	getPrimPathsByTypeName (const usg::Token &typeName, bool traverseModelHierarchy=true)
fdk::Box3d	getWorldBbox (const fdk::TimeValue &time) const
	Compute the world-space bounding-box for the entire stage at a specific time (required.)
void	setMetersPerUnit (double metersPerUnit)
	Set the metersPerUnit metadata tag on the stage.
bool	hasMetersPerUnit () const
	Is the metersPerUnit metadata tag authored on the stage?
double	getMetersPerUnit () const
LayerRef	flatten (bool addComment=true)
	Returns the flattened stage as a single anonymous layer.
LayerRef	flattenLayerStack ()
	Returns the flattened stage as a single anonymous layer. Unlike 'flatten', this preserves variants and some composition arcs.
bool	exportToFile (const std::string &filepath, bool addComment=true, const FileFormatArgs &fileFormatArgs=FileFormatArgs())
	Exports the flattened stage to a file.
bool	exportToString (std::string &text, bool addComment=true)
	Exports the flattened stage to a string.
Path	getDefaultParentPath () const
	Return the attribute representing the 'default parent' from the top-most (strongest) layer.
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
void	copyFrom (const usg::StageRef &stage)
	Copies the populationMask, load rules and muted layers from stage.
void	printReport (std::ostream &o, bool print_contents=true) const
std::string	resolveIdentifierToEditTarget (const std::string &identifier)
	Stage (const Stage::Impl &)
	Wrapper abstraction for implementation type.
Stage::Impl *	impl ()
const Stage::Impl *	impl () const
void	setComposeState (const fdk::Hash &compose_state)
	Set the compose state hash explicitly (usually passed to the latest stage Create()).
fdk::Hash	composeState () const
	Get the compose state hash currently assigned to the stage.
void	setProcessState (const fdk::Hash &process_state)
	Set hashes to help track the lastest modify state affecting the stage.
fdk::Hash	processState () const
void	setEditState (const fdk::Hash &edit_state)
	Set hashes to help track the latest edit state of the stage.
fdk::Hash	editState () const
void	setRootState (const fdk::Hash &root_state)
fdk::Hash	rootState () const

Static Public Member Functions
static StageRef	Create (const LayerRef &sessionLayer, const fdk::Hash *composeState=nullptr, bool loadAll=true)
static StageRef	Create (const LayerRef &rootLayer, const LayerRef &sessionLayer, const fdk::Hash *composeState=nullptr, bool loadAll=true)
static StageRef	CreateMasked (const LayerRef &sessionLayer, const PathArray &maskedPaths, const fdk::Hash *composeState=nullptr, bool loadAll=true)
static StageRef	CreateInMemory (bool loadAll=true, const std::string &arResolverContext="")
	Creates an empty Stage.
static StageRef	CreateInMemory (bool loadAll, const std::vector< std::pair< std::string, std::string > > &arResolverContexts)
static StageRef	Open (const std::string &filePath)
	Creates a new Stage from the given file path.

Detailed Description

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

Member Enumeration Documentation

LoadRule

enum usg::Stage::LoadRule

Abstraction handle for casting to underlying implementation type.

Load rules for setting the locations to be included / excluded during loading

TraversePolicy

enum class usg::Stage::TraversePolicy

strong

Indicates how the stage should be traversed while searching for prims.

Enumerator
DontTraverse	Don't traverse the stage, searching only the given paths.
FirstInSubTree	Traverse the stage but stop at the first occurence in a sub-tree.
All	Fully traverse the stage.

Member Function Documentation

Create() [1/2]

static StageRef usg::Stage::Create ( const LayerRef &  sessionLayer, const fdk::Hash *  composeState = nullptr, bool  loadAll = true  )

static

Creates a new Stage from the session layer. If compose_state is provided it's copied into the Stage::Impl and retrievable via Stage::composeState().

Create() [2/2]

static StageRef usg::Stage::Create ( const LayerRef &  rootLayer, const LayerRef &  sessionLayer, const fdk::Hash *  composeState = nullptr, bool  loadAll = true  )

static

Creates a new Stage from the given root layer and session layer. If compose_state is provided it's copied into the Stage::Impl and retrievable via Stage::composeState().

CreateMasked()

static StageRef usg::Stage::CreateMasked ( const LayerRef &  sessionLayer, const PathArray &  maskedPaths, const fdk::Hash *  composeState = nullptr, bool  loadAll = true  )

static

Creates a new stage from the given root layer limiting its population to the prims provided by maskedPaths. If composeState is provided it's copied into the Stage::Impl and retrievable via Stage::composeState().

getUsdStageRefPtr()

Stage::Handle * usg::Stage::getUsdStageRefPtr

(

int

usd_version

)

Return a pointer to the underlying UsdStage 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 a UsdStageRefPtr* and possibly double-check its validity since a Stage can be created without a valid binding. However, if Stage::isValid() returns true then the underlying binding will also be valid.

getPrimPaths()

size_t usg::Stage::getPrimPaths

(

PathArray &

prim_paths

)

const

Returns all prim paths in the stage. Caution - this can potentially be a very expensive operation on large stages!

findPrimsOfType() [1/2]

template<class T >

PathArray usg::Stage::findPrimsOfType	(	const PathArray &	primPaths,
		TraversePolicy	policy
	)		const

Given a list of paths, iterates through them and optionally their descendents, returning a list of all prims matching the type T. The stage traversal is controlled by TraversePolicy.

findPrimsOfType() [2/2]

template<class T >

PathArray usg::Stage::findPrimsOfType	(	const PathArray &	primPaths,
		bool	matchDescendents = true
	)		const

Given a list of paths, iterates through them and optionally their descendents, returning a list of all prims matching the type T.

findDescendentPrims()

template<class T >

std::vector< T > usg::Stage::findDescendentPrims

(

const PathArray &

primPaths

)

const

Given a list of paths, iterates through them and their descendents, returning a list of all prims of type T.

setPopulationMask()

void usg::Stage::setPopulationMask	(	const PathArray &	primPaths,
		MaskOperation	op = MaskOperation::Set
	)

Set the population mask for the stage. Use this to limit the prims that are composed. This is useful for isolating prims.

traverse()

PrimRange usg::Stage::traverse

(

)

const

Build a PrimRange traverser using the Prim::DefaultPredicate mask (ie Prim::IsActive && Prim::IsDefined && Prim::IsLoaded && -Prim::IsAbstract).

getMetersPerUnit()

double usg::Stage::getMetersPerUnit

(

)

const

Return the metersPerUnit metatada tag if authored, otherwise 0.1, the USD default of centimeters. Note the default unit for Nuke is meters so always check hasMetersPerUnit() to avoid getting centimeters by mistake.

setRootState()

void usg::Stage::setRootState

(

const fdk::Hash &

root_state

)

Set a state hash to help track the root layer's sublayer list state. Normally this is used to quickly test sublayer list status.