HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
shaderFunctionDesc.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 
25 #ifndef PXR_IMAGING_HGI_SHADERFUNCTIONDESC_H
26 #define PXR_IMAGING_HGI_SHADERFUNCTIONDESC_H
27 
28 #include "pxr/pxr.h"
29 #include "pxr/imaging/hgi/api.h"
30 #include "pxr/imaging/hgi/enums.h"
31 #include "pxr/imaging/hgi/types.h"
32 
33 #include <string>
34 #include <vector>
35 
37 
38 
39 /// \struct HgiShaderFunctionTextureDesc
40 ///
41 /// Describes a texture to be passed into a shader
42 ///
43 /// <ul>
44 /// <li>nameInShader:
45 /// The name written from the codegen into shader file for the texture.</li>
46 /// <li>dimensions:
47 /// 1d, 2d or 3d texture declaration.</li>
48 /// <li>format
49 /// Format of the texture. This is required in APIs where sampler types depend
50 /// on the texture (e.g., GL) </li>
51 /// <li>textureType:
52 /// Type of the texture (e.g. array texture, shadow, etc.).</li>
53 /// <li>bindIndex:
54 /// The index of the resource.</li>
55 /// <li>arraySize:
56 /// If arraySize > 0, indicates the size of the array. Note that textureType
57 /// = HgiTextureTypeTexture and arraySize = 2 would create an array with two
58 /// textures whereas textureType = HgiTextureTypeArrayTexture and arraySize
59 /// = 0 would create a single array texture (arrays of array textures are
60 /// supported as well).</li>
61 /// <li>writable
62 /// Whether the texture is writable.</li>
63 /// </ul>
64 ///
66 {
67  HGI_API
69 
71  uint32_t dimensions;
74  uint32_t bindIndex;
75  size_t arraySize;
76  bool writable;
77 };
78 
80  std::vector<HgiShaderFunctionTextureDesc>;
81 
82 HGI_API
83 bool operator==(
85  const HgiShaderFunctionTextureDesc& rhs);
86 
87 HGI_API
88 bool operator!=(
90  const HgiShaderFunctionTextureDesc& rhs);
91 
92 /// \struct HgiShaderFunctionBufferDesc
93 ///
94 /// Describes a buffer to be passed into a shader
95 ///
96 /// <ul>
97 /// <li>nameInShader:
98 /// The name written from the codegen into shader file for the texture.</li>
99 /// <li>type:
100 /// Type of the param within the shader file.</li>
101 /// <li>bindIndex:
102 /// The index of the resource.</li>
103 /// <li>arraySize:
104 /// The size of the array when binding is a HgiBindingTypeArray.</li>
105 /// <li>bindingType:
106 /// The binding model to use to expose the buffer to the shader.</li>
107 /// <li>writeable:
108 /// Whether the resource is writable.</li>
109 /// </ul>
110 ///
112 {
113  HGI_API
115 
118  uint32_t bindIndex;
119  uint32_t arraySize;
121  bool writable;
122 };
123 
125  std::vector<HgiShaderFunctionBufferDesc>;
126 
127 HGI_API
128 bool operator==(
129  const HgiShaderFunctionBufferDesc& lhs,
130  const HgiShaderFunctionBufferDesc& rhs);
131 
132 HGI_API
133 bool operator!=(
134  const HgiShaderFunctionBufferDesc& lhs,
135  const HgiShaderFunctionBufferDesc& rhs);
136 
137 /// \struct HgiShaderFunctionParamDesc
138 ///
139 /// Describes a param passed into a shader or between shader stages.
140 ///
141 /// <ul>
142 /// <li>nameInShader:
143 /// The name written from the codegen into the shader file for the param.</li>
144 /// <li>type:
145 /// Type of the param within the shader file.</li>
146 /// <li>location:
147 /// For OpenGL, optionally specify the layout location.
148 /// For Metal, if no role is specified, this generates the role</li>
149 /// <li>interstageSlot:
150 /// Optionally specify an index for interstage parameters.</li>
151 /// <li>interpolation:
152 /// Optionally specify the interpolation: Default, Flat or NoPerspective.</li>
153 /// <li>sampling:
154 /// Optionally specify the sampling: Default, Centroid or Sample.</li>
155 /// <li>storage:
156 /// Optionally specify the storage type: Default, Patch.</li>
157 /// <li>role:
158 /// Optionally a role can be specified, like position, uv, color.</li>
159 /// <li>arraySize:
160 /// If specified, generates an array type parameter with given size.</li>
161 /// </ul>
162 ///
164 {
165  HGI_API
167 
170  int32_t location;
171  int32_t interstageSlot;
177 };
178 
180  std::vector<HgiShaderFunctionParamDesc>;
181 
182 HGI_API
183 bool operator==(
184  const HgiShaderFunctionParamDesc& lhs,
185  const HgiShaderFunctionParamDesc& rhs);
186 
187 HGI_API
188 bool operator!=(
189  const HgiShaderFunctionParamDesc& lhs,
190  const HgiShaderFunctionParamDesc& rhs);
191 
192 /// \struct HgiShaderFunctionParamBlockDesc
193 ///
194 /// Describes an interstage param block between shader stages
195 ///
196 /// <ul>
197 /// <li>blockName:
198 /// The name used to match blocks between shader stages.</li>
199 /// <li>instanceName:
200 /// The name used to scope access to block members.</li>
201 /// <li>members:
202 /// The members of the block.</li>
203 /// <li>arraySize:
204 /// If specified, generates a block with given size.</li>
205 /// <li>interstageSlot:
206 /// The interstage slot index of the first member of the block,
207 /// subsequent members are assigned sequential interstage slot indices.</li>
208 /// </ul>
209 ///
211 {
212  HGI_API
214 
215  struct Member {
218  };
219  using MemberVector = std::vector<Member>;
220 
225  int32_t interstageSlot;
226 };
227 
229  std::vector<HgiShaderFunctionParamBlockDesc>;
230 
231 HGI_API
232 bool operator==(
235 
236 HGI_API
237 bool operator!=(
240 
241 HGI_API
242 bool operator==(
245 
246 HGI_API
247 bool operator!=(
250 
251 /// \struct HgiShaderFunctionComputeDesc
252 ///
253 /// Describes a compute function's description
254 ///
255 /// <ul>
256 /// <li>localSize:
257 /// Optional. Specifices the 3D size of the local thread grouping. Defaults to
258 /// 0, meaning it is not set. When x > 0, y and z must also be set > 0.
259 /// When localSize is set to > 0, the following source is generated:
260 /// GLSL: layout(local_size_x = localSize[0],
261 /// local_size_y = localSize[1], local_size_z = localSize[2]) in;
262 /// MSL: [[max_total_threads_per_threadgroup(localSize[0] *
263 /// localSize[1] * localSize[w])]]
264 /// </li>
265 /// </ul>
266 ///
268 {
269  HGI_API
271 
273 };
274 
275 HGI_API
276 bool operator==(
277  const HgiShaderFunctionComputeDesc& lhs,
278  const HgiShaderFunctionComputeDesc& rhs);
279 
280 HGI_API
281 bool operator!=(
282  const HgiShaderFunctionComputeDesc& lhs,
283  const HgiShaderFunctionComputeDesc& rhs);
284 
285 /// \struct HgiShaderFunctionTessellationDesc
286 ///
287 /// Describes a tessellation function's description
288 ///
289 /// <ul>
290 /// <li>patchType:
291 /// The type of patch</li>
292 /// <li>spacing
293 /// The spacing used by the tessellation primitive generator</li>
294 /// <li>ordering
295 /// The ordering used by the tessellation primitive generator</li>
296 /// <li>numVertsInPerPatch:
297 /// The number of vertices in per patch</li>
298 /// <li>numVertsOutPerPatch:
299 /// The number of vertices out per patch</li>
300 /// </ul>
301 ///
303 {
304  enum class PatchType { Triangles, Quads, Isolines };
306  enum class Ordering { CW, CCW };
307  HGI_API
309 
315 };
316 
317 HGI_API
318 bool operator==(
321 
322 HGI_API
323 bool operator!=(
326 
327 /// \struct HgiShaderFunctionGeometryDesc
328 ///
329 /// Describes a geometry function's description
330 ///
331 /// <ul>
332 /// <li>inPrimitiveType:
333 /// The input primitive type.</li>
334 /// <li>outPrimitiveType:
335 /// The output primitive type.</li>
336 /// <li>outMaxVertices:
337 /// The maximum number of vertices written by a single invovation of the
338 /// geometry shader.</li>
339 /// </ul>
340 ///
342 {
343  enum class InPrimitiveType {
345  enum class OutPrimitiveType {
347 
348  HGI_API
350 
354 };
355 
356 HGI_API
357 bool operator==(
359  const HgiShaderFunctionGeometryDesc& rhs);
360 
361 HGI_API
362 bool operator!=(
364  const HgiShaderFunctionGeometryDesc& rhs);
365 
366 ///
367 /// Describes a fragment function's description
368 ///
369 /// <ul>
370 /// <li>earlyFragmentTests:
371 /// Fragment shader tests will be performed before fragment
372 /// shader execution when enabled.</li>
373 /// </ul>
374 ///
376 {
377  HGI_API
379 
381 
382 };
383 
384 HGI_API
385 bool operator==(
387  const HgiShaderFunctionFragmentDesc& rhs);
388 
389 HGI_API
390 bool operator!=(
392  const HgiShaderFunctionFragmentDesc& rhs);
393 
394 /// \struct HgiShaderFunctionDesc
395 ///
396 /// Describes the properties needed to create a GPU shader function.
397 ///
398 /// <ul>
399 /// <li>debugName:
400 /// This label can be applied as debug label for gpu debugging.</li>
401 /// <li>shaderStage:
402 /// The shader stage this function represents.</li>
403 /// <li>shaderCodeDeclarations:
404 /// Optional ascii shader code containing defines and type declarations
405 /// which need to be emitted before generated resource bindings.</li>
406 /// <li>shaderCode:
407 /// The ascii shader code used to compile the shader.</li>
408 /// <li>generatedShaderCodeOut:
409 /// Optional pointer to a string that will be filled in with the
410 /// ascii shader code after shader generation is complete.</li>
411 /// <li>textures:
412 /// List of texture descriptions to be passed into a shader.</li>
413 /// <li>buffers:
414 /// List of buffer descriptions to be passed into a shader.</li>
415 /// <li>constantParams:
416 /// List of descriptions of constant params passed into a shader.</li>
417 /// <li>stageGlobalMembers:
418 /// List of descriptions of params declared at global scope.</li>
419 /// <li>stageInputs:
420 /// List of descriptions of the inputs of the shader.</li>
421 /// <li>stageOutputs:
422 /// List of descriptions of the outputs of the shader.</li>
423 /// <li>stageInputBlocks:
424 /// List of descriptions of the input blocks of the shader.</li>
425 /// <li>stageOutputsBlocks:
426 /// List of descriptions of the output blocks of the shader.</li>
427 /// <li>computeDescriptor:
428 /// Description of compute shader function.</li>
429 /// <li>tessellationDescriptor:
430 /// Description of tessellation shader function.</li>
431 /// <li>geometryDescriptor:
432 /// Description of geometry shader function.</li>
433 /// <li>fragmentDescriptor:
434 /// Description of fragment shader function.</li>
435 /// </ul>
436 ///
438 {
439  HGI_API
444  const char *shaderCode;
446  std::vector<HgiShaderFunctionTextureDesc> textures;
447  std::vector<HgiShaderFunctionBufferDesc> buffers;
448  std::vector<HgiShaderFunctionParamDesc> constantParams;
449  std::vector<HgiShaderFunctionParamDesc> stageGlobalMembers;
450  std::vector<HgiShaderFunctionParamDesc> stageInputs;
451  std::vector<HgiShaderFunctionParamDesc> stageOutputs;
452  std::vector<HgiShaderFunctionParamBlockDesc> stageInputBlocks;
453  std::vector<HgiShaderFunctionParamBlockDesc> stageOutputBlocks;
458 };
459 
461  std::vector<HgiShaderFunctionDesc>;
462 
463 HGI_API
464 bool operator==(
465  const HgiShaderFunctionDesc& lhs,
466  const HgiShaderFunctionDesc& rhs);
467 
468 HGI_API
469 bool operator!=(
470  const HgiShaderFunctionDesc& lhs,
471  const HgiShaderFunctionDesc& rhs);
472 
473 /// Adds texture descriptor to given shader function descriptor.
474 HGI_API
475 void
477  HgiShaderFunctionDesc *desc,
478  const std::string &nameInShader,
479  const uint32_t bindIndex = 0,
480  uint32_t dimensions = 2,
483 
484 /// Adds array of textures descriptor to given shader function descriptor.
485 HGI_API
486 void
488  HgiShaderFunctionDesc *desc,
489  const std::string &nameInShader,
490  const uint32_t arraySize,
491  const uint32_t bindIndex = 0,
492  const uint32_t dimensions = 2,
495 
496 /// Adds writable texture descriptor to given shader function descriptor.
497 HGI_API
498 void
500  HgiShaderFunctionDesc *desc,
501  const std::string &nameInShader,
502  const uint32_t bindIndex = 0,
503  const uint32_t dimensions = 2,
506 
507 /// Adds buffer descriptor to given shader function descriptor.
508 HGI_API
509 void
511  HgiShaderFunctionDesc *desc,
512  const std::string &nameInShader,
513  const std::string &type,
514  const uint32_t bindIndex,
515  HgiBindingType binding,
516  const uint32_t arraySize = 0);
517 
518 /// Adds buffer descriptor to given shader function descriptor.
519 HGI_API
520 void
522  HgiShaderFunctionDesc *desc,
523  const std::string &nameInShader,
524  const std::string &type,
525  const uint32_t bindIndex);
526 
527 /// Adds constant function param descriptor to given shader function
528 /// descriptor.
529 HGI_API
530 void
532  HgiShaderFunctionDesc *desc,
533  const std::string &nameInShader,
534  const std::string &type,
535  const std::string &role = std::string());
536 
537 /// Adds stage input function param descriptor to given shader function
538 /// descriptor.
539 /// The location is will be set to the next available.
540 HGI_API
541 void
543  HgiShaderFunctionDesc *desc,
544  const std::string &nameInShader,
545  const std::string &type,
546  const std::string &role = std::string());
547 
548 /// Adds stage input function param descriptor to given shader function
549 /// descriptor given param descriptor.
550 HGI_API
551 void
553  HgiShaderFunctionDesc *functionDesc,
554  HgiShaderFunctionParamDesc const &paramDesc);
555 
556 /// Interstage input.
557 HGI_API
558 void
560  HgiShaderFunctionDesc *desc,
561  const std::string &nameInShader,
562  const std::string &type,
563  const std::string &arraySize);
564 
565 /// Adds stage output function param descriptor to given shader function
566 /// descriptor.
567 HGI_API
568 void
570  HgiShaderFunctionDesc *desc,
571  const std::string &nameInShader,
572  const std::string &type,
573  const std::string &role = std::string(),
574  const std::string &arraySize = std::string());
575 
576 /// Adds stage output function param descriptor to given shader function
577 /// descriptor.
578 HGI_API
579 void
581  HgiShaderFunctionDesc *desc,
582  const std::string &nameInShader,
583  const std::string &type,
584  const uint32_t location);
585 
586 /// Adds stage output function param descriptor to given shader function
587 /// descriptor given param descriptor.
588 HGI_API
589 void
591  HgiShaderFunctionDesc *functionDesc,
592  HgiShaderFunctionParamDesc const &paramDesc);
593 
595 
596 #endif
HgiStorageType
Definition: enums.h:789
std::vector< HgiShaderFunctionParamDesc > HgiShaderFunctionParamDescVector
std::string * generatedShaderCodeOut
std::vector< HgiShaderFunctionParamDesc > constantParams
GLsizei const GLchar *const * string
Definition: glcorearb.h:814
const char * shaderCodeDeclarations
HGI_API void HgiShaderFunctionAddWritableTexture(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const uint32_t bindIndex=0, const uint32_t dimensions=2, const HgiFormat &format=HgiFormatFloat32Vec4, const HgiShaderTextureType textureType=HgiShaderTextureTypeTexture)
Adds writable texture descriptor to given shader function descriptor.
std::vector< HgiShaderFunctionParamDesc > stageGlobalMembers
std::vector< HgiShaderFunctionTextureDesc > textures
HgiShaderFunctionFragmentDesc fragmentDescriptor
HgiShaderFunctionComputeDesc computeDescriptor
std::vector< HgiShaderFunctionParamDesc > stageOutputs
HGI_API void HgiShaderFunctionAddArrayOfTextures(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const uint32_t arraySize, const uint32_t bindIndex=0, const uint32_t dimensions=2, const HgiFormat &format=HgiFormatFloat32Vec4, const HgiShaderTextureType textureType=HgiShaderTextureTypeTexture)
Adds array of textures descriptor to given shader function descriptor.
std::vector< HgiShaderFunctionTextureDesc > HgiShaderFunctionTextureDescVector
HgiFormat
Definition: types.h:45
HgiShaderFunctionGeometryDesc geometryDescriptor
HGI_API void HgiShaderFunctionAddGlobalVariable(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const std::string &arraySize)
Interstage input.
std::vector< HgiShaderFunctionDesc > HgiShaderFunctionDescVector
std::vector< HgiShaderFunctionParamBlockDesc > HgiShaderFunctionParamBlockDescVector
HgiInterpolationType interpolation
std::vector< HgiShaderFunctionParamBlockDesc > stageInputBlocks
HgiInterpolationType
Definition: enums.h:743
HgiShaderFunctionTessellationDesc tessellationDescriptor
HgiBindingType
Definition: enums.h:715
GLint GLint GLsizei GLint GLenum format
Definition: glcorearb.h:108
HGI_API HgiShaderFunctionDesc()
HgiShaderTextureType textureType
bool operator!=(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Inequality operator, does exact floating point comparisons.
Definition: Mat3.h:556
GLint location
Definition: glcorearb.h:805
Definition: vec3i.h:60
HgiSamplingType
Definition: enums.h:769
HGI_API void HgiShaderFunctionAddTexture(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const uint32_t bindIndex=0, uint32_t dimensions=2, const HgiFormat &format=HgiFormatFloat32Vec4, const HgiShaderTextureType textureType=HgiShaderTextureTypeTexture)
Adds texture descriptor to given shader function descriptor.
HGI_API void HgiShaderFunctionAddConstantParam(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const std::string &role=std::string())
HGI_API void HgiShaderFunctionAddBuffer(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const uint32_t bindIndex, HgiBindingType binding, const uint32_t arraySize=0)
Adds buffer descriptor to given shader function descriptor.
std::vector< Member > MemberVector
#define HGI_API
Definition: api.h:40
std::vector< HgiShaderFunctionParamBlockDesc > stageOutputBlocks
HGI_API HgiShaderFunctionParamDesc()
PXR_NAMESPACE_CLOSE_SCOPE PXR_NAMESPACE_OPEN_SCOPE
Definition: path.h:1432
std::vector< HgiShaderFunctionBufferDesc > HgiShaderFunctionBufferDescVector
std::vector< HgiShaderFunctionBufferDesc > buffers
#define PXR_NAMESPACE_CLOSE_SCOPE
Definition: pxr.h:91
HGI_API void HgiShaderFunctionAddStageOutput(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const std::string &role=std::string(), const std::string &arraySize=std::string())
std::vector< HgiShaderFunctionParamDesc > stageInputs
HgiBits HgiShaderStage
Definition: enums.h:371
HgiShaderTextureType
Definition: enums.h:808
type
Definition: core.h:1059
HGI_API void HgiShaderFunctionAddWritableBuffer(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const uint32_t bindIndex)
Adds buffer descriptor to given shader function descriptor.
bool operator==(const Mat3< T0 > &m0, const Mat3< T1 > &m1)
Equality operator, does exact floating point comparisons.
Definition: Mat3.h:542
HGI_API void HgiShaderFunctionAddStageInput(HgiShaderFunctionDesc *desc, const std::string &nameInShader, const std::string &type, const std::string &role=std::string())