usg::GeomEngine Class Reference

#include <GeomEngine.h>

Public Member Functions
virtual std::string	name () const =0
	Name of the engine. Not saved locally as name can change dynamically. Must implement.
virtual size_t	nInputs () const =0
	Return the number of GeomEngine inputs. Must implement.
virtual GeomEngine *	inputEngine (uint32_t input) const =0
	Returns the GeomEngine pointer from input index. Must implement.
virtual GeomEngine *	inputEngine0 () const
virtual GeomEngine *	inputEngine1 () const
void	assignTarget (GeomStateTarget &target)
void	connectTargetToParent (GeomStateTarget &target, const usg::Token &parent_id)
void	connectTargetToParent (GeomStateTarget &target, GeomStateTarget &parent_target)
void	assignDefineGeometryTarget (GeomStateTarget &target)
void	assignModifyValuesTarget (GeomStateTarget &target)
void	assignEditStageTarget (GeomStateTarget &target)
GeomStateTarget *	getTarget (const usg::Token &target_id) const
	Retrieve a named change target. Not thread safe.
const GeomStateTargetPtrMap &	targets () const
const GeomStateTarget &	defineGeometryTarget () const
	Pre-assigned target that affects GeomState::defineGeometryState.
const GeomStateTarget &	modifyValuesTarget () const
	Pre-assigned target that affects GeomState::modifyValuesState.
const GeomStateTarget &	editStageTarget () const
	Pre-assigned target that affects GeomState::editStageState.
const GeomStateTarget &	affectsSteroTarget () const
	Pre-assigned target that affects GeomState::affectsStereoState.
const GeomState &	getInputState () const
	Read access to geometry states calculated in validateGeomState().
const GeomState &	getLocalState () const
const GeomState &	getOutputState () const
bool	isDirty () const
bool	isDefineGeometryStateDirty () const
bool	isModifyValuesStateDirty () const
bool	isEditStageStateDirty () const
bool	isInputStateDirty () const
	Input GeomEngine(s) have changed.
bool	isInputDefineGeometryStateDirty () const
	Input GeomEngine's define-geometry state has changed.
bool	isInputModifyValuesStateDirty () const
	Input GeomEngine's modify-values state has changed.
bool	isInputEditStageStateDirty () const
	Input GeomEngine's edit-stage state has changed.
bool	isLocalStateDirty () const
	This GeomEngine's local state has changed.
bool	isLocalDefineGeometryStateDirty () const
	This GeomEngine's local Layer define-geometry state has changed.
bool	isLocalModifyValuesStateDirty () const
	This GeomEngine's local Layer modify-values state has changed.
bool	isLocalEditStageStateDirty () const
	This GeomEngine's local edit-stage state has changed.
bool	mayAffectScenegraph () const
bool	mayAffectComposedStage () const
bool	mayModifyAttributeValues () const
bool	mayEditStage () const
EngineMode	nominalProcessingMode () const
const usg::ArgSet &	requestArgs () const
void	addRequestArgs (const usg::ArgSet &args)
	Add request args to the engine.
void	clearRequestArgs ()
	Empty the arg set.
virtual usg::StageRef	buildStageFromInput (const GeomSceneContext &context, int32_t input, bool composeStage=true)
virtual bool	needsNewStage ()
	Subclasses can override this to return true if they need a new stage to be created at this engine.
virtual usg::StageRef	createStage ()
usg::LayerRef	editLayer ()
usg::LayerRef	rootLayer ()
virtual void	initializeEditLayer (GeomSceneContext &context)
virtual void	initializeRootLayer (GeomSceneContext &context)
virtual void	clearEditLayerAuthoredProperties (GeomSceneContext &context)
virtual void	clearRootLayerAuthoredProperties (GeomSceneContext &context)
LayerRef	activeStageLayer (const GeomSceneContext &context) const
	Returns the active stage layer. This is the layer on the stage that the edit layer will be copied to after processing.
StageRef	editableStage (const GeomSceneContext &context)
void	validateGeomState ()
int32_t	processedVersion () const
fdk::Hash	getProcessedState () const
const TimeGeomStateMap &	processedTimes () const
	Concatenated set of times passed to buildScenegraph() - used for cache testing.
