HgiGL Class Reference

OpenGL implementation of the Hydra Graphics Interface. More...

#include <hgi.h>

Inheritance diagram for HgiGL:

Public Member Functions
HGIGL_API bool	IsBackendSupported () const override
HGIGL_API HgiGraphicsCmdsUniquePtr	CreateGraphicsCmds (HgiGraphicsCmdsDesc const &desc) override
	Returns a GraphicsCmds object (for temporary use) that is ready to record draw commands.
HGIGL_API HgiBlitCmdsUniquePtr	CreateBlitCmds () override
	Returns a BlitCmds object (for temporary use) that is ready to execute resource copy commands.
HGIGL_API HgiComputeCmdsUniquePtr	CreateComputeCmds (HgiComputeCmdsDesc const &desc) override
	Returns a ComputeCmds object (for temporary use) that is ready to record dispatch commands.
HGIGL_API HgiTextureHandle	CreateTexture (HgiTextureDesc const &desc) override
	Create a texture in rendering backend.
HGIGL_API void	DestroyTexture (HgiTextureHandle *texHandle) override
	Destroy a texture in rendering backend.
HGIGL_API HgiTextureViewHandle	CreateTextureView (HgiTextureViewDesc const &desc) override
	Create a texture view in rendering backend.
HGIGL_API void	DestroyTextureView (HgiTextureViewHandle *viewHandle) override
	Destroy a texture view in rendering backend.
HGIGL_API HgiSamplerHandle	CreateSampler (HgiSamplerDesc const &desc) override
	Create a sampler in rendering backend.
HGIGL_API void	DestroySampler (HgiSamplerHandle *smpHandle) override
	Destroy a sampler in rendering backend.
HGIGL_API HgiBufferHandle	CreateBuffer (HgiBufferDesc const &desc) override
	Create a buffer in rendering backend.
HGIGL_API void	DestroyBuffer (HgiBufferHandle *bufHandle) override
	Destroy a buffer in rendering backend.
HGIGL_API HgiShaderFunctionHandle	CreateShaderFunction (HgiShaderFunctionDesc const &desc) override
	Create a new shader function.
HGIGL_API void	DestroyShaderFunction (HgiShaderFunctionHandle *shaderFunctionHandle) override
	Destroy a shader function.
HGIGL_API HgiShaderProgramHandle	CreateShaderProgram (HgiShaderProgramDesc const &desc) override
	Create a new shader program.
HGIGL_API void	DestroyShaderProgram (HgiShaderProgramHandle *shaderProgramHandle) override
	Destroy a shader program.
HGIGL_API HgiResourceBindingsHandle	CreateResourceBindings (HgiResourceBindingsDesc const &desc) override
	Create a new resource binding object.
HGIGL_API void	DestroyResourceBindings (HgiResourceBindingsHandle *resHandle) override
	Destroy a resource binding object.
HGIGL_API HgiGraphicsPipelineHandle	CreateGraphicsPipeline (HgiGraphicsPipelineDesc const &pipeDesc) override
	Create a new graphics pipeline state object.
HGIGL_API void	DestroyGraphicsPipeline (HgiGraphicsPipelineHandle *pipeHandle) override
	Destroy a graphics pipeline state object.
HGIGL_API HgiComputePipelineHandle	CreateComputePipeline (HgiComputePipelineDesc const &pipeDesc) override
	Create a new compute pipeline state object.
HGIGL_API void	DestroyComputePipeline (HgiComputePipelineHandle *pipeHandle) override
	Destroy a compute pipeline state object.
HGIGL_API TfToken const &	GetAPIName () const override
	Return the name of the api (e.g.
HGIGL_API HgiGLCapabilities const *	GetCapabilities () const override
	Returns the device-specific capabilities structure.
HGIGL_API HgiIndirectCommandEncoder *	GetIndirectCommandEncoder () const override
	Returns the device-specific indirect command buffer encoder or nullptr if not supported.
HGIGL_API void	StartFrame () override
	Optionally called by client app at the start of a new rendering frame.
HGIGL_API void	EndFrame () override
	Optionally called at the end of a rendering frame.
HGIGL_API HgiGLDevice *	GetPrimaryDevice () const
HGIGL_API HgiGLContextArenaHandle	CreateContextArena ()
HGIGL_API void	DestroyContextArena (HgiGLContextArenaHandle *arenaHandle)
	Destroy a context arena.
HGIGL_API void	SetContextArena (HgiGLContextArenaHandle const &arenaHandle)
	Set the context arena to manage container resources (currently limited to framebuffer objects) for graphics commands submitted subsequently.
Public Member Functions inherited from Hgi
HGI_API void	SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait=HgiSubmitWaitTypeNoWait)
	Submit one HgiCmds objects.
