Skip to content

Commit

Permalink
sokol_gfx.h: update documentation, wip (bindings cleanup)
Browse files Browse the repository at this point in the history
  • Loading branch information
@floooh
floooh committed Nov 3, 2024
1 parent 5e16039 commit 6b836bd
Showing 1 changed file with 99 additions and 41 deletions.
140 changes: 99 additions & 41 deletions sokol_gfx.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3000,43 +3000,101 @@ typedef struct sg_sampler_desc {
/*
sg_shader_desc

FIXME: UPDATE!
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.

The structure sg_shader_desc defines all creation parameters for shader
programs, used as input to the sg_make_shader() function:
If you use sokol-shdc you can ignore the following information since
the sg_shader_desc struct will be code generated.

- reflection information for vertex attributes (vertex shader inputs):
- vertex attribute name (only optionally used by GLES3 and GL)
- a semantic name and index (required for D3D11)
- for each shader-stage (vertex and fragment):
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 function name
- an optional compile target (only for D3D11 when source is provided,
defaults are "vs_4_0" and "ps_4_0")
- reflection info for each uniform block used by the shader stage:
- the size of the uniform block in bytes
- a memory layout hint (native vs std140, only required for GL backends)
- reflection info for each uniform block member (only required for GL backends):
- member name
- member type (SG_UNIFORMTYPE_xxx)
- if the member is an array, the number of array items
- reflection info for textures used in the shader stage:
- the image type (SG_IMAGETYPE_xxx)
- the image-sample type (SG_IMAGESAMPLETYPE_xxx, default is SG_IMAGESAMPLETYPE_FLOAT)
- whether the shader expects a multisampled texture
- reflection info for samplers used in the shader stage:
- the sampler type (SG_SAMPLERTYPE_xxx)
- reflection info for each image-sampler-pair used by the shader:
- the texture slot of the involved texture
- the sampler slot of the involved sampler
- for GLSL only: the name of the combined image-sampler object
- reflection info for each storage-buffer used by the shader:
- whether the storage buffer is readonly (currently this
must be true)
- 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)`

- 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.attrs[N] => sg_pipeline_desc.layout.attrs[N]

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_blocks[N] => 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.images[N] => sg_bindings.images[N]
- sg_shader_desc.samplers[N] => sg_bindings.samplers[N]
- sg_shader_desc.storage_buffers[N] => sg_bindings.storage_buffers[N]

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
Expand All @@ -3049,6 +3107,13 @@ typedef enum sg_shader_stage {
SG_SHADERSTAGE_FRAGMENT,
} sg_shader_stage;

typedef struct sg_shader_function {
const char* source;
sg_range bytecode;
const char* entry;
const char* d3d11_target; // default: "vs_4_0" or "ps_4_0"
} sg_shader_function;

typedef struct sg_shader_vertex_attr {
const char* glsl_name; // [optional] GLSL attribute name
const char* hlsl_sem_name; // HLSL semantic name
Expand All @@ -3057,17 +3122,17 @@ typedef struct sg_shader_vertex_attr {

typedef struct sg_glsl_shader_uniform {
sg_uniform_type type;
uint16_t array_count; // 0 for scalars, or >1 for arrays
uint16_t array_count; // 0 or 1 for scalars, >1 for arrays
const char* glsl_name; // glsl name binding is required on GL 4.1 and WebGL2
} sg_glsl_shader_uniform;

typedef struct sg_shader_uniform_block {
sg_shader_stage stage;
sg_uniform_layout layout;
uint32_t size;
uint8_t hlsl_register_b_n; // HLSL register(bn)
uint8_t msl_buffer_n; // MSL [[buffer(n)]]
uint8_t hlsl_register_b_n; // HLSL register(bn)
uint8_t msl_buffer_n; // MSL [[buffer(n)]]
uint8_t wgsl_group0_binding_n; // WGSL @group(0) @binding(n)
sg_uniform_layout layout;
sg_glsl_shader_uniform glsl_uniforms[SG_MAX_UNIFORMBLOCK_MEMBERS];
} sg_shader_uniform_block;

Expand Down Expand Up @@ -3105,13 +3170,6 @@ typedef struct sg_shader_image_sampler_pair {
const char* glsl_name; // glsl name binding required because of GL 4.1 and WebGL2
} sg_shader_image_sampler_pair;

typedef struct sg_shader_function {
const char* source;
sg_range bytecode;
const char* entry;
const char* d3d11_target;
} sg_shader_function;

typedef struct sg_shader_desc {
uint32_t _start_canary;
sg_shader_function vertex_func;
Expand Down

0 comments on commit 6b836bd

Please sign in to comment.