HdTask Class Reference

HdTask represents a unit of work to perform during a Hydra render. More...

#include <task.h>

Inheritance diagram for HdTask:

Public Member Functions
HD_API	HdTask (SdfPath const &id)
	Construct a new task.
virtual HD_API bool	IsConverged () const
	This function returns true when a (progressive) task considers its execution results converged.
virtual void	Sync (HdSceneDelegate *delegate, HdTaskContext *ctx, HdDirtyBits *dirtyBits)=0
	Sync Phase: Obtain task state from Scene delegate based on change processing.
virtual void	Prepare (HdTaskContext *ctx, HdRenderIndex *renderIndex)=0
	Prepare Phase: Resolve bindings and manage resources.
virtual void	Execute (HdTaskContext *ctx)=0
	Execute Phase: Runs the task.
virtual HD_API const TfTokenVector &	GetRenderTags () const
	Render Tag Gather.
SdfPath const &	GetId () const
virtual HD_API HdDirtyBits	GetInitialDirtyBitsMask () const
	Returns the minimal set of dirty bits to place in the change tracker for use in the first sync of this prim.

Protected Member Functions
template<class T >
bool	_GetTaskParams (HdSceneDelegate *delegate, T *outValue)
	Extracts a typed value out of the task context at the given id.
HD_API TfTokenVector	_GetTaskRenderTags (HdSceneDelegate *delegate)

Static Protected Member Functions
static HD_API bool	_HasTaskContextData (HdTaskContext const *ctx, TfToken const &id)
	Check if the shared context contains a value for the given id.
template<class T >
static bool	_GetTaskContextData (HdTaskContext const *ctx, TfToken const &id, T *outValue)
	Extracts a typed value out of the task context at the given id.
template<class T >
static T	_GetDriver (HdTaskContext const *ctx, TfToken const &driverName)
	Extract an object from a HdDriver inside the task context.

Detailed Description

HdTask represents a unit of work to perform during a Hydra render.

Developers can subclass HdTask to prepare resources, run 3d renderpasses, run 2d renderpasses such as compositing or color correction, or coordinate integration with the application or other renderers.

Definition at line 43 of file task.h.

Constructor & Destructor Documentation

HdTask()

HD_API HdTask

(

SdfPath const &

id

)

Construct a new task.

If the task is going to be added to the render index, id should be an absolute scene path. If the task isn't going to be added to the render index an empty path should be used for id.

Member Function Documentation

_GetDriver()

T _GetDriver ( HdTaskContext const *  ctx, TfToken const &  driverName  )

staticprotected

Extract an object from a HdDriver inside the task context.

Returns nullptr if driver was not found.

Definition at line 266 of file task.h.

_GetTaskContextData()

bool _GetTaskContextData ( HdTaskContext const *  ctx, TfToken const &  id, T *  outValue  )

staticprotected

Extracts a typed value out of the task context at the given id.

If the id is missing or of the wrong type, the code will throw a verify error, return false and outValue will be unmodified. in case of success, the return value is true and the value is copied into outValue.

outValue must not be null.

Definition at line 215 of file task.h.

_GetTaskParams()

bool _GetTaskParams ( HdSceneDelegate *  delegate, T *  outValue  )

protected

Extracts a typed value out of the task context at the given id.

If the id is missing or of the wrong type, the code will throw a verify error, return false and outValue will be unmodified. in case of success, the return value is true and the value is copied into outValue.

outValue must not be null.

Definition at line 245 of file task.h.

_HasTaskContextData()

static HD_API bool _HasTaskContextData ( HdTaskContext const *  ctx, TfToken const &  id  )

staticprotected

Check if the shared context contains a value for the given id.

Execute()

virtual void Execute ( HdTaskContext *  ctx )

pure virtual

Execute Phase: Runs the task.

The execution phase should trigger render delegate processing, such as issuing draw commands.

Task execution is non-parallel and ordered.

The task context is the same as used by the prepare step and is used for inter-task communication.

Implemented in HdxAovInputTask, HdxBoundingBoxTask, HdxColorChannelTask, HdxColorCorrectionTask, HdxColorizeSelectionTask, HdxOitRenderTask, HdxOitResolveTask, HdxOitVolumeRenderTask, HdxPickFromRenderBufferTask, HdxPickTask, HdxPresentTask, HdxRenderSetupTask, HdxRenderTask, HdxSelectionTask, HdxShadowTask, HdxSkydomeTask, and HdxVisualizeAovTask.