virtual HGI_API bool	IsBackendSupported () const =0
	Determine if Hgi instance can run on current hardware.
virtual HGI_API HgiGraphicsCmdsUniquePtr	CreateGraphicsCmds (HgiGraphicsCmdsDesc const &desc)=0
	Returns a GraphicsCmds object (for temporary use) that is ready to record draw commands.
virtual HGI_API HgiBlitCmdsUniquePtr	CreateBlitCmds ()=0
	Returns a BlitCmds object (for temporary use) that is ready to execute resource copy commands.
virtual HGI_API HgiComputeCmdsUniquePtr	CreateComputeCmds (HgiComputeCmdsDesc const &desc)=0
	Returns a ComputeCmds object (for temporary use) that is ready to record dispatch commands.
virtual HGI_API HgiTextureHandle	CreateTexture (HgiTextureDesc const &desc)=0
	Create a texture in rendering backend.
virtual HGI_API void	DestroyTexture (HgiTextureHandle *texHandle)=0
	Destroy a texture in rendering backend.
virtual HGI_API HgiTextureViewHandle	CreateTextureView (HgiTextureViewDesc const &desc)=0
	Create a texture view in rendering backend.
virtual HGI_API void	DestroyTextureView (HgiTextureViewHandle *viewHandle)=0
	Destroy a texture view in rendering backend.
virtual HGI_API HgiSamplerHandle	CreateSampler (HgiSamplerDesc const &desc)=0
	Create a sampler in rendering backend.
virtual HGI_API void	DestroySampler (HgiSamplerHandle *smpHandle)=0
	Destroy a sampler in rendering backend.
virtual HGI_API HgiBufferHandle	CreateBuffer (HgiBufferDesc const &desc)=0
	Create a buffer in rendering backend.
virtual HGI_API void	DestroyBuffer (HgiBufferHandle *bufHandle)=0
	Destroy a buffer in rendering backend.
virtual HGI_API HgiShaderFunctionHandle	CreateShaderFunction (HgiShaderFunctionDesc const &desc)=0
	Create a new shader function.
virtual HGI_API void	DestroyShaderFunction (HgiShaderFunctionHandle *shaderFunctionHandle)=0
	Destroy a shader function.
virtual HGI_API HgiShaderProgramHandle	CreateShaderProgram (HgiShaderProgramDesc const &desc)=0
	Create a new shader program.
virtual HGI_API void	DestroyShaderProgram (HgiShaderProgramHandle *shaderProgramHandle)=0
	Destroy a shader program.
virtual HGI_API HgiResourceBindingsHandle	CreateResourceBindings (HgiResourceBindingsDesc const &desc)=0
	Create a new resource binding object.
virtual HGI_API void	DestroyResourceBindings (HgiResourceBindingsHandle *resHandle)=0
	Destroy a resource binding object.
virtual HGI_API HgiGraphicsPipelineHandle	CreateGraphicsPipeline (HgiGraphicsPipelineDesc const &pipeDesc)=0
	Create a new graphics pipeline state object.
virtual HGI_API void	DestroyGraphicsPipeline (HgiGraphicsPipelineHandle *pipeHandle)=0
	Destroy a graphics pipeline state object.
virtual HGI_API HgiComputePipelineHandle	CreateComputePipeline (HgiComputePipelineDesc const &pipeDesc)=0
	Create a new compute pipeline state object.
virtual HGI_API void	DestroyComputePipeline (HgiComputePipelineHandle *pipeHandle)=0
	Destroy a compute pipeline state object.
virtual HGI_API TfToken const &	GetAPIName () const =0
	Return the name of the api (e.g.
virtual HGI_API HgiCapabilities const *	GetCapabilities () const =0
	Returns the device-specific capabilities structure.
virtual HGI_API HgiIndirectCommandEncoder *	GetIndirectCommandEncoder () const =0
	Returns the device-specific indirect command buffer encoder or nullptr if not supported.
virtual HGI_API void	StartFrame ()=0
	Optionally called by client app at the start of a new rendering frame.
virtual HGI_API void	EndFrame ()=0
	Optionally called at the end of a rendering frame.

Protected Member Functions
HGIGL_API bool	_SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait) override
Protected Member Functions inherited from Hgi
HGI_API uint64_t	GetUniqueId ()
virtual HGI_API bool	_SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait)

Additional Inherited Members
Static Public Member Functions inherited from Hgi
static HGI_API Hgi *	GetPlatformDefaultHgi ()
	*** DEPRECATED *** Please use: CreatePlatformDefaultHgi