void	addProcessedTime (const fdk::TimeValue &time, const GeomState *state=nullptr)
bool	hasProcessedTime (const fdk::TimeValue &time) const
	Has the engine processed this time already?
bool	getProcessedTime (const fdk::TimeValue &time, GeomState &state) const
fdk::TimeValueSet	getActiveProcessingTimes (const fdk::TimeValueSet &times) const
TimeGeomStateMap	getActiveProcessingTimes (const TimeGeomStateMap &times) const
	Version that takes a time/GeomState map.
bool	hasProcessedTimes (const fdk::TimeValueSet &times) const
bool	hasProcessedTimes (const TimeGeomStateMap &times) const
	Version that takes a time/GeomState map.
void	addProcessedTimes (const fdk::TimeValueSet &times)
	Add times to the processed set.
void	addProcessedTimes (const TimeGeomStateMap &times)
	Add times and GeomStates to the processed set.
void	clearProcessedTimes ()
	Clear all the processed times.
StageRef	buildScenegraph (GeomSceneContext &sceneCtx)
virtual void	updateStageRootSublayers (usg::GeomSceneContext &context, bool force=false)
void	processScenegraphForTimes (const GeomSceneContext &src_context, const fdk::TimeValueSet &times)
virtual void	mergeFromInputs (GeomSceneContext &context, const std::vector< int32_t > &inputs)
const usg::PathArray &	getModifiedPaths () const
	Gets the modified paths list for this engine.
void	setModifiedPaths (const usg::PathArray &lastModified)
	Sets the modified paths list for this engine.
const usg::PathArray &	getCreatedPaths () const
	Gets the created paths list for this engine.
void	setCreatedPaths (const usg::PathArray &lastModified)
	Sets the created paths list for this engine.
usg::StageRef &	outputStage ()
	Returns the output stage for this engine. This does not bring the stage up to date; use buildScenegraph to evaluate the stage.
const usg::StageRef &	outputStage () const
const usg::StageRef	inputStage (int input) const
	Returns the input stage for input. This does not bring the stage up to date; use buildStageFromInput to evaluate the stage.
virtual usg::GeomSceneOutput *	sceneOutputData ()

Static Public Member Functions
static fdk::TimeValue	trimFrame (const fdk::TimeValue &time)
static GeomEngine *	ExecutingEngine ()
	Returns the currently executing GeomEngine (if any). This should only be used for error reporting.
static GeomEngine *	SetExecutingEngine (GeomEngine *engine)
	Sets the currently executing GeomEngine, returning the previous one. This should only be used for error reporting.

Protected Member Functions
virtual void	_validateGeomState ()
virtual void	processScenegraph (GeomSceneContext &context)
virtual void	editComposedStage (GeomSceneContext &context)

Protected Attributes
std::unique_ptr< class GeomEngineImpl >	_pImpl
usg::LayerRef	_rootLayer
	Cached local root Layer for input layer stack.
usg::LayerRef	_editLayer
	Cached local edit Layer.
GeomState	_inputState
	Concatenation of all input GeomEngine output states.
GeomState	_localState
	Local changes to geometry.
GeomState	_outputState
	Concatenated state includes input and local states.
usg::ArgSet	_requestArgs
	Provides additional request context for _validateGeomState()
int32_t	_processedVersion
	Incremented each time this engine runs processScenegraph()
TimeGeomStateMap	_processedTimes
	Which times have been processed since the last dirty define-prims pass.
GeomState	_lastInputState
	Concatenation of all previous input GeomEngine output states.
GeomState	_lastLocalState
	Previous local changes to geometry.
GeomState	_lastOutputState
	Concatenated state includes previous input and local states.
GeomStateTargetPtrMap	_changeTargetMap
	What the engine intends to affect.
GeomStateTarget	_defineGeometryTarget
	Pre-assigned target that affects GeomState::defineGeometryState.
GeomStateTarget	_modifyValuesTarget
	Pre-assigned target that affects GeomState::modifyValuesState.
GeomStateTarget	_editStageTarget
	Pre-assigned target that affects GeomState::editStageState.
GeomStateTarget	_affectsStereoTarget
	Pre-assigned target that affects GeomState::affectsStereoState.
usg::GeomSceneOutput *	_sceneOutputData
	Optional engine-specific output arbitrary scene data.

