#include <hgi.h>

Inheritance diagram for Hgi:

Public Member Functions
HGI_API	Hgi ()

virtual HGI_API	~Hgi ()

HGI_API void	SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait=HgiSubmitWaitTypeNoWait)

virtual HGI_API bool	IsBackendSupported () const =0

virtual HGI_API HgiGraphicsCmdsUniquePtr	CreateGraphicsCmds (HgiGraphicsCmdsDesc const &desc)=0

virtual HGI_API HgiBlitCmdsUniquePtr	CreateBlitCmds ()=0

virtual HGI_API HgiComputeCmdsUniquePtr	CreateComputeCmds (HgiComputeCmdsDesc const &desc)=0

virtual HGI_API HgiTextureHandle	CreateTexture (HgiTextureDesc const &desc)=0

virtual HGI_API void	DestroyTexture (HgiTextureHandle *texHandle)=0

virtual HGI_API HgiTextureViewHandle	CreateTextureView (HgiTextureViewDesc const &desc)=0

virtual HGI_API void	DestroyTextureView (HgiTextureViewHandle *viewHandle)=0

virtual HGI_API HgiSamplerHandle	CreateSampler (HgiSamplerDesc const &desc)=0

virtual HGI_API void	DestroySampler (HgiSamplerHandle *smpHandle)=0

virtual HGI_API HgiBufferHandle	CreateBuffer (HgiBufferDesc const &desc)=0

virtual HGI_API void	DestroyBuffer (HgiBufferHandle *bufHandle)=0

virtual HGI_API HgiShaderFunctionHandle	CreateShaderFunction (HgiShaderFunctionDesc const &desc)=0

virtual HGI_API void	DestroyShaderFunction (HgiShaderFunctionHandle *shaderFunctionHandle)=0

virtual HGI_API HgiShaderProgramHandle	CreateShaderProgram (HgiShaderProgramDesc const &desc)=0

virtual HGI_API void	DestroyShaderProgram (HgiShaderProgramHandle *shaderProgramHandle)=0

virtual HGI_API HgiResourceBindingsHandle	CreateResourceBindings (HgiResourceBindingsDesc const &desc)=0

virtual HGI_API void	DestroyResourceBindings (HgiResourceBindingsHandle *resHandle)=0

virtual HGI_API HgiGraphicsPipelineHandle	CreateGraphicsPipeline (HgiGraphicsPipelineDesc const &pipeDesc)=0

virtual HGI_API void	DestroyGraphicsPipeline (HgiGraphicsPipelineHandle *pipeHandle)=0

virtual HGI_API HgiComputePipelineHandle	CreateComputePipeline (HgiComputePipelineDesc const &pipeDesc)=0

virtual HGI_API void	DestroyComputePipeline (HgiComputePipelineHandle *pipeHandle)=0

virtual HGI_API TfToken const &	GetAPIName () const =0

virtual HGI_API HgiCapabilities const *	GetCapabilities () const =0

virtual HGI_API HgiIndirectCommandEncoder *	GetIndirectCommandEncoder () const =0

virtual HGI_API void	StartFrame ()=0

virtual HGI_API void	EndFrame ()=0

Static Public Member Functions
static HGI_API Hgi *	GetPlatformDefaultHgi ()
	* DEPRECATED * Please use: CreatePlatformDefaultHgi More...

static HGI_API HgiUniquePtr	CreatePlatformDefaultHgi ()

static HGI_API bool	IsSupported ()

Protected Member Functions
HGI_API uint64_t	GetUniqueId ()

virtual HGI_API bool	_SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait)

Detailed Description

Hydra Graphics Interface. Hgi is used to communicate with one or more physical gpu devices.

Hgi provides API to create/destroy resources that a gpu device owns. The lifetime of resources is not managed by Hgi, so it is up to the caller to destroy resources and ensure those resources are no longer used.

Commands are recorded in 'HgiCmds' objects and submitted via Hgi.

Thread-safety:

Modern graphics APIs like Metal and Vulkan are designed with multi-threading in mind. We want to try and take advantage of this where possible. However we also wish to continue to support OpenGL for the time being.

In an application where OpenGL is involved, when we say "main thread" we mean the thread on which the gl-context is bound.

Each Hgi backend should at minimum support the following:

Single threaded Hgi::SubmitCmds on main thread.
Single threaded Hgi::Resource Create*** / Destroy*** on main thread.
Multi threaded recording of commands in Hgi***Cmds objects.
A Hgi***Cmds object should be creatable on the main thread, recorded into with one secondary thread (only one thread may use a Cmds object) and submitted via the main thread.

Each Hgi backend is additionally encouraged to support:

Multi threaded support for resource creation and destruction.

We currently do not rely on these additional multi-threading features in Hydra / Storm where we still wish to run OpenGL. In Hydra we make sure to use the main-thread for resource creation and command submission. One day we may wish to switch this to be multi-threaded so new Hgi backends are encouraged to support it.

Pseudo code what should minimally be supported:

vector<HgiGraphicsCmds> cmds

for num_threads
    cmds.push_back( Hgi->CreateGraphicsCmds() )

parallel_for i to num_threads
    cmds[i]->SetViewport()
    cmds[i]->Draw()

for i to num_threads
    hgi->SubmitCmds( cmds[i] )

Definition at line 110 of file hgi.h.

Constructor & Destructor Documentation

HGI_API Hgi::Hgi ( )

virtual HGI_API Hgi::~Hgi ( )

virtual

Member Function Documentation

virtual HGI_API bool Hgi::_SubmitCmds	(	HgiCmds *	cmds,
		HgiSubmitWaitType	wait
	)

