UsdImagingGLEngine Class Reference

The UsdImagingGLEngine is the main entry point API for rendering USD scenes. More...

Public Member Functions
Construction
USDIMAGINGGL_API	UsdImagingGLEngine (const HdDriver &driver=HdDriver())
	A HdDriver, containing the Hgi of your choice, can be optionally passed in during construction. More...
USDIMAGINGGL_API	UsdImagingGLEngine (const SdfPath &rootPath, const SdfPathVector &excludedPaths, const SdfPathVector &invisedPaths=SdfPathVector(), const SdfPath &sceneDelegateID=SdfPath::AbsoluteRootPath(), const HdDriver &driver=HdDriver())
	UsdImagingGLEngine (const UsdImagingGLEngine &)=delete
UsdImagingGLEngine &	operator= (const UsdImagingGLEngine &)=delete
USDIMAGINGGL_API	~UsdImagingGLEngine ()
Rendering
USDIMAGINGGL_API void	PrepareBatch (const UsdPrim &root, const UsdImagingGLRenderParams &params)
	Support for batched drawing. More...
USDIMAGINGGL_API void	RenderBatch (const SdfPathVector &paths, const UsdImagingGLRenderParams &params)
USDIMAGINGGL_API void	Render (const UsdPrim &root, const UsdImagingGLRenderParams &params)
	Entry point for kicking off a render. More...
USDIMAGINGGL_API bool	IsConverged () const
	Returns true if the resulting image is fully converged. More...
Root Transform and Visibility
USDIMAGINGGL_API void	SetRootTransform (GfMatrix4d const &xf)
	Sets the root transform. More...
USDIMAGINGGL_API void	SetRootVisibility (bool isVisible)
	Sets the root visibility. More...
Camera State
USDIMAGINGGL_API void	SetCameraPath (SdfPath const &id)
	Scene camera API Set the scene camera path to use for rendering. More...
USDIMAGINGGL_API void	SetFraming (CameraUtilFraming const &framing)
	Determines how the filmback of the camera is mapped into the pixels of the render buffer and what pixels of the render buffer will be rendered into. More...
USDIMAGINGGL_API void	SetOverrideWindowPolicy (const std::pair< bool, CameraUtilConformWindowPolicy > &policy)
	Specifies whether to force a window policy when conforming the frustum of the camera to match the display window of the camera framing. More...
USDIMAGINGGL_API void	SetRenderBufferSize (GfVec2i const &size)
	Set the size of the render buffers baking the AOVs. More...
USDIMAGINGGL_API void	SetRenderViewport (GfVec4d const &viewport)
	Set the viewport to use for rendering as (x,y,w,h), where (x,y) represents the lower left corner of the viewport rectangle, and (w,h) is the width and height of the viewport in pixels. More...
USDIMAGINGGL_API void	SetWindowPolicy (CameraUtilConformWindowPolicy policy)
	Set the window policy to use. More...
USDIMAGINGGL_API void	SetCameraState (const GfMatrix4d &viewMatrix, const GfMatrix4d &projectionMatrix)
	Free camera API Set camera framing state directly (without pointing to a camera on the USD stage). More...
USDIMAGINGGL_API void	SetCameraStateFromOpenGL ()
	Helper function to extract camera and viewport state from opengl and then call SetCameraState and SetRenderViewport. More...
Light State
USDIMAGINGGL_API void	SetLightingStateFromOpenGL ()
	Helper function to extract lighting state from opengl and then call SetLights. More...
USDIMAGINGGL_API void	SetLightingState (GlfSimpleLightingContextPtr const &src)
	Copy lighting state from another lighting context. More...
USDIMAGINGGL_API void	SetLightingState (GlfSimpleLightVector const &lights, GlfSimpleMaterial const &material, GfVec4f const &sceneAmbient)
	Set lighting state Derived classes should ensure that passing an empty lights vector disables lighting. More...
Selection Highlighting
USDIMAGINGGL_API void	SetSelected (SdfPathVector const &paths)
	Sets (replaces) the list of prim paths that should be included in selection highlighting. More...
USDIMAGINGGL_API void	ClearSelected ()
	Clear the list of prim paths that should be included in selection highlighting. More...
USDIMAGINGGL_API void	AddSelected (SdfPath const &path, int instanceIndex)
	Add a path with instanceIndex to the list of prim paths that should be included in selection highlighting. More...
USDIMAGINGGL_API void	SetSelectionColor (GfVec4f const &color)
	Sets the selection highlighting color. More...