static HGI_API HgiUniquePtr	CreatePlatformDefaultHgi ()
	Helper function to return a Hgi object for the current platform.
static HGI_API bool	IsSupported ()
	Constructs a temporary Hgi object for the current platform and calls the object's IsBackendSupported() function.

Detailed Description

OpenGL implementation of the Hydra Graphics Interface.

Context Management

HgiGL expects any GL context(s) to be externally managed. When HgiGL is constructed and during any of its resource create / destroy calls and during command recording operations, it expects that an OpenGL context is valid and current.

When an application uses the same HgiGL instance from multiple GL contexts, the expectations are that:

1. The application has set up sharing amongst the various GL contexts. This ensures that any non-container resources created may be shared amongst the contexts. These shared resources may be safely deleted from any context in the share group.
2. A context arena (see relevant API below) is used per GL context to manage container resources that can't be shared amongst GL contexts. Currently, HgiGL's support is limited to framebuffer objects.

In the absence of an application provided context arena, the default arena is used with the implied expectation that the same GL context is valid and current for the lifetime of the HgiGL instance.

Definition at line 71 of file hgi.h.

Member Function Documentation

_SubmitCmds()

HGIGL_API bool _SubmitCmds ( HgiCmds *  cmds, HgiSubmitWaitType  wait  )

overrideprotectedvirtual

Reimplemented from Hgi.

CreateBlitCmds()

HGIGL_API HgiBlitCmdsUniquePtr CreateBlitCmds ( )

overridevirtual

Returns a BlitCmds object (for temporary use) that is ready to execute resource copy commands.