protectedvirtual

Reimplemented in HgiGL.

virtual HGI_API HgiBlitCmdsUniquePtr Hgi::CreateBlitCmds ( )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API HgiBufferHandle Hgi::CreateBuffer ( HgiBufferDesc const & desc )

pure virtual

Create a buffer in rendering backend. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiComputeCmdsUniquePtr Hgi::CreateComputeCmds ( HgiComputeCmdsDesc const & desc )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API HgiComputePipelineHandle Hgi::CreateComputePipeline ( HgiComputePipelineDesc const & pipeDesc )

pure virtual

Create a new compute pipeline state object. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiGraphicsCmdsUniquePtr Hgi::CreateGraphicsCmds ( HgiGraphicsCmdsDesc const & desc )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API HgiGraphicsPipelineHandle Hgi::CreateGraphicsPipeline ( HgiGraphicsPipelineDesc const & pipeDesc )

pure virtual

Create a new graphics pipeline state object. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

static HGI_API HgiUniquePtr Hgi::CreatePlatformDefaultHgi ( )

static

Helper function to return a Hgi object for the current platform. For example on Linux this may return HgiGL while on macOS HgiMetal. Caller, usually the application, owns the lifetime of the Hgi object and the object is destroyed when the caller drops the unique ptr. Thread safety: Not thread safe.

virtual HGI_API HgiResourceBindingsHandle Hgi::CreateResourceBindings ( HgiResourceBindingsDesc const & desc )

pure virtual

Create a new resource binding object. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiSamplerHandle Hgi::CreateSampler ( HgiSamplerDesc const & desc )

pure virtual

Create a sampler in rendering backend. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiShaderFunctionHandle Hgi::CreateShaderFunction ( HgiShaderFunctionDesc const & desc )

pure virtual

Create a new shader function. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiShaderProgramHandle Hgi::CreateShaderProgram ( HgiShaderProgramDesc const & desc )

pure virtual

Create a new shader program. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiTextureHandle Hgi::CreateTexture ( HgiTextureDesc const & desc )

pure virtual

Create a texture in rendering backend. Thread safety: Creation must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API HgiTextureViewHandle Hgi::CreateTextureView ( HgiTextureViewDesc const & desc )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyBuffer ( HgiBufferHandle * bufHandle )

pure virtual

Destroy a buffer in rendering backend. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyComputePipeline ( HgiComputePipelineHandle * pipeHandle )

pure virtual

Destroy a compute pipeline state object. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyGraphicsPipeline ( HgiGraphicsPipelineHandle * pipeHandle )

pure virtual

Destroy a graphics pipeline state object. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyResourceBindings ( HgiResourceBindingsHandle * resHandle )

pure virtual

Destroy a resource binding object. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroySampler ( HgiSamplerHandle * smpHandle )

pure virtual

Destroy a sampler in rendering backend. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyShaderFunction ( HgiShaderFunctionHandle * shaderFunctionHandle )

pure virtual

Destroy a shader function. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyShaderProgram ( HgiShaderProgramHandle * shaderProgramHandle )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyTexture ( HgiTextureHandle * texHandle )

pure virtual

Destroy a texture in rendering backend. Thread safety: Destruction must happen on main thread. See notes above.

Implemented in HgiGL.

virtual HGI_API void Hgi::DestroyTextureView ( HgiTextureViewHandle * viewHandle )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API void Hgi::EndFrame ( )

pure virtual

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.

Implemented in HgiGL.

virtual HGI_API TfToken const& Hgi::GetAPIName ( ) const

pure virtual

Return the name of the api (e.g. "OpenGL"). Thread safety: This call is thread safe.

Implemented in HgiGL.

virtual HGI_API HgiCapabilities const* Hgi::GetCapabilities ( ) const

pure virtual

Returns the device-specific capabilities structure. Thread safety: This call is thread safe.

Implemented in HgiGL.

virtual HGI_API HgiIndirectCommandEncoder* Hgi::GetIndirectCommandEncoder ( ) const

pure virtual

Returns the device-specific indirect command buffer encoder or nullptr if not supported. Thread safety: This call is thread safe.

Implemented in HgiGL.

static HGI_API Hgi* Hgi::GetPlatformDefaultHgi ( )

static

*** DEPRECATED *** Please use: CreatePlatformDefaultHgi

HGI_API uint64_t Hgi::GetUniqueId ( )

protected

virtual HGI_API bool Hgi::IsBackendSupported ( ) const

pure virtual

Determine if Hgi instance can run on current hardware. Thread safety: This call is thread safe.

Implemented in HgiGL.

static HGI_API bool Hgi::IsSupported ( )

static

Constructs a temporary Hgi object for the current platform and calls the object's IsBackendSupported() function. Thread safety: Not thread safe.

virtual HGI_API void Hgi::StartFrame ( )

pure virtual

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.

Implemented in HgiGL.

HGI_API void Hgi::SubmitCmds	(	HgiCmds *	cmds,
		HgiSubmitWaitType	wait = `HgiSubmitWaitTypeNoWait`
	)

Submit one HgiCmds objects. Once the cmds object is submitted it cannot be re-used to record cmds. A call to SubmitCmds would usually result in the hgi backend submitting the cmd buffers of the cmds object(s) to the device queue. Derived classes can override _SubmitCmds to customize submission. Thread safety: This call is not thread-safe. Submission must happen on the main thread so we can continue to support the OpenGL platform. See notes above.

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

pxr/imaging/hgi/hgi.h

Public Member Functions

Static Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation