usg::Stage Class Reference

#include <Stage.h>

Public Member Functions
virtual	~Stage ()
	Abstraction handle for casting to underlying implementation type.
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.
LayerRef	getRootLayer () const
	Returns the root layer of the stage.
LayerRef	getSessionLayer ()
	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
template<class T >
PathArray	findPrimsOfType (const PathArray &primPaths, bool matchDescendents=true) const
template<class T >
std::vector< T >	findDescendentPrims (const PathArray &primPaths) const
void	setPopulationMask (const PathArray &primPaths)
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.)
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
usg::LayerRef	flatten (bool addComment=true)
	Returns the flattened stage as a single anonymous layer.
usg::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	printReport (std::ostream &o, bool print_contents=true) const
	Stage (const Stage::Impl &)
	Create a stage wrapper from a Stage::Impl.
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
void	setPreEditCacheMetadata (const std::string &cache_layer_id, uint64_t cache_hash)
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.
void	retrievePreEditCacheProperties (const LayerRef &cache_layer, const fdk::TimeValue &time=fdk::defaultTimeValue())

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 ()
	Creates an empty Stage.
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 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()

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

)

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.

setPreEditCacheMetadata()

void usg::Stage::setPreEditCacheMetadata	(	const std::string &	cache_layer_id,
		uint64_t	cache_hash
	)

Update Stage and cache Layer custom metadata with the cache layer info to be used during geometry_engine() edit calls. For internal use only.

retrievePreEditCacheProperties()

void usg::Stage::retrievePreEditCacheProperties	(	const LayerRef &	cache_layer,
		const fdk::TimeValue &	time = fdk::defaultTimeValue()
	)

Copy property values from the Layer to the Stage, normally used to restore cached 'pre-edited' values prior to possibly applying a new edit.

This iterates through all properties defined in the Layer. For internal use only.