The implementation of a system to procedurally compute values based on USD scene description and computation definitions. More...

#include <system.h>

Inheritance diagram for ExecUsdSystem:

Public Member Functions
EXECUSD_API	ExecUsdSystem (const UsdStageConstRefPtr &stage)

	ExecUsdSystem (const ExecUsdSystem &)=delete

ExecUsdSystem &	operator= (const ExecUsdSystem &)=delete

EXECUSD_API void	ChangeTime (UsdTimeCode time)
	Changes the `time` at which values are computed.

EXECUSD_API ExecUsdRequest	BuildRequest (std::vector< ExecUsdValueKey > &&valueKeys, ExecRequestComputedValueInvalidationCallback &&valueCallback=ExecRequestComputedValueInvalidationCallback(), ExecRequestTimeChangeInvalidationCallback &&timeCallback=ExecRequestTimeChangeInvalidationCallback())
	Builds a request for the given `valueKeys`.

EXECUSD_API void	PrepareRequest (const ExecUsdRequest &request)
	Prepares a given `request` for execution.

EXECUSD_API ExecUsdCacheView	Compute (const ExecUsdRequest &request)
	Executes the given `request` and returns a cache view for extracting the computed values.

Additional Inherited Members
Protected Member Functions inherited from ExecSystem
EXEC_API	ExecSystem (EsfStage &&stage)
	Construct an exec system for computing values on `stage`.

	ExecSystem (const ExecSystem &)=delete

ExecSystem &	operator= (const ExecSystem &)=delete

EXEC_API void	_ChangeTime (const EfTime &time)
	Changes time on the system.

EXEC_API void	_Compute (const VdfSchedule &schedule, const VdfRequest &computeRequest)
	Computes the values in the `computeRequest` using the provided `schedule`.

EXEC_API void	_ParallelForEachRequest (TfFunctionRef< void(Exec_RequestImpl &)> f) const
	Invoke `f` on each outstanding exec request.

Detailed Description

The implementation of a system to procedurally compute values based on USD scene description and computation definitions.

ExecUsdSystem specializes the base ExecSystem class and owns USD-specific structures and logic necessary to compile, schedule and evaluate requested computation values.

The ExecUsdSystem extends the lifetime of the UsdStage it is constructed with, although it is atypical for an ExecUsdSystem to outlive its stage in practice. As a rule of thumb, the ExecUsdSystem lives right alongside the UsdStage in most use-cases.

Definition at line 44 of file system.h.

Member Function Documentation

◆ BuildRequest()

EXECUSD_API ExecUsdRequest BuildRequest	(	std::vector< ExecUsdValueKey > &&	valueKeys,
		ExecRequestComputedValueInvalidationCallback &&	valueCallback = `ExecRequestComputedValueInvalidationCallback()`,
		ExecRequestTimeChangeInvalidationCallback &&	timeCallback = `ExecRequestTimeChangeInvalidationCallback()`
	)

Builds a request for the given valueKeys.

The optionally provided valueCallback will be invoked when previously computed value keys become invalid as a result of authored value changes or structural invalidation of the scene. If multiple value keys become invalid at the same time, they may be batched into a single invocation of the callback.

Note: The valueCallback is only guaranteed to be invoked at least once per invalid value key and invalid time interval combination, and only after Compute() has been called. If clients want to be notified of future invalidation, they must call Compute() again to renew their interest in the computed value keys.

The optionally provided timeCallback will be invoked when previously computed value keys become invalid as a result of time changing. The invalid value keys are the set of time-dependent value keys in this request, further filtered to only include the value keys where input dependencies are actually changing between the old time and new time.

Note: The client must not call into execution (including, but not limited to Compute() or value extraction) from within the valueCallback, as well as the timeCallback.

◆ ChangeTime()

EXECUSD_API void ChangeTime ( UsdTimeCode time )

Changes the time at which values are computed.

Calling this method re-resolves time-dependent inputs from the scene graph at the new time, and determines which of these inputs are actually changing between the old and new time. Computed values that are dependent on the changing inputs are then invalidated, and requests are notified of the time change.

Note: When computing multiple requests over multiple times, it is much more efficient to compute all requests at the same time, before moving on to the next time. Doing so, allows time-dependent intermediate results to remain cached and be re-used across the multiple calls to Compute().

◆ Compute()

EXECUSD_API ExecUsdCacheView Compute ( const ExecUsdRequest & request )

Executes the given request and returns a cache view for extracting the computed values.

This implicitly calls PrepareRequest(), though clients may choose to call PrepareRequest() ahead of time and front-load the associated compilation and scheduling cost.

◆ PrepareRequest()

EXECUSD_API void PrepareRequest ( const ExecUsdRequest & request )

Prepares a given request for execution.

This ensures the exec network is compiled and scheduled for the value keys in the request. Compute() will implicitly prepare the request if needed, but calling PrepareRequest() separately enables clients to front-load compilation and scheduling cost.

The documentation for this class was generated from the following file:

pxr/exec/execUsd/system.h