Used as parameter of sg_make_shader() to create a shader object which
communicates shader source or bytecode and shader interface
reflection information to sokol-gfx.
If you use sokol-shdc you can ignore the following information since
the sg_shader_desc struct will be code generated.
Otherwise you need to provide the following information to the
sg_make_shader() call:
- a vertex- and fragment-shader function:
- the shader source or bytecode
- an optional entry point name
- for D3D11: an optional compile target when source code is provided
(the defaults are "vs_4_0" and "ps_4_0")
- ...or alternatively, a compute function:
- the shader source or bytecode
- an optional entry point name
- for D3D11: an optional compile target when source code is provided
(the default is "cs_5_0")
- vertex attributes required by some backends (not for compute shaders):
- the vertex attribute base type (undefined, float, signed int, unsigned int),
this information is only used in the validation layer to check that the
pipeline object vertex formats are compatible with the input vertex attribute
type used in the vertex shader. NOTE that the default base type
'undefined' skips the validation layer check.
- for the GL backend: optional vertex attribute names used for name lookup
- for the D3D11 backend: semantic names and indices
- only for compute shaders on the Metal backend:
- the workgroup size aka 'threads per thread-group'
In other 3D APIs this is declared in the shader code:
- GLSL: layout(local_size_x=x, local_size_y=y, local_size_y=z) in;
- HLSL: [numthreads(x, y, z)]
- WGSL: @workgroup_size(x, y, z)
...but in Metal the workgroup size is declared on the CPU side
- reflection information for each uniform block used by the shader:
- the shader stage the uniform block appears in (SG_SHADERSTAGE_*)
- the size in bytes of the uniform block
- backend-specific bindslots:
- HLSL: the constant buffer register register(b0..7)
- MSL: the buffer attribute [[buffer(0..7)]]
- WGSL: the binding in @group(0) @binding(0..15)
- GLSL only: a description of the uniform block interior
- the memory layout standard (SG_UNIFORMLAYOUT_*)
- for each member in the uniform block:
- the member type (SG_UNIFORM_*)
- if the member is an array, the array count
- the member name
- reflection information for each texture used by the shader:
- the shader stage the texture appears in (SG_SHADERSTAGE_*)
- the image type (SG_IMAGETYPE_*)
- the image-sample type (SG_IMAGESAMPLETYPE_*)
- whether the texture is multisampled
- backend specific bindslots:
- HLSL: the texture register register(t0..23)
- MSL: the texture attribute [[texture(0..15)]]
- WGSL: the binding in @group(1) @binding(0..127)
- reflection information for each sampler used by the shader:
- the shader stage the sampler appears in (SG_SHADERSTAGE_*)
- the sampler type (SG_SAMPLERTYPE_*)
- backend specific bindslots:
- HLSL: the sampler register register(s0..15)
- MSL: the sampler attribute [[sampler(0..15)]]
- WGSL: the binding in @group(0) @binding(0..127)
- reflection information for each storage buffer used by the shader:
- the shader stage the storage buffer appears in (SG_SHADERSTAGE_*)
- whether the storage buffer is readonly (currently this must
always be true)
- backend specific bindslots:
- HLSL:
- for readonly storage buffer bindings: register(t0..23)
- for read/write storage buffer bindings: register(u0..7)
- MSL: the buffer attribute [[buffer(8..15)]]
- WGSL: the binding in @group(1) @binding(0..127)
- GL: the binding in layout(binding=0..7)
- reflection information for each combined image-sampler object
used by the shader:
- the shader stage (SG_SHADERSTAGE_*)
- the texture's array index in the sg_shader_desc.images[] array
- the sampler's array index in the sg_shader_desc.samplers[] array
- GLSL only: the name of the combined image-sampler object
The number and order of items in the sg_shader_desc.attrs[]
array corresponds to the items in sg_pipeline_desc.layout.attrs.
For all GL backends, shader source-code must be provided. For D3D11 and Metal,
either shader source-code or byte-code can be provided.
NOTE that the uniform block, image, sampler and storage_buffer arrays
can have gaps. This allows to use the same sg_bindings struct for
different related shader variants.
For D3D11, if source code is provided, the d3dcompiler_47.dll will be loaded
on demand. If this fails, shader creation will fail. When compiling HLSL
source code, you can provide an optional target string via
sg_shader_stage_desc.d3d11_target, the default target is "vs_4_0" for the
vertex shader stage and "ps_4_0" for the pixel shader stage.
sg_shader_desc
Used as parameter of sg_make_shader() to create a shader object which communicates shader source or bytecode and shader interface reflection information to sokol-gfx.
If you use sokol-shdc you can ignore the following information since the sg_shader_desc struct will be code generated.
Otherwise you need to provide the following information to the sg_make_shader() call:
- a vertex- and fragment-shader function: - the shader source or bytecode - an optional entry point name - for D3D11: an optional compile target when source code is provided (the defaults are "vs_4_0" and "ps_4_0")
- ...or alternatively, a compute function: - the shader source or bytecode - an optional entry point name - for D3D11: an optional compile target when source code is provided (the default is "cs_5_0")
- vertex attributes required by some backends (not for compute shaders): - the vertex attribute base type (undefined, float, signed int, unsigned int), this information is only used in the validation layer to check that the pipeline object vertex formats are compatible with the input vertex attribute type used in the vertex shader. NOTE that the default base type 'undefined' skips the validation layer check. - for the GL backend: optional vertex attribute names used for name lookup - for the D3D11 backend: semantic names and indices
- only for compute shaders on the Metal backend: - the workgroup size aka 'threads per thread-group'
In other 3D APIs this is declared in the shader code: - GLSL: layout(local_size_x=x, local_size_y=y, local_size_y=z) in; - HLSL: [numthreads(x, y, z)] - WGSL: @workgroup_size(x, y, z) ...but in Metal the workgroup size is declared on the CPU side
- reflection information for each uniform block used by the shader: - the shader stage the uniform block appears in (SG_SHADERSTAGE_*) - the size in bytes of the uniform block - backend-specific bindslots: - HLSL: the constant buffer register register(b0..7) - MSL: the buffer attribute [[buffer(0..7)]] - WGSL: the binding in @group(0) @binding(0..15) - GLSL only: a description of the uniform block interior - the memory layout standard (SG_UNIFORMLAYOUT_*) - for each member in the uniform block: - the member type (SG_UNIFORM_*) - if the member is an array, the array count - the member name
- reflection information for each texture used by the shader: - the shader stage the texture appears in (SG_SHADERSTAGE_*) - the image type (SG_IMAGETYPE_*) - the image-sample type (SG_IMAGESAMPLETYPE_*) - whether the texture is multisampled - backend specific bindslots: - HLSL: the texture register register(t0..23) - MSL: the texture attribute [[texture(0..15)]] - WGSL: the binding in @group(1) @binding(0..127)
- reflection information for each sampler used by the shader: - the shader stage the sampler appears in (SG_SHADERSTAGE_*) - the sampler type (SG_SAMPLERTYPE_*) - backend specific bindslots: - HLSL: the sampler register register(s0..15) - MSL: the sampler attribute [[sampler(0..15)]] - WGSL: the binding in @group(0) @binding(0..127)
- reflection information for each storage buffer used by the shader: - the shader stage the storage buffer appears in (SG_SHADERSTAGE_*) - whether the storage buffer is readonly (currently this must always be true) - backend specific bindslots: - HLSL: - for readonly storage buffer bindings: register(t0..23) - for read/write storage buffer bindings: register(u0..7) - MSL: the buffer attribute [[buffer(8..15)]] - WGSL: the binding in @group(1) @binding(0..127) - GL: the binding in layout(binding=0..7)
- reflection information for each combined image-sampler object used by the shader: - the shader stage (SG_SHADERSTAGE_*) - the texture's array index in the sg_shader_desc.images[] array - the sampler's array index in the sg_shader_desc.samplers[] array - GLSL only: the name of the combined image-sampler object
The number and order of items in the sg_shader_desc.attrs[] array corresponds to the items in sg_pipeline_desc.layout.attrs.
- sg_shader_desc.attrsN => sg_pipeline_desc.layout.attrsN
NOTE that vertex attribute indices currently cannot have gaps.
The items index in the sg_shader_desc.uniform_blocks[] array corresponds to the ub_slot arg in sg_apply_uniforms():
- sg_shader_desc.uniform_blocksN => sg_apply_uniforms(N, ...)
The items in the shader_desc images, samplers and storage_buffers arrays correspond to the same array items in the sg_bindings struct:
- sg_shader_desc.imagesN => sg_bindings.imagesN - sg_shader_desc.samplersN => sg_bindings.samplersN - sg_shader_desc.storage_buffersN => sg_bindings.storage_buffersN
For all GL backends, shader source-code must be provided. For D3D11 and Metal, either shader source-code or byte-code can be provided.
NOTE that the uniform block, image, sampler and storage_buffer arrays can have gaps. This allows to use the same sg_bindings struct for different related shader variants.
For D3D11, if source code is provided, the d3dcompiler_47.dll will be loaded on demand. If this fails, shader creation will fail. When compiling HLSL source code, you can provide an optional target string via sg_shader_stage_desc.d3d11_target, the default target is "vs_4_0" for the vertex shader stage and "ps_4_0" for the pixel shader stage.