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")
- vertex attributes required by some backends:
- for the GL backend: optional vertex attribute names
used for name lookup
- for the D3D11 backend: semantic names and indices
- 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: the texture(sic) register register(t0..23)
- MSL: the buffer attribute [[buffer(8..15)]]
- WGSL: the binding in @group(1) @binding(0..127)
- GL: the binding in layout(binding=0..16)
- 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")
- vertex attributes required by some backends: - for the GL backend: optional vertex attribute names used for name lookup - for the D3D11 backend: semantic names and indices
- 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: the texture(sic) register register(t0..23) - MSL: the buffer attribute [[buffer(8..15)]] - WGSL: the binding in @group(1) @binding(0..127) - GL: the binding in layout(binding=0..16)
- 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