Picking
USDIMAGINGGL_API bool	TestIntersection (const GfMatrix4d &viewMatrix, const GfMatrix4d &projectionMatrix, const UsdPrim &root, const UsdImagingGLRenderParams &params, GfVec3d *outHitPoint, GfVec3d *outHitNormal, SdfPath *outHitPrimPath=NULL, SdfPath *outHitInstancerPath=NULL, int *outHitInstanceIndex=NULL, HdInstancerContext *outInstancerContext=NULL)
	Finds closest point of intersection with a frustum by rendering. More...
USDIMAGINGGL_API bool	DecodeIntersection (unsigned char const primIdColor[4], unsigned char const instanceIdColor[4], SdfPath *outHitPrimPath=NULL, SdfPath *outHitInstancerPath=NULL, int *outHitInstanceIndex=NULL, HdInstancerContext *outInstancerContext=NULL)
	Decodes a pick result given hydra prim ID/instance ID (like you'd get from an ID render). More...
AOVs and Renderer Settings
USDIMAGINGGL_API TfTokenVector	GetRendererAovs () const
	Return the vector of available renderer AOV settings. More...
USDIMAGINGGL_API bool	SetRendererAov (TfToken const &id)
	Set the current renderer AOV to id. More...
USDIMAGINGGL_API HgiTextureHandle	GetAovTexture (TfToken const &name) const
	Returns an AOV texture handle for the given token. More...
USDIMAGINGGL_API UsdImagingGLRendererSettingsList	GetRendererSettingsList () const
	Returns the list of renderer settings. More...
USDIMAGINGGL_API VtValue	GetRendererSetting (TfToken const &id) const
	Gets a renderer setting's current value. More...
USDIMAGINGGL_API void	SetRendererSetting (TfToken const &id, VtValue const &value)
	Sets a renderer setting's value. More...
USDIMAGINGGL_API void	SetEnablePresentation (bool enabled)
	Enable / disable presenting the render to bound framebuffer. More...
USDIMAGINGGL_API void	SetPresentationOutput (TfToken const &api, VtValue const &framebuffer)
	The destination API (e.g., OpenGL, see hgiInterop for details) and framebuffer that the AOVs are presented into. More...
Renderer Command API
USDIMAGINGGL_API HdCommandDescriptors	GetRendererCommandDescriptors () const
	Return command deescriptors for commands supported by the active render delegate. More...
USDIMAGINGGL_API bool	InvokeRendererCommand (const TfToken &command, const HdCommandArgs &args=HdCommandArgs()) const
	Invokes command on the active render delegate. More...
Control of background rendering threads.
USDIMAGINGGL_API bool	IsPauseRendererSupported () const
	Query the renderer as to whether it supports pausing and resuming. More...
USDIMAGINGGL_API bool	PauseRenderer ()
	Pause the renderer. More...
USDIMAGINGGL_API bool	ResumeRenderer ()
	Resume the renderer. More...
USDIMAGINGGL_API bool	IsStopRendererSupported () const
	Query the renderer as to whether it supports stopping and restarting. More...
USDIMAGINGGL_API bool	StopRenderer ()
	Stop the renderer. More...
USDIMAGINGGL_API bool	RestartRenderer ()
	Restart the renderer. More...
Color Correction
USDIMAGINGGL_API void	SetColorCorrectionSettings (TfToken const &id)
	Set id to one of the HdxColorCorrectionTokens. More...
Render Statistics
USDIMAGINGGL_API VtDictionary	GetRenderStats () const
	Returns render statistics. More...
HGI
USDIMAGINGGL_API Hgi *	GetHgi ()
	Returns the HGI interface. More...

Static Public Member Functions
static USDIMAGINGGL_API bool	IsColorCorrectionCapable ()
	Returns true if the platform is color correction capable. More...
Global State
static USDIMAGINGGL_API bool	IsHydraEnabled ()
	Returns true if Hydra is enabled for GL drawing. More...

Protected Member Functions
USDIMAGINGGL_API HdRenderIndex *	_GetRenderIndex () const
	Returns the render index of the engine, if any. More...
USDIMAGINGGL_API void	_Execute (const UsdImagingGLRenderParams &params, HdTaskSharedPtrVector tasks)
USDIMAGINGGL_API bool	_CanPrepare (const UsdPrim &root)
USDIMAGINGGL_API void	_PreSetTime (const UsdImagingGLRenderParams &params)
USDIMAGINGGL_API void	_PostSetTime (const UsdImagingGLRenderParams &params)
USDIMAGINGGL_API void	_PrepareRender (const UsdImagingGLRenderParams &params)
USDIMAGINGGL_API void	_InitializeHgiIfNecessary ()
USDIMAGINGGL_API void	_SetRenderDelegateAndRestoreState (HdPluginRenderDelegateUniqueHandle &&)
USDIMAGINGGL_API void	_SetRenderDelegate (HdPluginRenderDelegateUniqueHandle &&)
USDIMAGINGGL_API SdfPath	_ComputeControllerPath (const HdPluginRenderDelegateUniqueHandle &)
USDIMAGINGGL_API UsdImagingDelegate *	_GetSceneDelegate () const
USDIMAGINGGL_API HdEngine *	_GetHdEngine ()
USDIMAGINGGL_API HdxTaskController *	_GetTaskController () const
USDIMAGINGGL_API bool	_IsUsingLegacyImpl () const
USDIMAGINGGL_API HdSelectionSharedPtr	_GetSelection () const

Static Protected Member Functions
static USDIMAGINGGL_API bool	_UpdateHydraCollection (HdRprimCollection *collection, SdfPathVector const &roots, UsdImagingGLRenderParams const &params)
static USDIMAGINGGL_API HdxRenderTaskParams	_MakeHydraUsdImagingGLRenderParams (UsdImagingGLRenderParams const &params)
static USDIMAGINGGL_API void	_ComputeRenderTags (UsdImagingGLRenderParams const &params, TfTokenVector *renderTags)
static USDIMAGINGGL_API TfToken	_GetDefaultRendererPluginId ()

Protected Attributes
HgiUniquePtr	_hgi
HdDriver	_hgiDriver
VtValue	_userFramebuffer
HdPluginRenderDelegateUniqueHandle	_renderDelegate
std::unique_ptr< HdRenderIndex >	_renderIndex
SdfPath const	_sceneDelegateId
std::unique_ptr < HdxTaskController >	_taskController
HdxSelectionTrackerSharedPtr	_selTracker
HdRprimCollection	_renderCollection
HdRprimCollection	_intersectCollection
GlfSimpleLightingContextRefPtr	_lightingContextForOpenGLState
GfVec4f	_selectionColor
SdfPath	_rootPath
SdfPathVector	_excludedPrimPaths
SdfPathVector	_invisedPrimPaths
bool	_isPopulated
std::unique_ptr < UsdImagingGLLegacyEngine >	_legacyImpl

Renderer Plugin Management
static USDIMAGINGGL_API TfTokenVector	GetRendererPlugins ()
	Return the vector of available render-graph delegate plugins. More...
static USDIMAGINGGL_API std::string	GetRendererDisplayName (TfToken const &id)
	Return the user-friendly description of a renderer plugin. More...
USDIMAGINGGL_API TfToken	GetCurrentRendererId () const
	Return the id of the currently used renderer plugin. More...
USDIMAGINGGL_API bool	SetRendererPlugin (TfToken const &id)
	Set the current render-graph delegate to id. More...

Detailed Description

The UsdImagingGLEngine is the main entry point API for rendering USD scenes.

Definition at line 82 of file engine.h.

Constructor & Destructor Documentation

USDIMAGINGGL_API UsdImagingGLEngine

(

const HdDriver &

driver = HdDriver()

)

A HdDriver, containing the Hgi of your choice, can be optionally passed in during construction.

This can be helpful if you application creates multiple UsdImagingGLEngine that wish to use the same HdDriver / Hgi.

Member Function Documentation

USDIMAGINGGL_API HdRenderIndex* _GetRenderIndex ( ) const

protected

Returns the render index of the engine, if any.

This is only used for whitebox testing.

USDIMAGINGGL_API void AddSelected	(	SdfPath const &	path,
		int	instanceIndex
	)

Add a path with instanceIndex to the list of prim paths that should be included in selection highlighting.

UsdImagingDelegate::ALL_INSTANCES can be used for highlighting all instances if path is an instancer.

USDIMAGINGGL_API void ClearSelected

(

)

Clear the list of prim paths that should be included in selection highlighting.

USDIMAGINGGL_API bool DecodeIntersection	(	unsigned char const	primIdColor[4],
		unsigned char const	instanceIdColor[4],
		SdfPath *	outHitPrimPath = NULL,
		SdfPath *	outHitInstancerPath = NULL,
		int *	outHitInstanceIndex = NULL,
		HdInstancerContext *	outInstancerContext = NULL
	)

Decodes a pick result given hydra prim ID/instance ID (like you'd get from an ID render).

USDIMAGINGGL_API HgiTextureHandle GetAovTexture

(

TfToken const &

name

)

const

Returns an AOV texture handle for the given token.

USDIMAGINGGL_API TfToken GetCurrentRendererId

(

)

const

Return the id of the currently used renderer plugin.

USDIMAGINGGL_API Hgi* GetHgi

(

)

Returns the HGI interface.

USDIMAGINGGL_API TfTokenVector GetRendererAovs

(

)

const

Return the vector of available renderer AOV settings.

USDIMAGINGGL_API HdCommandDescriptors GetRendererCommandDescriptors

(

)

const

Return command deescriptors for commands supported by the active render delegate.

static USDIMAGINGGL_API std::string GetRendererDisplayName ( TfToken const &  id )

static

Return the user-friendly description of a renderer plugin.

static USDIMAGINGGL_API TfTokenVector GetRendererPlugins ( )

static

Return the vector of available render-graph delegate plugins.

USDIMAGINGGL_API VtValue GetRendererSetting

(

TfToken const &

id

)

const

Gets a renderer setting's current value.

USDIMAGINGGL_API UsdImagingGLRendererSettingsList GetRendererSettingsList

(

)

const

Returns the list of renderer settings.

USDIMAGINGGL_API VtDictionary GetRenderStats

(

)

const

Returns render statistics.

The contents of the dictionary will depend on the current render delegate.

USDIMAGINGGL_API bool InvokeRendererCommand	(	const TfToken &	command,
		const HdCommandArgs &	args = HdCommandArgs()
	)		const

Invokes command on the active render delegate.

If successful, returns true, returns false otherwise. Note that the command will not succeeed if it is not among those returned by GetRendererCommandDescriptors() for the same active render delegate.

static USDIMAGINGGL_API bool IsColorCorrectionCapable ( )

static

Returns true if the platform is color correction capable.

USDIMAGINGGL_API bool IsConverged

(

)

const

Returns true if the resulting image is fully converged.

(otherwise, caller may need to call Render() again to refine the result)

static USDIMAGINGGL_API bool IsHydraEnabled ( )

static

Returns true if Hydra is enabled for GL drawing.

USDIMAGINGGL_API bool IsPauseRendererSupported

(

)

const

Query the renderer as to whether it supports pausing and resuming.

USDIMAGINGGL_API bool IsStopRendererSupported

(

)

const

Query the renderer as to whether it supports stopping and restarting.

USDIMAGINGGL_API bool PauseRenderer

(

)

Pause the renderer.

Returns true if successful.

USDIMAGINGGL_API void PrepareBatch	(	const UsdPrim &	root,
		const UsdImagingGLRenderParams &	params
	)

Support for batched drawing.

USDIMAGINGGL_API void Render	(	const UsdPrim &	root,
		const UsdImagingGLRenderParams &	params
	)

Entry point for kicking off a render.

USDIMAGINGGL_API bool RestartRenderer

(

)

Restart the renderer.

Returns true if successful.

USDIMAGINGGL_API bool ResumeRenderer

(

)

Resume the renderer.

Returns true if successful.

USDIMAGINGGL_API void SetCameraPath

(

SdfPath const &

id

)

Scene camera API Set the scene camera path to use for rendering.

USDIMAGINGGL_API void SetCameraState	(	const GfMatrix4d &	viewMatrix,
		const GfMatrix4d &	projectionMatrix
	)

Free camera API Set camera framing state directly (without pointing to a camera on the USD stage).

The projection matrix is expected to be pre-adjusted for the window policy.

USDIMAGINGGL_API void SetCameraStateFromOpenGL

(

)

Helper function to extract camera and viewport state from opengl and then call SetCameraState and SetRenderViewport.

USDIMAGINGGL_API void SetColorCorrectionSettings

(

TfToken const &

id

)

Set id to one of the HdxColorCorrectionTokens.

USDIMAGINGGL_API void SetEnablePresentation

(

bool

enabled

)

Enable / disable presenting the render to bound framebuffer.

An application may choose to manage the AOVs that are rendered into itself and skip the engine's presentation.

USDIMAGINGGL_API void SetFraming

(

CameraUtilFraming const &

framing

)

Determines how the filmback of the camera is mapped into the pixels of the render buffer and what pixels of the render buffer will be rendered into.

USDIMAGINGGL_API void SetLightingState

(

GlfSimpleLightingContextPtr const &

src

)

Copy lighting state from another lighting context.

USDIMAGINGGL_API void SetLightingState	(	GlfSimpleLightVector const &	lights,
		GlfSimpleMaterial const &	material,
		GfVec4f const &	sceneAmbient
	)

Set lighting state Derived classes should ensure that passing an empty lights vector disables lighting.

Parameters

lights

is the set of lights to use, or empty to disable lighting.

USDIMAGINGGL_API void SetLightingStateFromOpenGL

(

)

Helper function to extract lighting state from opengl and then call SetLights.

USDIMAGINGGL_API void SetOverrideWindowPolicy

(

const std::pair< bool, CameraUtilConformWindowPolicy > &

policy

)

Specifies whether to force a window policy when conforming the frustum of the camera to match the display window of the camera framing.

If set to {false, ...}, the window policy of the specified camera will be used.

Note: std::pair<bool, ...> is used instead of std::optional<...> because the latter is only available in C++17 or later.

USDIMAGINGGL_API void SetPresentationOutput	(	TfToken const &	api,
		VtValue const &	framebuffer
	)

The destination API (e.g., OpenGL, see hgiInterop for details) and framebuffer that the AOVs are presented into.

The framebuffer is a VtValue that encoding a framebuffer in a destination API specific way. E.g., a uint32_t (aka GLuint) for framebuffer object for OpenGL.

USDIMAGINGGL_API void SetRenderBufferSize

(

GfVec2i const &

size

)

Set the size of the render buffers baking the AOVs.

GUI applications should set this to the size of the window.

USDIMAGINGGL_API bool SetRendererAov

(

TfToken const &

id

)

Set the current renderer AOV to id.

USDIMAGINGGL_API bool SetRendererPlugin

(

TfToken const &

id

)

Set the current render-graph delegate to id.

the plugin will be loaded if it's not yet.

USDIMAGINGGL_API void SetRendererSetting	(	TfToken const &	id,
		VtValue const &	value
	)

Sets a renderer setting's value.

USDIMAGINGGL_API void SetRenderViewport

(

GfVec4d const &

viewport

)

Set the viewport to use for rendering as (x,y,w,h), where (x,y) represents the lower left corner of the viewport rectangle, and (w,h) is the width and height of the viewport in pixels.

Deprecated:

Use SetFraming and SetRenderBufferSize instead.

USDIMAGINGGL_API void SetRootTransform

(

GfMatrix4d const &

xf

)

Sets the root transform.

USDIMAGINGGL_API void SetRootVisibility

(

bool

isVisible

)

Sets the root visibility.

USDIMAGINGGL_API void SetSelected

(

SdfPathVector const &

paths

)

Sets (replaces) the list of prim paths that should be included in selection highlighting.

These paths may include root paths which will be expanded internally.

USDIMAGINGGL_API void SetSelectionColor

(

GfVec4f const &

color

)

Sets the selection highlighting color.

USDIMAGINGGL_API void SetWindowPolicy

(

CameraUtilConformWindowPolicy

policy

)

Set the window policy to use.

XXX: This is currently used for scene cameras set via SetCameraPath. See comment in SetCameraState for the free cam.

USDIMAGINGGL_API bool StopRenderer

(

)

Stop the renderer.

Returns true if successful.

USDIMAGINGGL_API bool TestIntersection	(	const GfMatrix4d &	viewMatrix,
		const GfMatrix4d &	projectionMatrix,
		const UsdPrim &	root,
		const UsdImagingGLRenderParams &	params,
		GfVec3d *	outHitPoint,
		GfVec3d *	outHitNormal,
		SdfPath *	outHitPrimPath = NULL,
		SdfPath *	outHitInstancerPath = NULL,
		int *	outHitInstanceIndex = NULL,
		HdInstancerContext *	outInstancerContext = NULL
	)

Finds closest point of intersection with a frustum by rendering.

This method uses a PickRender and a customized depth buffer to find an approximate point of intersection by rendering. This is less accurate than implicit methods or rendering with GL_SELECT, but leverages any data already cached in the renderer.

Returns whether a hit occurred and if so, outHitPoint will contain the intersection point in world space (i.e. projectionMatrix and viewMatrix factored back out of the result), and outHitNormal will contain the world space normal at that point.

outHitPrimPath will point to the gprim selected by the pick. outHitInstancerPath will point to the point instancer (if applicable) of that gprim. For nested instancing, outHitInstancerPath points to the closest instancer.

---

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

• pxr/usdImaging/usdImagingGL/engine.h