diff options
| -rw-r--r-- | CHANGELOG.md | 90 | ||||
| -rw-r--r-- | README.md | 6 |
2 files changed, 93 insertions, 3 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index 29af32ee..a52b9ebd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,95 @@ ## Updates +### 07-Nov-2024 + +The sokol-gfx 'bindings cleanup update'. This is a breaking change. + +Please read this blog post to get an idea what the update is about +and how existing code needs to be changed: + +https://floooh.github.io/2024/11/04/sokol-fall-2024-update.html + +TL;DR: + +- sokol-shdc input shader sources now require to annotate uniform blocks, + textures, samplers and storage buffers with `layout(binding=N)` where `N` + directly maps to sokol-gfx bindslots +- the concept of 'shader stages' has mostly been removed from the sokol-gfx API +- in the `sg_bindings` struct, the nested per-shader-stage binding arrays have + been replaced with unified binding arrays +- in the function `sg_apply_uniforms()`, the shader stage parameter has been + removed +- only relevant if you don't use sokol-shdc: the interior of the `sg_shader_desc` + struct has been changed according to the new binding model, and additional + information must be provided for each resource binding: + - what shader change the binding appears in + - backend 3D API specific resource bindslots to map sokol-gfx + bindslots to 3D API bindslots + +The update is implemented in [PR #1111](https://github.com/floooh/sokol/pull/1111). + +The detailed API changes in the sokol_gfx.h API: + +- the `sg_apply_uniforms()` function no longer has a shader stage parameter: + ```c + void sg_apply_uniforms(int ub_slot, const sg_range* data); + ``` +- the `sg_bindings` struct interior no longer separates resource + bindings by shader stages: + ```c + typedef struct sg_bindings { + uint32_t _start_canary; + sg_buffer vertex_buffers[SG_MAX_VERTEXBUFFER_BINDSLOTS]; + int vertex_buffer_offsets[SG_MAX_VERTEXBUFFER_BINDSLOTS]; + sg_buffer index_buffer; + int index_buffer_offset; + sg_image images[SG_MAX_IMAGE_BINDSLOTS]; + sg_sampler samplers[SG_MAX_SAMPLER_BINDSLOTS]; + sg_buffer storage_buffers[SG_MAX_STORAGEBUFFER_BINDSLOTS]; + uint32_t _end_canary; + } sg_bindings; + ``` +- some public constants starting with `SG_NUM_*` or `SG_MAX_*` + have been removed or renamed (those typically shouldn't show up + in user code) +- similar to the `sg_bindings` struct, the bindings reflection is no + longer split between shader stages: + ```c + typedef struct sg_shader_desc { + uint32_t _start_canary; + sg_shader_function vertex_func; + sg_shader_function fragment_func; + sg_shader_vertex_attr attrs[SG_MAX_VERTEX_ATTRIBUTES]; + sg_shader_uniform_block uniform_blocks[SG_MAX_UNIFORMBLOCK_BINDSLOTS]; + sg_shader_storage_buffer storage_buffers[SG_MAX_STORAGEBUFFER_BINDSLOTS]; + sg_shader_image images[SG_MAX_IMAGE_BINDSLOTS]; + sg_shader_sampler samplers[SG_MAX_SAMPLER_BINDSLOTS]; + sg_shader_image_sampler_pair image_sampler_pairs[SG_MAX_IMAGE_SAMPLER_PAIRS]; + const char* label; + uint32_t _end_canary; + } sg_shader_desc; + ``` + +Behaviour changes: + +- Resource bindings can now have gaps, and validation of `sg_apply_bindings()` + has been relaxed to allow bindslots in `sg_bindings` to be occupied even + if those bindings are not used by the current shader. This allows to use the + same `sg_bindings` struct for different but related shader variants. +- Likewise, uniform block bindslots can now have gaps (but currently it's still + an error trying to apply uniform block data for a bindslot that's not used + by the current shader) +- In debug mode, `sg_draw()` now checks that `sg_apply_bindings()` and/or + `sg_apply_uniforms()` has been called after `sg_apply_pipeline()` when required. +- Lots of new validation checks for the new reflection information in `sg_shader_desc`. + +Drive by fixes: + +- the sokol_gfx.h WebGPU backend is now compatible again with the latest + Google Dawn library (Chrome's native WebGPU implementation) +- the [fips-dawn glue repository](https://github.com/fips-libs/fips-dawn) has been fixed to work with the latest + Dawn build system changes (still only tested on macOS though) + ### 24-Oct-2024 - sokol_nuklear.h: Merged https://github.com/floooh/sokol/pull/1138 which @@ -6,7 +6,7 @@ # Sokol -[**See what's new**](https://github.com/floooh/sokol/blob/master/CHANGELOG.md) (**17-Sep-2024** sokol_app.h: clipboard support for Linux) +[**See what's new**](https://github.com/floooh/sokol/blob/master/CHANGELOG.md) (**07-Nov-2024** sokol_gfx.h: the 'bindings cleanup' update [](/../../actions/workflows/main.yml) [](/../../actions/workflows/gen_bindings.yml) [](https://github.com/floooh/sokol-zig/actions/workflows/main.yml) [](https://github.com/floooh/sokol-nim/actions/workflows/main.yml) [](https://github.com/floooh/sokol-odin/actions/workflows/main.yml)[](https://github.com/floooh/sokol-rust/actions/workflows/main.yml)[](https://github.com/kassane/sokol-d/actions/workflows/build.yml) @@ -155,8 +155,8 @@ static void init(void) { .shader = sg_make_shader(triangle_shader_desc(sg_query_backend())), .layout = { .attrs = { - [ATTR_vs_position].format = SG_VERTEXFORMAT_FLOAT3, - [ATTR_vs_color0].format = SG_VERTEXFORMAT_FLOAT4 + [ATTR_triangle_position].format = SG_VERTEXFORMAT_FLOAT3, + [ATTR_triangle_color0].format = SG_VERTEXFORMAT_FLOAT4 } }, }); |