GetId()

SdfPath const & GetId ( ) const

inline

Definition at line 156 of file task.h.

GetInitialDirtyBitsMask()

virtual HD_API HdDirtyBits GetInitialDirtyBitsMask ( ) const

virtual

Returns the minimal set of dirty bits to place in the change tracker for use in the first sync of this prim.

Typically this would be all dirty bits.

GetRenderTags()

virtual HD_API const TfTokenVector & GetRenderTags ( ) const

virtual

Render Tag Gather.

Is called during the Sync phase after the task has been sync'ed.

The task should return the render tags it wants to be appended to the active set.

Hydra prims are marked up with a render tag and only prims marked with the render tags in the current active set are Sync'ed.

Hydra's core will combine the sets from each task and deduplicate the result. So tasks don't need to co-ordinate with each other to optimize the set.

For those tasks that use HdRenderPass, this set is passed to HdRenderPass's Execute method.

The default implementation returns an empty set

Reimplemented in HdxPickTask, HdxRenderTask, and HdxShadowTask.

IsConverged()

virtual HD_API bool IsConverged ( ) const

virtual

This function returns true when a (progressive) task considers its execution results converged.

Usually this means that a progressive render delegate is finished rendering into the HdRenderBuffers used by this task. Returns true by default which is a good default for rasterizers.

Applications with data-driven task lists can determine their convergence state by determining which tasks are HdxTasks and then querying specifically those tasks for IsConverged.

Reimplemented in HdxAovInputTask, HdxColorizeSelectionTask, HdxPickFromRenderBufferTask, and HdxRenderTask.

Prepare()

virtual void Prepare ( HdTaskContext *  ctx, HdRenderIndex *  renderIndex  )

pure virtual

Prepare Phase: Resolve bindings and manage resources.

The Prepare phase happens before the Data Commit phase. All tasks in the task list get called for every execute. At this time all Tasks and other prims have completed the phase synced.

This is an opportunity for the task to pull data from other prims (such as a camera prim) by querying the render index.

The task can also use the phase to create, register and update temporary resources with the resource registry or other render delegate specific mechanism.

Tasks are always "Prepared" in execution order.

Inter-task communication is achievable via the task context. The same task context is used for the prepare and execution phases. Data in the task context isn't guaranteed to persist across calls to HdEngine::Execute().

Implemented in HdxAovInputTask, HdxBoundingBoxTask, HdxColorChannelTask, HdxColorCorrectionTask, HdxColorizeSelectionTask, HdxOitRenderTask, HdxOitResolveTask, HdxOitVolumeRenderTask, HdxPickFromRenderBufferTask, HdxPickTask, HdxPresentTask, HdxRenderSetupTask, HdxRenderTask, HdxSelectionTask, HdxShadowTask, HdxSkydomeTask, and HdxVisualizeAovTask.

Sync()

virtual void Sync ( HdSceneDelegate *  delegate, HdTaskContext *  ctx, HdDirtyBits *  dirtyBits  )

pure virtual

Sync Phase: Obtain task state from Scene delegate based on change processing.

This function might only be called if dirtyBits is not 0, so isn't guaranteed to be called every time HdEngine::Execute() is run with this task.

However, this is the only time when the task should communicate with with the scene delegate responsible for the task and should be used to pull all changed data. As outside the Sync phase, the scene delegate may not have the data available.

Tasks maybe synced in parallel and out of order.

The ctx parameter is present for legacy reason and shouldn't be used once the task has moved to using the 3-phase mechanism.

After a task has been synced, it is expected that it produces a collection identifying the prims that are important to the task. This collection is used to filter the prims in the scene so only the Relevant prims get synced.

Note about inter-prim dependencies: Quite often tasks need to access other prims, such as a camera prim for example. These other prims have not been synced yet when sync is called. Therefore, it is not recommended to access these prims during the sync phase. Instead a task should store the path to the prim to be resolved to an actual prim during the "prepare" phase.

Implemented in HdxOitResolveTask, HdxPickTask, HdxRenderSetupTask, HdxSelectionTask, HdxShadowTask, and HdxTask.

---

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

• pxr/imaging/hd/task.h