BlitCmds is a lightweight object that should be re-acquired each frame (don't hold onto it after EndEncoding). Thread safety: Each Hgi backend must ensure that a Cmds object can be created on the main thread, recorded into (exclusively) by one secondary thread and be submitted on the main thread. See notes above.

Implements Hgi.

CreateBuffer()

HGIGL_API HgiBufferHandle CreateBuffer ( HgiBufferDesc const &  desc )

overridevirtual

Create a buffer in rendering backend.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateComputeCmds()

HGIGL_API HgiComputeCmdsUniquePtr CreateComputeCmds ( HgiComputeCmdsDesc const &  desc )

overridevirtual

Returns a ComputeCmds object (for temporary use) that is ready to record dispatch commands.

ComputeCmds is a lightweight object that should be re-acquired each frame (don't hold onto it after EndEncoding). Thread safety: Each Hgi backend must ensure that a Cmds object can be created on the main thread, recorded into (exclusively) by one secondary thread and be submitted on the main thread. See notes above.

Implements Hgi.

CreateComputePipeline()

HGIGL_API HgiComputePipelineHandle CreateComputePipeline ( HgiComputePipelineDesc const &  pipeDesc )

overridevirtual

Create a new compute pipeline state object.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateContextArena()

HGIGL_API HgiGLContextArenaHandle CreateContextArena

(

)

---

Context arena API Please refer to "GL Context Management" for usage expectations.

Creates and return a context arena object handle.

CreateGraphicsCmds()

HGIGL_API HgiGraphicsCmdsUniquePtr CreateGraphicsCmds ( HgiGraphicsCmdsDesc const &  desc )

overridevirtual

Returns a GraphicsCmds object (for temporary use) that is ready to record draw commands.

GraphicsCmds is a lightweight object that should be re-acquired each frame (don't hold onto it after EndEncoding). Thread safety: Each Hgi backend must ensure that a Cmds object can be created on the main thread, recorded into (exclusively) by one secondary thread and be submitted on the main thread. See notes above.

Implements Hgi.

CreateGraphicsPipeline()

HGIGL_API HgiGraphicsPipelineHandle CreateGraphicsPipeline ( HgiGraphicsPipelineDesc const &  pipeDesc )

overridevirtual

Create a new graphics pipeline state object.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateResourceBindings()

HGIGL_API HgiResourceBindingsHandle CreateResourceBindings ( HgiResourceBindingsDesc const &  desc )

overridevirtual

Create a new resource binding object.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateSampler()

HGIGL_API HgiSamplerHandle CreateSampler ( HgiSamplerDesc const &  desc )

overridevirtual

Create a sampler in rendering backend.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateShaderFunction()

HGIGL_API HgiShaderFunctionHandle CreateShaderFunction ( HgiShaderFunctionDesc const &  desc )

overridevirtual

Create a new shader function.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateShaderProgram()

HGIGL_API HgiShaderProgramHandle CreateShaderProgram ( HgiShaderProgramDesc const &  desc )

overridevirtual

Create a new shader program.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateTexture()

HGIGL_API HgiTextureHandle CreateTexture ( HgiTextureDesc const &  desc )

overridevirtual

Create a texture in rendering backend.

Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

CreateTextureView()

HGIGL_API HgiTextureViewHandle CreateTextureView ( HgiTextureViewDesc const &  desc )

overridevirtual

Create a texture view in rendering backend.

A texture view aliases another texture's data. It is the responsibility of the client to ensure that the sourceTexture is not destroyed while the texture view is in use. Thread safety: Creation must happen on main thread. See notes above.

Implements Hgi.

DestroyBuffer()

HGIGL_API void DestroyBuffer ( HgiBufferHandle *  bufHandle )

overridevirtual

Destroy a buffer in rendering backend.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyComputePipeline()

HGIGL_API void DestroyComputePipeline ( HgiComputePipelineHandle *  pipeHandle )

overridevirtual

Destroy a compute pipeline state object.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyContextArena()

HGIGL_API void DestroyContextArena

(

HgiGLContextArenaHandle *

arenaHandle

)

Destroy a context arena.

Note: The context arena must be unset (by calling SetContextArena with an empty handle) prior to destruction.

DestroyGraphicsPipeline()

HGIGL_API void DestroyGraphicsPipeline ( HgiGraphicsPipelineHandle *  pipeHandle )

overridevirtual

Destroy a graphics pipeline state object.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyResourceBindings()

HGIGL_API void DestroyResourceBindings ( HgiResourceBindingsHandle *  resHandle )

overridevirtual

Destroy a resource binding object.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroySampler()

HGIGL_API void DestroySampler ( HgiSamplerHandle *  smpHandle )

overridevirtual

Destroy a sampler in rendering backend.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyShaderFunction()

HGIGL_API void DestroyShaderFunction ( HgiShaderFunctionHandle *  shaderFunctionHandle )

overridevirtual

Destroy a shader function.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyShaderProgram()

HGIGL_API void DestroyShaderProgram ( HgiShaderProgramHandle *  shaderProgramHandle )

overridevirtual

Destroy a shader program.

Note that this does NOT automatically destroy the shader functions in the program since shader functions may be used by more than one program. Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyTexture()

HGIGL_API void DestroyTexture ( HgiTextureHandle *  texHandle )

overridevirtual

Destroy a texture in rendering backend.

Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

DestroyTextureView()

HGIGL_API void DestroyTextureView ( HgiTextureViewHandle *  viewHandle )

overridevirtual

Destroy a texture view in rendering backend.

This will destroy the view's texture, but not the sourceTexture that was aliased by the view. The sourceTexture data remains unchanged. Thread safety: Destruction must happen on main thread. See notes above.

Implements Hgi.

EndFrame()

HGIGL_API void EndFrame ( )

overridevirtual

Optionally called at the end of a rendering frame.

Please read the comments in StartFrame. Thread safety: Not thread safe. Should be called on the main thread.

Implements Hgi.

GetAPIName()

HGIGL_API TfToken const & GetAPIName ( ) const

overridevirtual

Return the name of the api (e.g.

"OpenGL"). Thread safety: This call is thread safe.

Implements Hgi.

GetCapabilities()

HGIGL_API HgiGLCapabilities const * GetCapabilities ( ) const

overridevirtual

Returns the device-specific capabilities structure.

Thread safety: This call is thread safe.

Implements Hgi.

GetIndirectCommandEncoder()

HGIGL_API HgiIndirectCommandEncoder * GetIndirectCommandEncoder ( ) const

overridevirtual

Returns the device-specific indirect command buffer encoder or nullptr if not supported.

Thread safety: This call is thread safe.

Implements Hgi.

GetPrimaryDevice()

HGIGL_API HgiGLDevice * GetPrimaryDevice

(

)

const

---

---

IsBackendSupported()

HGIGL_API bool IsBackendSupported ( ) const

overridevirtual

---

Virtual API

Implements Hgi.

SetContextArena()

HGIGL_API void SetContextArena

(

HgiGLContextArenaHandle const &

arenaHandle

)

Set the context arena to manage container resources (currently limited to framebuffer objects) for graphics commands submitted subsequently.

StartFrame()

HGIGL_API void StartFrame ( )

overridevirtual

Optionally called by client app at the start of a new rendering frame.

We can't rely on StartFrame for anything important, because it is up to the external client to (optionally) call this and they may never do. Hydra doesn't have a clearly defined start or end frame. This can be helpful to insert GPU frame debug markers. Thread safety: Not thread safe. Should be called on the main thread.

Implements Hgi.

---

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

• pxr/imaging/hgiGL/hgi.h