HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
hgi.h
Go to the documentation of this file.
1 //
2 // Copyright 2019 Pixar
3 //
4 // Licensed under the terms set forth in the LICENSE.txt file available at
5 // https://openusd.org/license.
6 //
7 #ifndef PXR_IMAGING_HGI_GL_HGI_H
8 #define PXR_IMAGING_HGI_GL_HGI_H
9 
10 #include "pxr/pxr.h"
11 #include "pxr/imaging/hgiGL/api.h"
14 #include "pxr/imaging/hgi/hgi.h"
15 #include "pxr/imaging/hgi/tokens.h"
16 
17 #include <functional>
18 #include <memory>
19 #include <vector>
20 
22 
23 class HgiGLDevice;
24 
25 using HgiGLOpsFn = std::function<void(void)>;
26 using HgiGLOpsVector = std::vector<HgiGLOpsFn>;
28 
29 /// \class HgiGL
30 ///
31 /// OpenGL implementation of the Hydra Graphics Interface.
32 ///
33 /// \section GL Context Management
34 /// HgiGL expects any GL context(s) to be externally managed.
35 /// When HgiGL is constructed and during any of its resource create / destroy
36 /// calls and during command recording operations, it expects that an OpenGL
37 /// context is valid and current.
38 ///
39 /// When an application uses the same HgiGL instance from multiple GL contexts,
40 /// the expectations are that:
41 /// 1. The application has set up sharing amongst the various GL contexts. This
42 /// ensures that any non-container resources created may be shared amongst
43 /// the contexts. These shared resources may be safely deleted from
44 /// any context in the share group.
45 ///
46 /// 2. A context arena (see relevant API below) is used per GL context to
47 /// manage container resources that can't be shared amongst GL contexts.
48 /// Currently, HgiGL's support is limited to framebuffer objects.
49 ///
50 /// In the absence of an application provided context arena, the default arena
51 /// is used with the implied expectation that the same GL context is valid
52 /// and current for the lifetime of the HgiGL instance.
53 ///
54 class HgiGL final : public Hgi
55 {
56 public:
57  HGIGL_API
58  HgiGL();
59 
60  HGIGL_API
61  ~HgiGL() override;
62 
63  /// ------------------------------------------------------------------------
64  /// Virtual API
65  /// ------------------------------------------------------------------------
66 
67  HGIGL_API
68  bool IsBackendSupported() const override;
69 
70  HGIGL_API
72  HgiGraphicsCmdsDesc const& desc) override;
73 
74  HGIGL_API
76 
77  HGIGL_API
79  HgiComputeCmdsDesc const& desc) override;
80 
81  HGIGL_API
82  HgiTextureHandle CreateTexture(HgiTextureDesc const & desc) override;
83 
84  HGIGL_API
85  void DestroyTexture(HgiTextureHandle* texHandle) override;
86 
87  HGIGL_API
89  HgiTextureViewDesc const& desc) override;
90 
91  HGIGL_API
92  void DestroyTextureView(HgiTextureViewHandle* viewHandle) override;
93 
94  HGIGL_API
95  HgiSamplerHandle CreateSampler(HgiSamplerDesc const & desc) override;
96 
97  HGIGL_API
98  void DestroySampler(HgiSamplerHandle* smpHandle) override;
99 
100  HGIGL_API
101  HgiBufferHandle CreateBuffer(HgiBufferDesc const & desc) override;
102 
103  HGIGL_API
104  void DestroyBuffer(HgiBufferHandle* bufHandle) override;
105 
106  HGIGL_API
108  HgiShaderFunctionDesc const& desc) override;
109 
110  HGIGL_API
112  HgiShaderFunctionHandle* shaderFunctionHandle) override;
113 
114  HGIGL_API
116  HgiShaderProgramDesc const& desc) override;
117 
118  HGIGL_API
120  HgiShaderProgramHandle* shaderProgramHandle) override;
121 
122  HGIGL_API
124  HgiResourceBindingsDesc const& desc) override;
125 
126  HGIGL_API
127  void DestroyResourceBindings(HgiResourceBindingsHandle* resHandle) override;
128 
129  HGIGL_API
131  HgiGraphicsPipelineDesc const& pipeDesc) override;
132 
133  HGIGL_API
135  HgiGraphicsPipelineHandle* pipeHandle) override;
136 
137  HGIGL_API
139  HgiComputePipelineDesc const& pipeDesc) override;
140 
141  HGIGL_API
142  void DestroyComputePipeline(HgiComputePipelineHandle* pipeHandle) override;
143 
144  HGIGL_API
145  TfToken const& GetAPIName() const override;
146 
147  HGIGL_API
148  HgiGLCapabilities const* GetCapabilities() const override;
149 
150  HGIGL_API
152 
153  HGIGL_API
154  void StartFrame() override;
155 
156  HGIGL_API
157  void EndFrame() override;
158 
159  /// ------------------------------------------------------------------------
160  // HgiGL specific API
161  /// ------------------------------------------------------------------------
162 
163  // Returns the opengl device.
164  HGIGL_API
165  HgiGLDevice* GetPrimaryDevice() const;
166 
167  /// ------------------------------------------------------------------------
168  /// Context arena API
169  /// Please refer to \ref "GL Context Management" for usage expectations.
170  ///
171  /// Creates and return a context arena object handle.
172  HGIGL_API
174 
175  /// Destroy a context arena.
176  /// Note: The context arena must be unset (by calling SetContextArena with
177  /// an empty handle) prior to destruction.
178  HGIGL_API
179  void DestroyContextArena(HgiGLContextArenaHandle* arenaHandle);
180 
181  /// Set the context arena to manage container resources (currently limited to
182  /// framebuffer objects) for graphics commands submitted subsequently.
183  HGIGL_API
184  void SetContextArena(HgiGLContextArenaHandle const& arenaHandle);
185  // -------------------------------------------------------------------------
186 
187 protected:
188  HGIGL_API
189  bool _SubmitCmds(HgiCmds* cmds, HgiSubmitWaitType wait) override;
190 
191 private:
192  HgiGL & operator=(const HgiGL&) = delete;
193  HgiGL(const HgiGL&) = delete;
194 
195  /// Invalidates the resource handle and places the object in the garbage
196  /// collector vector for future destruction.
197  /// This is helpful to avoid destroying GPU resources still in-flight.
198  template<class T>
199  void _TrashObject(
200  HgiHandle<T>* handle, std::vector<HgiHandle<T>>* collector) {
201  collector->push_back(HgiHandle<T>(handle->Get(), /*id*/0));
202  *handle = HgiHandle<T>();
203  }
204 
205  HgiGLDevice* _device;
206  std::unique_ptr<HgiGLCapabilities> _capabilities;
207  HgiGLGarbageCollector _garbageCollector;
208  int _frameDepth;
209 };
210 
211 /// ----------------------------------------------------------------------------
212 /// API Version & History
213 /// ----------------------------------------------------------------------------
214 /// 1 -> 2: Added Context Arena API
215 ///
216 #define HGIGL_API_VERSION 2
217 
219 
220 #endif
HGIGL_API HgiGL()
HGIGL_API void SetContextArena(HgiGLContextArenaHandle const &arenaHandle)
HGIGL_API void DestroyShaderFunction(HgiShaderFunctionHandle *shaderFunctionHandle) override
HGIGL_API HgiComputePipelineHandle CreateComputePipeline(HgiComputePipelineDesc const &pipeDesc) override
HGIGL_API void DestroyShaderProgram(HgiShaderProgramHandle *shaderProgramHandle) override
HGIGL_API HgiTextureViewHandle CreateTextureView(HgiTextureViewDesc const &desc) override
HGIGL_API void DestroyContextArena(HgiGLContextArenaHandle *arenaHandle)
std::function< void(void)> HgiGLOpsFn
Definition: hgi.h:25
int HgiHandle< class HgiTexture > HgiTextureHandle
HGIGL_API HgiGLCapabilities const * GetCapabilities() const override
HGIGL_API HgiBlitCmdsUniquePtr CreateBlitCmds() override
HGIGL_API HgiShaderFunctionHandle CreateShaderFunction(HgiShaderFunctionDesc const &desc) override
HGIGL_API TfToken const & GetAPIName() const override
HgiSubmitWaitType
Definition: enums.h:650
Definition: token.h:70
HGIGL_API HgiSamplerHandle CreateSampler(HgiSamplerDesc const &desc) override
HGIGL_API HgiShaderProgramHandle CreateShaderProgram(HgiShaderProgramDesc const &desc) override
HGIGL_API void DestroyBuffer(HgiBufferHandle *bufHandle) override
T * Get() const
Definition: handle.h:39
HGIGL_API HgiGLDevice * GetPrimaryDevice() const
Definition: hgi.h:54
HGIGL_API void DestroyComputePipeline(HgiComputePipelineHandle *pipeHandle) override
HGIGL_API HgiResourceBindingsHandle CreateResourceBindings(HgiResourceBindingsDesc const &desc) override
#define HGIGL_API
Definition: api.h:23
HGIGL_API HgiIndirectCommandEncoder * GetIndirectCommandEncoder() const override
std::unique_ptr< class HgiGraphicsCmds > HgiGraphicsCmdsUniquePtr
Definition: effectsShader.h:28
HGIGL_API HgiTextureHandle CreateTexture(HgiTextureDesc const &desc) override
HGIGL_API ~HgiGL() override
HGIGL_API void DestroySampler(HgiSamplerHandle *smpHandle) override
HGIGL_API bool _SubmitCmds(HgiCmds *cmds, HgiSubmitWaitType wait) override
HGIGL_API HgiGraphicsCmdsUniquePtr CreateGraphicsCmds(HgiGraphicsCmdsDesc const &desc) override
std::unique_ptr< class HgiComputeCmds > HgiComputeCmdsUniquePtr
Definition: computeCmds.h:19
HGIGL_API void StartFrame() override
*tasks wait()
HGIGL_API HgiGraphicsPipelineHandle CreateGraphicsPipeline(HgiGraphicsPipelineDesc const &pipeDesc) override
Definition: hgi.h:93
HGIGL_API void DestroyTextureView(HgiTextureViewHandle *viewHandle) override
std::unique_ptr< class HgiBlitCmds > HgiBlitCmdsUniquePtr
Definition: blitCmds.h:28
HGIGL_API HgiComputeCmdsUniquePtr CreateComputeCmds(HgiComputeCmdsDesc const &desc) override
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1425
HGIGL_API HgiBufferHandle CreateBuffer(HgiBufferDesc const &desc) override
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:74
HGIGL_API void DestroyResourceBindings(HgiResourceBindingsHandle *resHandle) override
HGIGL_API HgiGLContextArenaHandle CreateContextArena()
HGIGL_API void EndFrame() override
HGIGL_API bool IsBackendSupported() const override
HGIGL_API void DestroyTexture(HgiTextureHandle *texHandle) override
std::vector< HgiGLOpsFn > HgiGLOpsVector
Definition: hgi.h:26
HGIGL_API void DestroyGraphicsPipeline(HgiGraphicsPipelineHandle *pipeHandle) override
Definition: cmds.h:27