diff options
Diffstat (limited to 'doc/CONTRIBUTING.md')
| -rw-r--r-- | doc/CONTRIBUTING.md | 69 |
1 files changed, 18 insertions, 51 deletions
diff --git a/doc/CONTRIBUTING.md b/doc/CONTRIBUTING.md index 7490fe6..de6378a 100644 --- a/doc/CONTRIBUTING.md +++ b/doc/CONTRIBUTING.md @@ -1,5 +1,7 @@ # Contributing Guidelines +--- + ## Commit Policy ### Verify Before Committing @@ -8,7 +10,6 @@ ```bash ./scripts/check_all.sh ``` -Runs tests, builds tools, cross-compiles Windows. **Manual:** ```bash @@ -26,18 +27,9 @@ cd build && ctest --output-on-failure cmake -S . -B build_debug_check -DDEMO_ENABLE_DEBUG_LOGS=ON cmake --build build_debug_check -j4 ``` -Must compile without errors. **Debug macros** (`src/util/debug.h`): -- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER` -- `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU` - -Example: -```cpp -#if defined(DEBUG_LOG_AUDIO) - DEBUG_AUDIO("[CALLBACK #%d] frames=%d\n", ++count, frames); -#endif -``` +- `DEBUG_LOG_AUDIO`, `DEBUG_LOG_RING_BUFFER`, `DEBUG_LOG_TRACKER`, `DEBUG_LOG_SYNTH`, `DEBUG_LOG_3D`, `DEBUG_LOG_ASSETS`, `DEBUG_LOG_GPU` ### Code Formatting ```bash @@ -50,6 +42,8 @@ Never format `third_party/`. - 3-line header comment - Max 500 lines (split if larger) +--- + ## Coding Style ### Core Rules @@ -61,36 +55,9 @@ Never format `third_party/`. - No `auto` (except complex iterators) - No C++ casts (`static_cast`, `reinterpret_cast`) -### Preprocessor -```cpp -#if defined(MY_TAG) - ... -#endif /* defined(MY_TAG) */ -``` - -### Struct Initialization -```cpp -// Good -const WGPUDescriptor desc = { - .format = g_format, - .dimension = WGPUTextureViewDimension_2D, -}; - -// Bad -WGPUDescriptor desc = {}; -desc.format = g_format; -desc.dimension = WGPUTextureViewDimension_2D; -``` - -### Class Keywords -```cpp - private: // 1 space indent - int field_; -``` +See `doc/CODING_STYLE.md` for detailed examples. -### Comments -- 1-line comment for non-obvious functions -- 3-line header for all source files +--- ## Development Protocols @@ -170,18 +137,18 @@ After hierarchy changes (moving files, renaming), verify: ./scripts/gen_coverage_report.sh ``` -Update scripts with hardcoded paths. +--- ## Uniform Buffer Checklist -To ensure consistency and prevent alignment-related issues, follow these guidelines when working with uniform buffers: +To ensure consistency and prevent alignment-related issues: -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. +1. **Define WGSL Structs:** Pay attention to type alignment (`f32`, `vec2`, `vec3`, `vec4`) and use explicit padding where necessary. +2. **Mirror in C++:** Create corresponding C++ structs that mirror WGSL definitions. +3. **`static_assert` for Size:** Every C++ struct must have a `static_assert` verifying size matches WGSL. +4. **Standard Bindings:** + - **Binding 2:** Always use `CommonPostProcessUniforms` for per-frame data (resolution, time, beat). + - **Binding 3:** Use effect-specific parameter structs for unique data. +5. **Shader Consistency:** Ensure WGSL shaders correctly declare uniforms at specified bindings. +6. **Validation Script:** Run `tools/validate_uniforms.py` to catch discrepancies. +7. **Documentation:** Refer to `doc/UNIFORM_BUFFER_GUIDELINES.md` for detailed alignment rules. |