1 //
2 // Copyright 2019 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_ENUMS_H
25 #define PXR_IMAGING_HGI_ENUMS_H
26 
27 #include "pxr/pxr.h"
28 #include "pxr/imaging/hgi/api.h"
29 #include <cstdint>
30 
31 PXR_NAMESPACE_OPEN_SCOPE
32 
33 using HgiBits = uint32_t;
34 
35 
36 /// \enum HgiDeviceCapabilitiesBits
37 ///
38 /// Describes what capabilities the requested device must have.
39 ///
40 /// <ul>
41 /// <li>HgiDeviceCapabilitiesBitsPresentation:
42 ///   The device must be capable of presenting graphics to screen</li>
43 /// <li>HgiDeviceCapabilitiesBitsBindlessBuffers:
44 ///   THe device can access GPU buffers using bindless handles</li>
45 /// <li>HgiDeviceCapabilitiesBitsConcurrentDispatch:
46 ///   The device can execute commands concurrently</li>
47 /// <li>HgiDeviceCapabilitiesBitsUnifiedMemory:
48 ///   The device shares all GPU and CPU memory</li>
49 /// </ul>
50 ///
51 enum HgiDeviceCapabilitiesBits : HgiBits
52 {
53     HgiDeviceCapabilitiesBitsPresentation       = 1 << 0,
54     HgiDeviceCapabilitiesBitsBindlessBuffers    = 1 << 1,
55     HgiDeviceCapabilitiesBitsConcurrentDispatch = 1 << 2,
56     HgiDeviceCapabilitiesBitsUnifiedMemory      = 1 << 3,
57 };
58 
59 using HgiDeviceCapabilities = HgiBits;
60 
61 /// \enum HgiTextureType
62 ///
63 /// Describes the kind of texture.
64 ///
65 /// <ul>
66 /// <li>HgiTextureType1D:
67 ///   A one-dimensional texture.</li>
68 /// <li>HgiTextureType2D:
69 ///   A two-dimensional texture.</li>
70 /// <li>HgiTextureType3D:
71 ///   A three-dimensional texture.</li>
72 /// <li>HgiTextureType1DArray:
73 ///   An array of one-dimensional textures.</li>
74 /// <li>HgiTextureType2DArray:
75 ///   An array of two-dimensional textures.</li>
76 /// </ul>
77 ///
78 enum HgiTextureType
79 {
80     HgiTextureType1D = 0,
81     HgiTextureType2D,
82     HgiTextureType3D,
83     HgiTextureType1DArray,
84     HgiTextureType2DArray,
85 
86     HgiTextureTypeCount
87 };
88 
89 /// \enum HgiTextureUsageBits
90 ///
91 /// Describes how the texture will be used. If a texture has multiple uses you
92 /// can combine multiple bits.
93 ///
94 /// <ul>
95 /// <li>HgiTextureUsageBitsColorTarget:
96 ///   The texture is a color attachment rendered into via a render pass.</li>
97 /// <li>HgiTextureUsageBitsDepthTarget:
98 ///   The texture is a depth attachment rendered into via a render pass.</li>
99 /// <li>HgiTextureUsageBitsStencilTarget:
100 ///   The texture is a stencil attachment rendered into via a render pass.</li>
101 /// <li>HgiTextureUsageBitsShaderRead:
102 ///   The texture is sampled from in a shader (sampling)</li>
103 /// <li>HgiTextureUsageBitsShaderWrite:
104 ///   The texture is written into from in a shader (image store)
105 ///   When a texture is used as HgiBindResourceTypeStorageImage you must
106 ///   add this flag (even if you only read from the image).</li>
107 ///
108 /// <li>HgiTextureUsageCustomBitsBegin:
109 ///   This bit (and any bit after) can be used to attached custom, backend
110 ///   specific  bits to the usage bit. </li>
111 /// </ul>
112 ///
113 enum HgiTextureUsageBits : HgiBits
114 {
115     HgiTextureUsageBitsColorTarget   = 1 << 0,
116     HgiTextureUsageBitsDepthTarget   = 1 << 1,
117     HgiTextureUsageBitsStencilTarget = 1 << 2,
118     HgiTextureUsageBitsShaderRead    = 1 << 3,
119     HgiTextureUsageBitsShaderWrite   = 1 << 4,
120 
121     HgiTextureUsageCustomBitsBegin = 1 << 5,
122 };
123 
124 using HgiTextureUsage = HgiBits;
125 
126 /// \enum HgiSamplerAddressMode
127 ///
128 /// Various modes used during sampling of a texture.
129 ///
130 enum HgiSamplerAddressMode
131 {
132     HgiSamplerAddressModeClampToEdge = 0,
133     HgiSamplerAddressModeMirrorClampToEdge,
134     HgiSamplerAddressModeRepeat,
135     HgiSamplerAddressModeMirrorRepeat,
136     HgiSamplerAddressModeClampToBorderColor,
137 
138     HgiSamplerAddressModeCount
139 };
140 
141 /// \enum HgiSamplerFilter
142 ///
143 /// Sampler filtering modes that determine the pixel value that is returned.
144 ///
145 /// <ul>
146 /// <li>HgiSamplerFilterNearest:
147 ///   Returns the value of a single mipmap level.</li>
148 /// <li>HgiSamplerFilterLinear:
149 ///   Combines the values of multiple mipmap levels.</li>
150 /// </ul>
151 ///
152 enum HgiSamplerFilter
153 {
154     HgiSamplerFilterNearest = 0,
155     HgiSamplerFilterLinear  = 1,
156 
157     HgiSamplerFilterCount
158 };
159 
160 /// \enum HgiMipFilter
161 ///
162 /// Sampler filtering modes that determine the pixel value that is returned.
163 ///
164 /// <ul>
165 /// <li>HgiMipFilterNotMipmapped:
166 ///   Texture is always sampled at mipmap level 0. (ie. max lod=0)</li>
167 /// <li>HgiMipFilterNearest:
168 ///   Returns the value of a single mipmap level.</li>
169 /// <li>HgiMipFilterLinear:
170 ///   Linear interpolates the values of up to two mipmap levels.</li>
171 /// </ul>
172 ///
173 enum HgiMipFilter
174 {
175     HgiMipFilterNotMipmapped = 0,
176     HgiMipFilterNearest      = 1,
177     HgiMipFilterLinear       = 2,
178 
179     HgiMipFilterCount
180 };
181 
182 /// \enum HgiSampleCount
183 ///
184 /// Sample count for multi-sampling
185 ///
186 enum HgiSampleCount
187 {
188     HgiSampleCount1  = 1,
189     HgiSampleCount2  = 2,
190     HgiSampleCount4  = 4,
191     HgiSampleCount8  = 8,
192     HgiSampleCount16 = 16,
193 
194     HgiSampleCountEnd
195 };
196 
197 /// \enum HgiAttachmentLoadOp
198 ///
199 /// Describes what will happen to the attachment pixel data prior to rendering.
200 ///
201 /// <ul>
202 /// <li>HgiAttachmentLoadOpDontCare:
203 ///   All pixels are rendered to. Pixel data in render target starts undefined.</li>
204 /// <li>HgiAttachmentLoadOpClear:
205 ///   The attachment  pixel data is cleared to a specified color value.</li>
206 /// <li>HgiAttachmentLoadOpLoad:
207 ///   Previous pixel data is loaded into attachment prior to rendering.</li>
208 /// </ul>
209 ///
210 enum HgiAttachmentLoadOp
211 {
212     HgiAttachmentLoadOpDontCare = 0,
213     HgiAttachmentLoadOpClear,
214     HgiAttachmentLoadOpLoad,
215 
216     HgiAttachmentLoadOpCount
217 };
218 
219 /// \enum HgiAttachmentStoreOp
220 ///
221 /// Describes what will happen to the attachment pixel data after rendering.
222 ///
223 /// <ul>
224 /// <li>HgiAttachmentStoreOpDontCare:
225 ///   Pixel data is undefined after rendering has completed (no store cost)</li>
226 /// <li>HgiAttachmentStoreOpStore:
227 ///   The attachment pixel data is stored in memory.</li>
228 /// </ul>
229 ///
230 enum HgiAttachmentStoreOp
231 {
232     HgiAttachmentStoreOpDontCare = 0,
233     HgiAttachmentStoreOpStore,
234 
235     HgiAttachmentStoreOpCount
236 };
237 
238 /// \enum HgiBufferUsageBits
239 ///
240 /// Describes the properties and usage of the buffer.
241 ///
242 /// <ul>
243 /// <li>HgiBufferUsageUniform:
244 ///   Shader uniform buffer </li>
245 /// <li>HgiBufferUsageIndex32:
246 ///   Topology 32 bit indices.</li>
247 /// <li>HgiBufferUsageVertex:
248 ///   Vertex attributes.</li>
249 /// <li>HgiBufferUsageStorage:
250 ///   Shader storage buffer / Argument buffer.</li>
251 ///
252 /// <li>HgiBufferUsageCustomBitsBegin:
253 ///   This bit (and any bit after) can be used to attached custom, backend
254 ///   specific  bits to the usage bit. </li>
255 /// </ul>
256 ///
257 enum HgiBufferUsageBits : HgiBits
258 {
259     HgiBufferUsageUniform = 1 << 0,
260     HgiBufferUsageIndex32 = 1 << 1,
261     HgiBufferUsageVertex  = 1 << 2,
262     HgiBufferUsageStorage = 1 << 3,
263 
264     HgiBufferUsageCustomBitsBegin = 1 << 4,
265 };
266 using HgiBufferUsage = HgiBits;
267 
268 /// \enum HgiShaderStage
269 ///
270 /// Describes the stage a shader function operates in.
271 ///
272 /// <ul>
273 /// <li>HgiShaderStageVertex:
274 ///   Vertex Shader.</li>
275 /// <li>HgiShaderStageFragment:
276 ///   Fragment Shader.</li>
277 /// <li>HgiShaderStageCompute:
278 ///   Compute Shader.</li>
279 /// <li>HgiShaderStageTessellationControl:
280 ///   Transforms the control points of the low order surface (patch).
281 ///   This runs before the tessellator fixed function stage.</li>
282 /// <li>HgiShaderStageTessellationEval:
283 ///   Generates the surface geometry (the points) from the transformed control
284 ///   points for every coordinate coming out of the tessellator fixed function
285 ///  stage. </li>
286 /// <li>HgiShaderStageGeometry:
287 ///   Governs the processing of Primitives.</li>
288 /// </ul>
289 ///
290 enum HgiShaderStageBits : HgiBits
291 {
292     HgiShaderStageVertex               = 1 << 0,
293     HgiShaderStageFragment             = 1 << 1,
294     HgiShaderStageCompute              = 1 << 2,
295     HgiShaderStageTessellationControl  = 1 << 3,
296     HgiShaderStageTessellationEval     = 1 << 4,
297     HgiShaderStageGeometry             = 1 << 5,
298 
299     HgiShaderStageCustomBitsBegin      = 1 << 6,
300 };
301 using HgiShaderStage = HgiBits;
302 
303 /// \enum HgiBindResourceType
304 ///
305 /// Describes the type of the resource to be bound.
306 ///
307 /// <ul>
308 /// <li>HgiBindResourceTypeSampler:
309 ///   Sampler.
310 ///   Glsl example: uniform sampler samplerOnly</li>
311 /// <li>HgiBindResourceTypeSampledImage:
312 ///   Image for use with sampling ops.
313 ///   Glsl example: uniform texture2D textureOnly
314 ///   texture(sampler2D(textureOnly, samplerOnly), ...)</li>
315 /// <li>HgiBindResourceTypeCombinedSamplerImage:
316 ///   Image and sampler combined into one.
317 ///   Glsl example: uniform sampler2D texSmp;
318 ///   texture(texSmp, ...)</li>
319 /// <li>HgiBindResourceTypeStorageImage:
320 ///   Storage image used for image store/load ops (Unordered Access View).</li>
321 /// <li>HgiBindResourceTypeUniformBuffer:
322 ///   Uniform buffer (UBO).</li>
323 /// <li>HgiBindResourceTypeStorageBuffer:
324 ///   Shader storage buffer (SSBO).</li>
325 /// </ul>
326 ///
327 enum HgiBindResourceType
328 {
329     HgiBindResourceTypeSampler = 0,
330     HgiBindResourceTypeSampledImage,
331     HgiBindResourceTypeCombinedSamplerImage,
332     HgiBindResourceTypeStorageImage,
333     HgiBindResourceTypeUniformBuffer,
334     HgiBindResourceTypeStorageBuffer,
335 
336     HgiBindResourceTypeCount
337 };
338 
339 /// \enum HgiPolygonMode
340 ///
341 /// Controls polygon mode during rasterization
342 ///
343 /// <ul>
344 /// <li>HgiPolygonModeFill:
345 ///   Polygons are filled.</li>
346 /// <li>HgiPolygonModeLine:
347 ///   Polygon edges are drawn as line segments.</li>
348 /// <li>HgiPolygonModePoint:
349 ///   Polygon vertices are drawn as points.</li>
350 /// </ul>
351 ///
352 enum HgiPolygonMode
353 {
354     HgiPolygonModeFill = 0,
355     HgiPolygonModeLine,
356     HgiPolygonModePoint,
357 
358     HgiPolygonModeCount
359 };
360 
361 /// \enum HgiCullMode
362 ///
363 /// Controls primitive (faces) culling.
364 ///
365 /// <ul>
366 /// <li>HgiPolygonModeNone:
367 ///   No primitive are discarded.</li>
368 /// <li>HgiPolygonModeFront:
369 ///   Front-facing primitive are discarded.</li>
370 /// <li>HgiPolygonModeBack:
371 ///   Back-facing primitive are discarded.</li>
372 /// <li>HgiPolygonModeFrontAndBack:
373 ///   All primitive are discarded.</li>
374 /// </ul>
375 ///
376 enum HgiCullMode
377 {
378     HgiCullModeNone = 0,
379     HgiCullModeFront,
380     HgiCullModeBack,
381     HgiCullModeFrontAndBack,
382 
383     HgiCullModeCount
384 };
385 
386 /// \enum HgiWinding
387 ///
388 /// Determines the front-facing orientation of a primitive (face).
389 ///
390 /// <ul>
391 /// <li>HgiWindingClockwise:
392 ///   Primitives with clockwise vertex-order are front facing.</li>
393 /// <li>HgiWindingCounterClockwise:
394 ///   Primitives with counter-clockwise vertex-order are front facing.</li>
395 /// </ul>
396 ///
397 enum HgiWinding
398 {
399     HgiWindingClockwise = 0,
400     HgiWindingCounterClockwise,
401 
402     HgiWindingCount
403 };
404 
405 
406 /// \enum HgiBlendOp
407 ///
408 /// Blend operations
409 ///
410 enum HgiBlendOp
411 {
412     HgiBlendOpAdd = 0,
413     HgiBlendOpSubtract,
414     HgiBlendOpReverseSubtract,
415     HgiBlendOpMin,
416     HgiBlendOpMax,
417 
418     HgiBlendOpCount
419 };
420 
421 /// \enum HgiBlendFactor
422 ///
423 /// Blend factors
424 ///
425 enum HgiBlendFactor
426 {
427     HgiBlendFactorZero = 0,
428     HgiBlendFactorOne,
429     HgiBlendFactorSrcColor,
430     HgiBlendFactorOneMinusSrcColor,
431     HgiBlendFactorDstColor,
432     HgiBlendFactorOneMinusDstColor,
433     HgiBlendFactorSrcAlpha,
434     HgiBlendFactorOneMinusSrcAlpha,
435     HgiBlendFactorDstAlpha,
436     HgiBlendFactorOneMinusDstAlpha,
437     HgiBlendFactorConstantColor,
438     HgiBlendFactorOneMinusConstantColor,
439     HgiBlendFactorConstantAlpha,
440     HgiBlendFactorOneMinusConstantAlpha,
441     HgiBlendFactorSrcAlphaSaturate,
442     HgiBlendFactorSrc1Color,
443     HgiBlendFactorOneMinusSrc1Color,
444     HgiBlendFactorSrc1Alpha,
445     HgiBlendFactorOneMinusSrc1Alpha,
446 
447     HgiBlendFactorCount
448 };
449 
450 
451 /// \enum HgiCompareFunction
452 ///
453 /// Compare functions.
454 ///
455 enum HgiCompareFunction
456 {
457     HgiCompareFunctionNever = 0,
458     HgiCompareFunctionLess,
459     HgiCompareFunctionEqual,
460     HgiCompareFunctionLEqual,
461     HgiCompareFunctionGreater,
462     HgiCompareFunctionNotEqual,
463     HgiCompareFunctionGEqual,
464     HgiCompareFunctionAlways,
465 
466     HgiCompareFunctionCount
467 };
468 
469 /// \enum HgiComponentSwizzle
470 ///
471 /// Swizzle for a component.
472 ///
473 enum HgiComponentSwizzle
474 {
475     HgiComponentSwizzleZero = 0,
476     HgiComponentSwizzleOne,
477     HgiComponentSwizzleR,
478     HgiComponentSwizzleG,
479     HgiComponentSwizzleB,
480     HgiComponentSwizzleA,
481 
482     HgiComponentSwizzleCount
483 };
484 
485 /// \enum HgiPrimitiveType
486 ///
487 /// What the stream of vertices being rendered represents
488 ///
489 /// <ul>
490 /// <li>HgiPrimitiveTypePointList:
491 ///   Rasterize a point at each vertex.</li>
492 /// <li>HgiPrimitiveTypeLineList:
493 ///   Rasterize a line between each separate pair of vertices.</li>
494 /// <li>HgiPrimitiveTypeLineStrip:
495 ///   Rasterize a line between each pair of adjacent vertices.</li>
496 /// <li>HgiPrimitiveTypeTriangleList:
497 ///   Rasterize a triangle for every separate set of three vertices.</li>
498 /// <li>HgiPrimitiveTypePatchList:
499 ///   A user-defined number of vertices, which is tessellated into
500 ///   points, lines, or triangles.</li>
501 /// </ul>
502 ///
503 enum HgiPrimitiveType
504 {
505     HgiPrimitiveTypePointList = 0,
506     HgiPrimitiveTypeLineList,
507     HgiPrimitiveTypeLineStrip,
508     HgiPrimitiveTypeTriangleList,
509     HgiPrimitiveTypePatchList,
510 
511     HgiPrimitiveTypeCount
512 };
513 
514 /// \enum HgiSubmitWaitType
515 ///
516 /// Describes command submission wait behavior.
517 ///
518 /// <ul>
519 /// <li>HgiSubmitWaitTypeNoWait:
520 ///   CPU should not wait for the GPU to finish processing the cmds.</li>
521 /// <li>HgiSubmitWaitTypeWaitUntilCompleted:
522 ///   The CPU waits ("blocked") until the GPU has consumed the cmds.</li>
523 /// </ul>
524 ///
525 enum HgiSubmitWaitType
526 {
527     HgiSubmitWaitTypeNoWait = 0,
528     HgiSubmitWaitTypeWaitUntilCompleted,
529 };
530 
531 /// \enum HgiMemoryBarrier
532 ///
533 /// Describes what objects the memory barrier affects.
534 ///
535 /// <ul>
536 /// <li>HgiMemoryBarrierNone:
537 ///   No barrier (no-op).</li>
538 /// <li>HgiMemoryBarrierAll:
539 ///   The barrier affects all memory writes and reads.</li>
540 /// </ul>
541 ///
542 enum HgiMemoryBarrierBits
543 {
544     HgiMemoryBarrierNone = 0,
545     HgiMemoryBarrierAll  = 1 << 0
546 };
547 using HgiMemoryBarrier = HgiBits;
548 
549 PXR_NAMESPACE_CLOSE_SCOPE
550 
551 #endif
552