Friends
class	GeomEngineImpl

Detailed Description

Scenegraph processing engine node that can build a usg::Stage.

Member Function Documentation

assignTarget()

void usg::GeomEngine::assignTarget

(

GeomStateTarget &

target

)

Assign a change target to engine. It's assumed the target object is a local variable in this class and will not disappear or become invalid! Not thread safe.

connectTargetToParent() [1/2]

void usg::GeomEngine::connectTargetToParent	(	GeomStateTarget &	target,
		const usg::Token &	parent_id
	)

Add a change target to engine, parented to a parent change target group. It's assumed the target object is a local variable in this class and will not disappear or become invalid! Not thread safe.

connectTargetToParent() [2/2]

void usg::GeomEngine::connectTargetToParent	(	GeomStateTarget &	target,
		GeomStateTarget &	parent_target
	)

Add a change target to engine, parented to an existing parent target. Not thread safe.

targets()

const GeomStateTargetPtrMap & usg::GeomEngine::targets ( ) const

inline

Retrieve the set of change targets assigned to this engine. Not thread safe.

isDirty()

bool usg::GeomEngine::isDirty

(

)

const

Does the GeomEngine need to re-process? This could be because the inputs GeomState changed or the local GeomState changed. Note that this only indicates that the engine -may- need to reprocess. Check the other dirty indicators to determine what specifically needs updating.

mayAffectScenegraph()

bool usg::GeomEngine::mayAffectScenegraph

(

)

const

Return true if the output state != the input state. Does not indicate if the engine needs to process the scene, only that the engine will be run when dirty.

mayAffectComposedStage()

bool usg::GeomEngine::mayAffectComposedStage

(

)

const

Return true if the output define-geometry state != the input define-geometry state. Does not indicate if the engine needs to process the scene, only that the engine will be run when dirty.

mayModifyAttributeValues()

bool usg::GeomEngine::mayModifyAttributeValues

(

)

const

Return true if the output modify-values state != the input modify-values state. Does not indicate if the engine needs to process the scene, only that the engine will be run when dirty.

mayEditStage()

bool usg::GeomEngine::mayEditStage

(

)

const

Return true if the output edit-stage state != the input edit-stage state. Does not indicate if the engine needs to process the scene, only that the engine will be run when dirty.

nominalProcessingMode()

EngineMode usg::GeomEngine::nominalProcessingMode

(

)

const

Returns the nominal processing mode the engine should handle in processScenegraph() based on the engine's current dirty state flags and what state targets the engine has declared it wants to handle. This value is assigned to the GeomSceneContext before processScenegraph() is called.

trimFrame()

static fdk::TimeValue usg::GeomEngine::trimFrame ( const fdk::TimeValue &  time )

static

Rounds the time value to three decimal places (ie .001, a thousandth of a frame) to make it more useful as a key value for things like std::map, etc.

requestArgs()

const usg::ArgSet & usg::GeomEngine::requestArgs ( ) const

inline

The 'request' ArgSet can be used during engine evaluation to influence its behavior, typically set by the system managing the GeomEngine network. The args are not used by the GeomEngine base class.

buildStageFromInput()

virtual usg::StageRef usg::GeomEngine::buildStageFromInput ( const GeomSceneContext &  context, int32_t  input, bool  composeStage = true  )

virtual

Returns the evaluated stage frominput.. If composeStage is true, the stage is fully composed. You can set this to false if you don't care about the stage but simply want the input engines and their edit layers to be brought up to date. Note that if multiple inputs lead back to the same stage via a split in the graph, you may get the same stage back for these inputs, the second call modifying the stage you got back from the first call, so you should be careful to deal gracefully with this possibility.

createStage()

virtual usg::StageRef usg::GeomEngine::createStage ( )

virtual

Subclasses can override this to return a new stage. This is generally only required for an engine which needs to set the asset resolver context.

editLayer()

usg::LayerRef usg::GeomEngine::editLayer

(

)

Return the edit layer for the engine. Base class returns the local _editLayer var. This layer is where all local prim/attribute defines & edits are stored.

rootLayer()

usg::LayerRef usg::GeomEngine::rootLayer

(

)

