From fd19130b3360d17b44247ec26533b20e051b7f8c Mon Sep 17 00:00:00 2001 From: skal Date: Mon, 9 Feb 2026 11:17:53 +0100 Subject: feat: WGSL Uniform Buffer Validation & Consolidation (Task #75) - Added to validate WGSL/C++ struct alignment. - Integrated validation into . - Standardized uniform usage in , , , . - Renamed generic to specific names in WGSL and C++ to avoid collisions. - Added and updated . - handoff(Gemini): Completed Task #75. --- doc/CONTRIBUTING.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) (limited to 'doc/CONTRIBUTING.md') diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 3a09dbc..7490fe6 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -171,3 +171,17 @@ After hierarchy changes (moving files, renaming), verify: ``` Update scripts with hardcoded paths. + +## Uniform Buffer Checklist + +To ensure consistency and prevent alignment-related issues, follow these guidelines when working with uniform buffers: + +1. **Define WGSL Structs:** Clearly define uniform structs in WGSL, paying close attention to type alignment (`f32`, `vec2`, `vec3`, `vec4`) and using explicit padding (`_pad0: vec2`) where necessary. +2. **Mirror in C++:** Create corresponding C++ structs that mirror the WGSL struct's definitions. +3. **`static_assert` for Size:** Every C++ struct corresponding to a WGSL uniform buffer **must** have a `static_assert` verifying its size matches the expected WGSL size. Use `sizeof(MyStruct) == EXPECTED_SIZE`. +4. **Standard Bindings:** + * **Binding 2:** Always use `CommonPostProcessUniforms` (or a similar common structure) for general per-frame data (resolution, time, beat, etc.). + * **Binding 3:** Use effect-specific parameter structs for unique effect data. +5. **Shader Consistency:** Ensure WGSL shaders correctly declare and use uniforms at the specified bindings (`@group(0) @binding(2)` for common uniforms, `@group(0) @binding(3)` for effect parameters). +6. **Validation Script:** Run `tools/validate_uniforms.py` as part of your development workflow to catch any discrepancies in size or alignment between C++ and WGSL definitions. Ensure this script passes without errors. +7. **Documentation:** Refer to `doc/UNIFORM_BUFFER_GUIDELINES.md` for detailed information on WGSL alignment rules and best practices. -- cgit v1.2.3