diff options
Diffstat (limited to 'doc/CONTRIBUTING.md')
| -rw-r--r-- | doc/CONTRIBUTING.md | 14 |
1 files changed, 14 insertions, 0 deletions
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<f32>`) 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. |