Return the root layer for the engine. Base class returns the local _rootLayer var. If there are local edits present in the _editLayer after processScenegraph() has run the edit_layer will be inserted into _rootLayer as the highest-priority sublayer (layer 0.)

initializeEditLayer()

virtual void usg::GeomEngine::initializeEditLayer ( GeomSceneContext &  context )

virtual

Called in buildScenegraph() when defineGeometryState is dirty, to clear out _editLayer in preparation for defining prims, attribs. A subclass can implement this to perform custom initialization if the default clearing of _editLayer is not desired, such as an importer which caches the input layer, or to defer clearing until processScenegraph() is called.

Note that clearing a Layer's content can cause a global stage change notification since it may force a stage recomposition. To avoid this an engine should also pay attention to the modifyValuesTarget() state, which indicates when the attribute's contents should be cleared vs. the attribute's definition.

Base class implementation calls _editLayer->clear(). GeomSceneContext is provided in case request scope args are required.

initializeRootLayer()

virtual void usg::GeomEngine::initializeRootLayer ( GeomSceneContext &  context )

virtual

Called in buildScenegraph() when defineGeometryState is dirty, to clear out _rootLayer in preparation for defining prims, attribs, or layering operations. A subclass can implement this to perform custom initialization if the default clearing of _rootLayer is not desired, or to defer clearing until processScenegraph() is called.

Note that clearing a Layer's content can cause a global stage change notification since it may force a stage recomposition. To avoid this an engine should also pay attention to the modifyValuesTarget() state, which indicates when the attribute's contents should be cleared vs. the attribute's definition.

Base class implementation calls _rootLayer->clear(). GeomSceneContext is provided in case request scope args are required.

clearEditLayerAuthoredProperties()

virtual void usg::GeomEngine::clearEditLayerAuthoredProperties ( GeomSceneContext &  context )

virtual

Called in buildScenegraph() when modifyValuesState is dirty, to clear all currently authored properties (default values, time samples, relationships, etc) from _editLayer, while retaining their definitions, avoiding Stage path-change notifications and a possible recompose.

Base class implementation calls _editLayer->clearAuthoredProperties(). A subclass can implement this to perform custom behavior such as deferring any work until processScenegraph() is called.

GeomSceneContext is provided in case request scope args are required.

clearRootLayerAuthoredProperties()

virtual void usg::GeomEngine::clearRootLayerAuthoredProperties ( GeomSceneContext &  context )

virtual

Called in buildScenegraph() when modifyValuesState is dirty, to clear all currently authored properties (default values, time samples, relationships, etc) from _rootLayer, while retaining their definitions, avoiding Stage path-change notifications and a possible recompose.

Base class implementation calls _rootLayer->clearAuthoredProperties(). A subclass can implement this to perform custom behavior such as deferring any work until processScenegraph() is called.

GeomSceneContext is provided in case request scope args are required.

editableStage()

StageRef usg::GeomEngine::editableStage

(

const GeomSceneContext &

context

)

Returns a stage set up for use in processScenegraph. Engines can use this to make changes to the stage using raw UsdStage APIs (for example via Python). If an engine calls this method, it must not make any changes to the edit layer. All changes must be made via the returned stage.

validateGeomState()

void usg::GeomEngine::validateGeomState

(

)

Calculate the input and output GeomStates and update the dirty status of the GeomEngine. A subclass can manipulate the state vars in a _validateGeomState() implementation.

processedVersion()

int32_t usg::GeomEngine::processedVersion ( ) const

inline

Current processing version for this engine. This number is incremented each time this engine runs processScenegraph() and reset to zero when the define or modify states are dirty.

A change in this number is a good indicator that a modification may have been made to a Layer or Stage attribute value contents.

getProcessedState()

fdk::Hash usg::GeomEngine::getProcessedState

(

)

const

Returns the processing state of the engine which can be used to track if processing changes may have been applied to the engine's layers or stage. This hash is a combination of the outputState and the current processed version number.

addProcessedTime()

void usg::GeomEngine::addProcessedTime	(	const fdk::TimeValue &	time,
		const GeomState *	state = nullptr
	)

Add a single processed time to the _processedTimes set. If state is provided then its value is stored otherwise the engine's _outputState is.

getProcessedTime()

