![]() |
|
Hydra Graphics Interface. More...
Public Member Functions | |
HGI_API void | SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait=HgiSubmitWaitTypeNoWait) |
Submit one HgiCmds objects. More... | |
virtual HGI_API bool | IsBackendSupported () const =0 |
Determine if Hgi instance can run on current hardware. More... | |
virtual HGI_API HgiGraphicsCmdsUniquePtr | CreateGraphicsCmds (HgiGraphicsCmdsDesc const &desc)=0 |
Returns a GraphicsCmds object (for temporary use) that is ready to record draw commands. More... | |
virtual HGI_API HgiBlitCmdsUniquePtr | CreateBlitCmds ()=0 |
Returns a BlitCmds object (for temporary use) that is ready to execute resource copy commands. More... | |
virtual HGI_API HgiComputeCmdsUniquePtr | CreateComputeCmds (HgiComputeCmdsDesc const &desc)=0 |
Returns a ComputeCmds object (for temporary use) that is ready to record dispatch commands. More... | |
virtual HGI_API HgiTextureHandle | CreateTexture (HgiTextureDesc const &desc)=0 |
Create a texture in rendering backend. More... | |
virtual HGI_API void | DestroyTexture (HgiTextureHandle *texHandle)=0 |
Destroy a texture in rendering backend. More... | |
virtual HGI_API HgiTextureViewHandle | CreateTextureView (HgiTextureViewDesc const &desc)=0 |
Create a texture view in rendering backend. More... | |
virtual HGI_API void | DestroyTextureView (HgiTextureViewHandle *viewHandle)=0 |
Destroy a texture view in rendering backend. More... | |
virtual HGI_API HgiSamplerHandle | CreateSampler (HgiSamplerDesc const &desc)=0 |
Create a sampler in rendering backend. More... | |
virtual HGI_API void | DestroySampler (HgiSamplerHandle *smpHandle)=0 |
Destroy a sampler in rendering backend. More... | |
virtual HGI_API HgiBufferHandle | CreateBuffer (HgiBufferDesc const &desc)=0 |
Create a buffer in rendering backend. More... | |
virtual HGI_API void | DestroyBuffer (HgiBufferHandle *bufHandle)=0 |
Destroy a buffer in rendering backend. More... | |
virtual HGI_API HgiShaderFunctionHandle | CreateShaderFunction (HgiShaderFunctionDesc const &desc)=0 |
Create a new shader function. More... | |
virtual HGI_API void | DestroyShaderFunction (HgiShaderFunctionHandle *shaderFunctionHandle)=0 |
Destroy a shader function. More... | |
virtual HGI_API HgiShaderProgramHandle | CreateShaderProgram (HgiShaderProgramDesc const &desc)=0 |
Create a new shader program. More... | |
virtual HGI_API void | DestroyShaderProgram (HgiShaderProgramHandle *shaderProgramHandle)=0 |
Destroy a shader program. More... | |
virtual HGI_API HgiResourceBindingsHandle | CreateResourceBindings (HgiResourceBindingsDesc const &desc)=0 |
Create a new resource binding object. More... | |
virtual HGI_API void | DestroyResourceBindings (HgiResourceBindingsHandle *resHandle)=0 |
Destroy a resource binding object. More... | |
virtual HGI_API HgiGraphicsPipelineHandle | CreateGraphicsPipeline (HgiGraphicsPipelineDesc const &pipeDesc)=0 |
Create a new graphics pipeline state object. More... | |
virtual HGI_API void | DestroyGraphicsPipeline (HgiGraphicsPipelineHandle *pipeHandle)=0 |
Destroy a graphics pipeline state object. More... | |
virtual HGI_API HgiComputePipelineHandle | CreateComputePipeline (HgiComputePipelineDesc const &pipeDesc)=0 |
Create a new compute pipeline state object. More... | |
virtual HGI_API void | DestroyComputePipeline (HgiComputePipelineHandle *pipeHandle)=0 |
Destroy a compute pipeline state object. More... | |
virtual HGI_API TfToken const & | GetAPIName () const =0 |
Return the name of the api (e.g. More... | |
virtual HGI_API HgiCapabilities const * | GetCapabilities () const =0 |
Returns the device-specific capabilities structure. More... | |
virtual HGI_API HgiIndirectCommandEncoder * | GetIndirectCommandEncoder () const =0 |
Returns the device-specific indirect command buffer encoder or nullptr if not supported. More... | |
virtual HGI_API void | StartFrame ()=0 |
Optionally called by client app at the start of a new rendering frame. More... | |
virtual HGI_API void | EndFrame ()=0 |
Optionally called at the end of a rendering frame. More... | |
Static Public Member Functions | |
static HGI_API Hgi * | GetPlatformDefaultHgi () |
*** DEPRECATED *** Please use: CreatePlatformDefaultHgi More... | |
static HGI_API HgiUniquePtr | CreatePlatformDefaultHgi () |
Helper function to return a Hgi object for the current platform. More... | |
static HGI_API bool | IsSupported () |
Constructs a temporary Hgi object for the current platform and calls the object's IsBackendSupported() function. More... | |
Protected Member Functions | |
HGI_API uint64_t | GetUniqueId () |
virtual HGI_API bool | _SubmitCmds (HgiCmds *cmds, HgiSubmitWaitType wait) |
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:
Each Hgi backend is additionally encouraged to support:
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] )
|
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.
|
pure virtual |
Create a buffer in rendering backend.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
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.
|
pure virtual |
Create a new compute pipeline state object.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
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.
|
pure virtual |
Create a new graphics pipeline state object.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
static |
|
pure virtual |
Create a new resource binding object.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Create a sampler in rendering backend.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Create a new shader function.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Create a new shader program.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Create a texture in rendering backend.
Thread safety: Creation must happen on main thread. See notes above.
Implemented in HgiGL.
|
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.
|
pure virtual |
Destroy a buffer in rendering backend.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Destroy a compute pipeline state object.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Destroy a graphics pipeline state object.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Destroy a resource binding object.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Destroy a sampler in rendering backend.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
pure virtual |
Destroy a shader function.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
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.
|
pure virtual |
Destroy a texture in rendering backend.
Thread safety: Destruction must happen on main thread. See notes above.
Implemented in HgiGL.
|
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.
|
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.
|
pure virtual |
Return the name of the api (e.g.
"OpenGL"). Thread safety: This call is thread safe.
Implemented in HgiGL.
|
pure virtual |
Returns the device-specific capabilities structure.
Thread safety: This call is thread safe.
Implemented in HgiGL.
|
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 |
*** DEPRECATED *** Please use: CreatePlatformDefaultHgi
|
pure virtual |
|
static |
Constructs a temporary Hgi object for the current platform and calls the object's IsBackendSupported() function.
Thread safety: Not thread safe.
|
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 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.