HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
graphicsPipeline.h
Go to the documentation of this file.
1 //
2 // Copyright 2020 Pixar
3 //
4 // Licensed under the Apache License, Version 2.0 (the "Apache License")
5 // with the following modification; you may not use this file except in
6 // compliance with the Apache License and the following modification to it:
7 // Section 6. Trademarks. is deleted and replaced with:
8 //
9 // 6. Trademarks. This License does not grant permission to use the trade
10 // names, trademarks, service marks, or product names of the Licensor
11 // and its affiliates, except as required to comply with Section 4(c) of
12 // the License and to reproduce the content of the NOTICE file.
13 //
14 // You may obtain a copy of the Apache License at
15 //
16 // http://www.apache.org/licenses/LICENSE-2.0
17 //
18 // Unless required by applicable law or agreed to in writing, software
19 // distributed under the Apache License with the above modification is
20 // distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
21 // KIND, either express or implied. See the Apache License for the specific
22 // language governing permissions and limitations under the Apache License.
23 //
24 #ifndef PXR_IMAGING_HGI_GRAPHICS_PIPELINE_H
25 #define PXR_IMAGING_HGI_GRAPHICS_PIPELINE_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hgi/api.h"
30 #include "pxr/imaging/hgi/enums.h"
31 #include "pxr/imaging/hgi/handle.h"
34 #include "pxr/imaging/hgi/types.h"
35 
36 #include "pxr/base/gf/vec2f.h"
37 
38 #include <string>
39 #include <vector>
40 
42 
43 
44 /// \struct HgiVertexAttributeDesc
45 ///
46 /// Describes one attribute of a vertex.
47 ///
48 /// <ul>
49 /// <li>format:
50 /// Format of the vertex attribute.</li>
51 /// <li>offset:
52 /// The byte offset of the attribute in vertex buffer</li>
53 /// <li>shaderBindLocation:
54 /// The location of the attribute in the shader. layout(location = X)</li>
55 /// </ul>
56 ///
58 {
59  HGI_API
61 
63  uint32_t offset;
65 };
66 using HgiVertexAttributeDescVector = std::vector<HgiVertexAttributeDesc>;
67 
68 HGI_API
69 bool operator==(
70  const HgiVertexAttributeDesc& lhs,
71  const HgiVertexAttributeDesc& rhs);
72 
73 HGI_API
74 inline bool operator!=(
75  const HgiVertexAttributeDesc& lhs,
76  const HgiVertexAttributeDesc& rhs);
77 
78 
79 /// \struct HgiVertexBufferDesc
80 ///
81 /// Describes the attributes of a vertex buffer.
82 ///
83 /// <ul>
84 /// <li>bindingIndex:
85 /// Binding location for this vertex buffer.</li>
86 /// <li>vertexAttributes:
87 /// List of vertex attributes (in vertex buffer).</li>
88 /// <li>vertexStepFunction:
89 /// The rate at which data is pulled for this vertex buffer.</li>
90 /// <li>vertexStride:
91 /// The byte size of a vertex (distance between two vertices).</li>
92 /// </ul>
93 ///
95 {
96  HGI_API
98 
99  uint32_t bindingIndex;
102  uint32_t vertexStride;
103 };
104 using HgiVertexBufferDescVector = std::vector<HgiVertexBufferDesc>;
105 
106 HGI_API
107 bool operator==(
108  const HgiVertexBufferDesc& lhs,
109  const HgiVertexBufferDesc& rhs);
110 
111 HGI_API
112 inline bool operator!=(
113  const HgiVertexBufferDesc& lhs,
114  const HgiVertexBufferDesc& rhs);
115 
116 
117 /// \struct HgiMultiSampleState
118 ///
119 /// Properties to configure multi sampling.
120 ///
121 /// <ul>
122 /// <li>multiSampleEnable:
123 /// When enabled and sampleCount and attachments match and allow for it, use
124 /// multi-sampling.</li>
125 /// <li>alphaToCoverageEnable:
126 /// Fragment's color.a determines coverage (screen door transparency).</li>
127 /// <li>alphaToOneEnable:
128 /// Fragment's color.a is replaced by the maximum representable alpha
129 /// value for fixed-point color attachments, or by 1.0 for floating-point
130 /// attachments.</li>
131 /// <li>sampleCount:
132 /// The number of samples for each fragment. Must match attachments</li>
133 /// </ul>
134 ///
136 {
137  HGI_API
139 
144 };
145 
146 HGI_API
147 bool operator==(
148  const HgiMultiSampleState& lhs,
149  const HgiMultiSampleState& rhs);
150 
151 HGI_API
152 bool operator!=(
153  const HgiMultiSampleState& lhs,
154  const HgiMultiSampleState& rhs);
155 
156 
157 /// \struct HgiRasterizationState
158 ///
159 /// Properties to configure the rasterization state.
160 ///
161 /// <ul>
162 /// <li>polygonMode:
163 /// Determines the rasterization draw mode of primitve (triangles).</li>
164 /// <li>lineWidth:
165 /// The width of lines when polygonMode is set to line drawing.</li>
166 /// <li>cullMode:
167 /// Determines the culling rules for primitives (triangles).</li>
168 /// <li>winding:
169 /// The rule that determines what makes a front-facing primitive.</li>
170 /// <li>rasterizationEnabled:
171 /// When false all primitives are discarded before rasterization stage.</li>
172 /// <li>depthClampEnabled:
173 /// When enabled clamps the clip space depth to the view volume, rather than
174 /// clipping the depth to the near and far planes.</li>
175 /// <li>depthRange:
176 /// The mapping of NDC depth values to window depth values.</li>
177 /// <li>conservativeRaster:
178 /// When enabled, any pixel at least partially covered by a rendered primitive
179 /// will be rasterized.</li>
180 /// <li>numClipDistances:
181 /// The number of user-defined clip distances.</li>
182 /// </ul>
183 ///
185 {
186  HGI_API
188 
190  float lineWidth;
198 };
199 
200 HGI_API
201 bool operator==(
202  const HgiRasterizationState& lhs,
203  const HgiRasterizationState& rhs);
204 
205 HGI_API
206 bool operator!=(
207  const HgiRasterizationState& lhs,
208  const HgiRasterizationState& rhs);
209 
210 /// \struct HgiStencilState
211 ///
212 /// Properties controlling the operation of the stencil test.
213 ///
214 /// <ul>
215 /// <li>compareFn:
216 /// The function used to test the reference value with the masked
217 /// value read from the stencil buffer.</li>
218 /// <li>referenceValue:
219 //. The reference value used by the stencil test function.</li>
220 /// <li>stencilFailOp:
221 /// The operation executed when the stencil test fails.</li>
222 /// <li>depthFailOp:
223 /// The operation executed when the stencil test passes but the
224 /// depth test fails.</li>
225 /// <li>depthStencilPassOp:
226 /// The operation executed when both stencil and depth tests pass.</li>
227 /// <li>readMask:
228 /// The mask applied to values before the stencil test function.</li>
229 /// <li>writeMask:
230 /// The mask applied when writing to the stencil buffer.</li>
231 /// </ul>
232 ///
234 {
235  HGI_API
236  HgiStencilState();
237 
239  uint32_t referenceValue;
243  uint32_t readMask;
244  uint32_t writeMask;
245 };
246 
247 HGI_API
248 bool operator==(
249  const HgiStencilState& lhs,
250  const HgiStencilState& rhs);
251 
252 HGI_API
253 bool operator!=(
254  const HgiStencilState& lhs,
255  const HgiStencilState& rhs);
256 
257 /// \struct HgiDepthStencilState
258 ///
259 /// Properties to configure depth and stencil test.
260 ///
261 /// <ul>
262 /// <li>depthTestEnabled:
263 /// When enabled uses `depthCompareFn` to test if a fragment passes the
264 /// depth test. Note that depth writes are automatically disabled when
265 /// depthTestEnabled is false.</li>
266 /// <li>depthWriteEnabled:
267 /// When enabled uses `depthCompareFn` to test if a fragment passes the
268 /// depth test. Note that depth writes are automatically disabled when
269 /// depthTestEnabled is false.</li>
270 /// <li>depthCompareFn:
271 /// The function used to test depth values.</li>
272 /// <li>depthBiasEnabled:
273 /// When enabled applies a bias to depth values before the depth test.
274 /// <li>depthBiasConstantFactor:
275 /// The constant depth bias.</li>
276 /// <li>depthBiasSlopeFactor:
277 /// The depth bias that scales with the gradient of the primitive.</li>
278 /// <li>stencilTestEnabled:
279 /// Enables the stencil test.</li>
280 /// <li>stencilFront:
281 /// Stencil operation for front faces.</li>
282 /// <li>stencilBack:
283 /// Stencil operation for back faces.</li>
284 /// </ul>
285 ///
287 {
288  HGI_API
290 
294 
298 
302 };
303 
304 HGI_API
305 bool operator==(
306  const HgiDepthStencilState& lhs,
307  const HgiDepthStencilState& rhs);
308 
309 HGI_API
310 bool operator!=(
311  const HgiDepthStencilState& lhs,
312  const HgiDepthStencilState& rhs);
313 
314 /// \struct HgiGraphicsShaderConstantsDesc
315 ///
316 /// A small, but fast buffer of uniform data for shaders.
317 ///
318 /// <ul>
319 /// <li>byteSize:
320 /// Size of the constants in bytes. (max 256 bytes)</li>
321 /// <li>stageUsage:
322 /// What shader stage(s) the constants will be used in.</li>
323 /// </ul>
324 ///
326  HGI_API
328 
329  uint32_t byteSize;
331 };
332 
333 HGI_API
334 bool operator==(
336  const HgiGraphicsShaderConstantsDesc& rhs);
337 
338 HGI_API
339 bool operator!=(
341  const HgiGraphicsShaderConstantsDesc& rhs);
342 
344 {
345  HGI_API
347 
348  float innerTessLevel[2];
349  float outerTessLevel[4];
350 };
351 
352 /// \struct HgiTessellationState
353 ///
354 /// Properties to configure tessellation.
355 ///
356 /// <ul>
357 /// <li>patchType:
358 /// The type of tessellation patch.</li>
359 /// <li>primitiveIndexSize:
360 /// The number of control indices per patch.</li>
361 /// <li>tessellationLevel:
362 /// The fallback tessellation levels.</li>
363 /// </ul>
364 ///
366 {
367  enum PatchType {
371  };
372 
377  };
378 
379  HGI_API
381 
384  TessFactorMode tessFactorMode = TessFactorMode::Constant;
386 };
387 
388 /// \struct HgiGraphicsPipelineDesc
389 ///
390 /// Describes the properties needed to create a GPU pipeline.
391 ///
392 /// <ul>
393 /// <li>primitiveType:
394 /// Describes the stream of vertices (primitive topology).</li>
395 /// <li>shaderProgram:
396 /// Shader functions/stages used in this pipeline.</li>
397 /// <li>depthState:
398 /// Describes depth state for a pipeline.</li>
399 /// <li>multiSampleState:
400 /// Various settings to control multi-sampling.</li>
401 /// <li>rasterizationState:
402 /// Various settings to control rasterization.</li>
403 /// <li>vertexBuffers:
404 /// Description of the vertex buffers (per-vertex attributes).
405 /// The actual VBOs are bound via GraphicsCmds.</li>
406 /// <li>colorAttachmentDescs:
407 /// Describes each of the color attachments.</li>
408 /// <li>colorResolveAttachmentDescs:
409 /// Describes each of the color resolve attachments (optional).</li>
410 /// <li>depthAttachmentDesc:
411 /// Describes the depth attachment (optional)
412 /// Use HgiFormatInvalid to indicate no depth attachment.</li>
413 /// <li>depthResolveAttachmentDesc:
414 /// Describes the depth resolve attachment (optional).
415 /// Use HgiFormatInvalid to indicate no depth resolve attachment.</li>
416 /// <li>shaderConstantsDesc:
417 /// Describes the shader uniforms.</li>
418 /// <li>tessellationState:
419 /// Describes the tessellation state.</li>
420 /// </ul>
421 ///
423 {
424  HGI_API
426 
440 };
441 
442 HGI_API
443 bool operator==(
444  const HgiGraphicsPipelineDesc& lhs,
445  const HgiGraphicsPipelineDesc& rhs);
446 
447 HGI_API
448 bool operator!=(
449  const HgiGraphicsPipelineDesc& lhs,
450  const HgiGraphicsPipelineDesc& rhs);
451 
452 
453 ///
454 /// \class HgiGraphicsPipeline
455 ///
456 /// Represents a graphics platform independent GPU graphics pipeline
457 /// resource.
458 ///
459 /// Base class for Hgi pipelines.
460 /// To the client (HdSt) pipeline resources are referred to via
461 /// opaque, stateless handles (HgiPipelineHandle).
462 ///
464 {
465 public:
466  HGI_API
467  virtual ~HgiGraphicsPipeline();
468 
469  /// The descriptor describes the object.
470  HGI_API
471  HgiGraphicsPipelineDesc const& GetDescriptor() const;
472 
473 protected:
474  HGI_API
476 
478 
479 private:
480  HgiGraphicsPipeline() = delete;
481  HgiGraphicsPipeline & operator=(const HgiGraphicsPipeline&) = delete;
482  HgiGraphicsPipeline(const HgiGraphicsPipeline&) = delete;
483 };
484 
486 using HgiGraphicsPipelineHandleVector = std::vector<HgiGraphicsPipelineHandle>;
487 
488 
490 
491 #endif
HgiVertexBufferDescVector vertexBuffers
HgiPolygonMode
Definition: enums.h:424
HgiStencilOp
Definition: enums.h:558
HgiVertexBufferStepFunction
Definition: enums.h:640
HgiStencilOp stencilFailOp
HgiVertexAttributeDescVector vertexAttributes
HgiCompareFunction
Definition: enums.h:540
HGI_API HgiMultiSampleState()
HGI_API HgiDepthStencilState()
virtual HGI_API ~HgiGraphicsPipeline()
TessFactorMode tessFactorMode
std::vector< HgiAttachmentDesc > HgiAttachmentDescVector
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
HgiWinding
Definition: enums.h:469
HgiDepthStencilState depthState
HgiAttachmentDescVector colorAttachmentDescs
HgiGraphicsPipelineDesc _descriptor
HgiFormat
Definition: types.h:45
HgiStencilState stencilFront
HgiTessellationLevel tessellationLevel
HgiVertexBufferStepFunction vertexStepFunction
std::vector< HgiVertexBufferDesc > HgiVertexBufferDescVector
HgiCullMode
Definition: enums.h:448
std::vector< HgiGraphicsPipelineHandle > HgiGraphicsPipelineHandleVector
HgiAttachmentDesc depthResolveAttachmentDesc
HgiSampleCount sampleCount
HgiStencilState stencilBack
HgiMultiSampleState multiSampleState
HgiGraphicsShaderConstantsDesc shaderConstantsDesc
HgiRasterizationState rasterizationState
bool operator!=(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Inequality operator, does exact floating point comparisons.
Definition: Mat3.h:556
HGI_API HgiStencilState()
HGI_API HgiVertexAttributeDesc()
HgiPrimitiveType
Definition: enums.h:609
HGI_API HgiVertexBufferDesc()
HGI_API HgiTessellationState()
#define HGI_API
Definition: api.h:40
HgiStencilOp depthStencilPassOp
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1441
HgiAttachmentDescVector colorResolveAttachmentDescs
Definition: vec2f.h:62
HgiShaderProgramHandle shaderProgram
HGI_API HgiRasterizationState()
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HGI_API HgiGraphicsPipelineDesc()
HgiAttachmentDesc depthAttachmentDesc
HgiTessellationState tessellationState
HgiBits HgiShaderStage
Definition: enums.h:370
HgiCompareFunction compareFn
HgiPolygonMode polygonMode
HgiStencilOp depthFailOp
HgiPrimitiveType primitiveType
HgiSampleCount
Definition: enums.h:248
HGI_API HgiGraphicsPipelineDesc const & GetDescriptor() const
The descriptor describes the object.
bool operator==(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Equality operator, does exact floating point comparisons.
Definition: Mat3.h:542
HgiCompareFunction depthCompareFn
HGI_API HgiTessellationLevel()
std::vector< HgiVertexAttributeDesc > HgiVertexAttributeDescVector