bool usg::GeomEngine::getProcessedTime	(	const fdk::TimeValue &	time,
		GeomState &	state
	)		const

Retrieve the GeomState of the processed time, returning true if there was an existing GeomState entry for the time.

getActiveProcessingTimes()

fdk::TimeValueSet usg::GeomEngine::getActiveProcessingTimes

(

const fdk::TimeValueSet &

times

)

const

Returns the set of TimeValues to process for this GeomEngine, which is the TimeValues from the times set minus the ones in the _processedTimes that match the engine's current _outputState.

In other words this method removes the already processed times from the passed-in set.

hasProcessedTimes()

bool usg::GeomEngine::hasProcessedTimes

(

const fdk::TimeValueSet &

times

)

const

Same as getActiveProcessingTimes() but returns true if all times in times are already in _processedTimes.

buildScenegraph()

StageRef usg::GeomEngine::buildScenegraph

(

GeomSceneContext &

sceneCtx

)

Process/build the scene, filling in any Layers this GeomEngine owns and updating the output Stage contained in the GeomSceneContext context.

This method examines the dirty states of the GeomEngine to determine whether to call the virtual processScenegraph() method so the engine subclass can perform any work defined by the dirty state.

When this method completes the engine's dirty state is cleared and the 'last' GeomStates updated to the current ones.

If composeStage is true the stage's root sublayer stack will be updated to this engine likely causing the stage to recompose if the stack is different than the one current in it. This is useful when an engine needs its input results composed so it can query before doing additional scenegraph processing.

updateStageRootSublayers()

virtual void usg::GeomEngine::updateStageRootSublayers ( usg::GeomSceneContext &  context, bool  force = false  )

virtual

Called in processScenegraph when the engine is dirty due to any reason. We double check that the dirty state is in fact different from the state on the stage, if so we re-copy layers, this is for both composition and non composition changes, and we leave it to the copyLayers method to handle these cases. Specifically it sets the stage root layer's sublayer stack which ultimately determines the stage's composition state, and thus calling this method will usually cause a full stage re-composition.

Default implementation checks the engine's current sublayer state hash against the stage's current root layer state hash and only updates the stack if they differ. This can be overriden by passing force = true. If updating is needed the stage's root layer is updated with the engine's current sublayer list and the stage's root state hash updated to the engine's current sublayer state hash.

A subclass can override this to perform any additional work related to setting the root state.

processScenegraphForTimes()

void usg::GeomEngine::processScenegraphForTimes	(	const GeomSceneContext &	src_context,
		const fdk::TimeValueSet &	times
	)

Directly runs processScenegraph() for all TimeValues in times, which is used instead of the times in src_context. A new GeomSceneContext is constructed with the new TimeValueSet and passed to processScenegraph(). After processing the times are added to the current processed set.

This method does not test any states and is equivalent to calling the following code: GeomSceneContext new_context(src_context, times); processScenegraph(new_context); addProcessedTimes(times);

mergeFromInputs()

virtual void usg::GeomEngine::mergeFromInputs ( GeomSceneContext &  context, const std::vector< int32_t > &  inputs  )

virtual

Merges the layers from inputs into the _rootLayer. These are merged in reverse order.

sceneOutputData()

virtual usg::GeomSceneOutput * usg::GeomEngine::sceneOutputData ( )

virtual

Return the companion arbitrary output data for this engine. Base class returns the local _sceneOutputData var.

_validateGeomState()

virtual void usg::GeomEngine::_validateGeomState ( )

inlineprotectedvirtual

Subclass portion of validateGeomState().

GeomEngine subclasses can mess with the local GeomState here to take into account input parameters, internal calculations, etc.

Default implementation does nothing.

processScenegraph()

virtual void usg::GeomEngine::processScenegraph ( GeomSceneContext &  context )

protectedvirtual

Subclass-specific engine implementation called by buildScenegraph().

Default implementation gets the root layer from inputEngine0() by calling buildScenegraph() on it, then copies the SubLayer paths from the root layer.

editComposedStage()

virtual void usg::GeomEngine::editComposedStage ( GeomSceneContext &  context )

protectedvirtual

Subclass-specific engine implementation called by buildScenegraph(), after processScenegraph(), and only if affectsComposedStage()==true.

Default implementation does nothing.