From b8d4a815453acac752c6fb3c56d047e39a76fd05 Mon Sep 17 00:00:00 2001 From: skal Date: Sat, 14 Feb 2026 19:05:34 +0100 Subject: feat(gpu): add SDF camera infrastructure and effect base class Add unified camera system for SDF raymarching effects: - CameraParams struct (80 bytes): inv_view matrix + FOV/near/far/aspect - SDFEffect base class: manages camera uniform, provides update_camera() helpers - camera_common.wgsl: getCameraRay(), position/forward/up/right extractors - SDFTestEffect: working example with orbiting camera + animated sphere Refactor effect headers: - Extract class definitions from demo_effects.h to individual .h files - Update includes in .cc files to use specific headers - Cleaner compilation dependencies, faster incremental builds Documentation: - Add SDF_EFFECT_GUIDE.md with complete workflow - Update ARCHITECTURE.md, UNIFORM_BUFFER_GUIDELINES.md - Update EFFECT_WORKFLOW.md, CONTRIBUTING.md Tests: 34/34 passing, SDFTestEffect validated Co-Authored-By: Claude Sonnet 4.5 --- doc/UNIFORM_BUFFER_GUIDELINES.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) (limited to 'doc/UNIFORM_BUFFER_GUIDELINES.md') diff --git a/doc/UNIFORM_BUFFER_GUIDELINES.md b/doc/UNIFORM_BUFFER_GUIDELINES.md index 93999d8..c6cf9c8 100644 --- a/doc/UNIFORM_BUFFER_GUIDELINES.md +++ b/doc/UNIFORM_BUFFER_GUIDELINES.md @@ -16,11 +16,17 @@ Structs are padded to the alignment of their largest member. Any trailing space ## Standard Uniform Buffer Pattern -To maintain consistency and facilitate efficient rendering, a standard pattern for uniform buffer usage is established: +To maintain consistency and facilitate efficient rendering, standard patterns for uniform buffer usage are established: +### Post-Process Effects - **Binding 0 & 1:** Reserved for Sampler and Texture access (handled by `pp_update_bind_group`). -- **Binding 2:** **Common Uniforms** (`CommonPostProcessUniforms` or similar). This buffer should contain frequently used data like resolution, aspect ratio, physical time, beat time, beat phase, and audio intensity. -- **Binding 3:** **Effect-Specific Parameters**. This buffer holds parameters unique to a particular effect (e.g., `strength`, `speed`, `fade_amount`). +- **Binding 2:** **Common Uniforms** (`CommonPostProcessUniforms`). Contains resolution, aspect ratio, physical time, beat time, beat phase, audio intensity. +- **Binding 3:** **Effect-Specific Parameters**. Unique per-effect data (e.g., `strength`, `speed`, `fade_amount`). + +### SDF/Raymarching Effects +- **Binding 0:** **Common Uniforms** (`CommonPostProcessUniforms`). Same as above. +- **Binding 1:** **Camera Parameters** (`CameraParams`). Camera transform and projection data for raymarching. +- **Binding 2+:** **Effect-Specific Parameters** (optional). This pattern ensures that common data is shared efficiently across effects, while effect-specific data remains isolated. @@ -98,10 +104,36 @@ struct GaussianBlurParams { float strength = 2.0f; float _pad = 0.0f; }; -static_assert(sizeof(GaussianBlurParams) == 8, +static_assert(sizeof(GaussianBlurParams) == 8, "GaussianBlurParams must be 8 bytes for WGSL alignment"); ``` +**Example (C++ CameraParams):** + +```cpp +struct CameraParams { + mat4 inv_view; // 64 bytes - inverse view matrix (screen→world) + float fov; // 4 bytes - vertical field of view (radians) + float near_plane; // 4 bytes - near clipping plane + float far_plane; // 4 bytes - far clipping plane + float aspect_ratio; // 4 bytes - width/height ratio +}; +static_assert(sizeof(CameraParams) == 80, + "CameraParams must be 80 bytes for WGSL alignment"); +``` + +**Corresponding WGSL:** + +```wgsl +struct CameraParams { + inv_view: mat4x4, // 64 bytes + fov: f32, // 4 bytes + near_plane: f32, // 4 bytes + far_plane: f32, // 4 bytes + aspect_ratio: f32, // 4 bytes +} +``` + ## Handling Common Pitfalls - **`vec3` Padding:** Avoid using `vec3` for padding in WGSL, as it has a 16-byte alignment. If padding is needed, use `vec2` for 8 bytes or individual `f32`s for 4-byte alignment. -- cgit v1.2.3