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.

6 files changed, 64 insertions, 23 deletions

diff --git a/src/gpu/demo_effects.h b/src/gpu/demo_effects.h
index ed6ee87..1bd6020 100644
--- a/src/gpu/demo_effects.h
+++ b/src/gpu/demo_effects.h
@@ -180,6 +180,26 @@ class Hybrid3DEffect : public Effect {
   int height_ = 720;
 };
 
+// Parameters for DistortEffect
+struct DistortParams {
+  float strength = 0.01f; // Default distortion strength
+  float speed = 1.0f;     // Default distortion speed
+};
+static_assert(sizeof(DistortParams) == 8, "DistortParams must be 8 bytes for WGSL alignment");
+
+class DistortEffect : public PostProcessEffect {
+ public:
+  DistortEffect(const GpuContext& ctx);
+  DistortEffect(const GpuContext& ctx, const DistortParams& params);
+  void render(WGPURenderPassEncoder pass, float time, float beat,
+              float intensity, float aspect_ratio) override;
+  void update_bind_group(WGPUTextureView input_view) override;
+
+ private:
+  DistortParams params_;
+  UniformBuffer<CommonPostProcessUniforms> common_uniforms_;
+  UniformBuffer<DistortParams> params_buffer_;
+};
 class FlashCubeEffect : public Effect {
  public:
   FlashCubeEffect(const GpuContext& ctx);
diff --git a/src/gpu/effects/circle_mask_effect.cc b/src/gpu/effects/circle_mask_effect.cc
index 5b71086..2368631 100644
--- a/src/gpu/effects/circle_mask_effect.cc
+++ b/src/gpu/effects/circle_mask_effect.cc
@@ -86,7 +86,7 @@ void CircleMaskEffect::init(MainSequence* demo) {
        .size = sizeof(CommonPostProcessUniforms)},
       {.binding = 1,
        .buffer = compute_params_.get().buffer,
-       .size = sizeof(EffectParams)},
+       .size = sizeof(CircleMaskParams)},
   };
   const WGPUBindGroupDescriptor compute_bg_desc = {
       .layout = wgpuRenderPipelineGetBindGroupLayout(compute_pipeline_, 0),
@@ -162,7 +162,7 @@ void CircleMaskEffect::compute(WGPUCommandEncoder encoder, float time,
   };
   compute_uniforms_.update(ctx_.queue, uniforms);
 
-  const EffectParams params = {
+  const CircleMaskParams params = {
       .radius = radius_,
   };
   compute_params_.update(ctx_.queue, params);
diff --git a/src/gpu/effects/circle_mask_effect.h b/src/gpu/effects/circle_mask_effect.h
index ac44210..bf9cdfb 100644
--- a/src/gpu/effects/circle_mask_effect.h
+++ b/src/gpu/effects/circle_mask_effect.h
@@ -21,10 +21,12 @@ class CircleMaskEffect : public Effect {
               float intensity, float aspect_ratio) override;
 
  private:
-  struct EffectParams {
+  struct CircleMaskParams {
     float radius;
     float _pad[3];
   };
+  static_assert(sizeof(CircleMaskParams) == 16,
+                "CircleMaskParams must be 16 bytes for WGSL alignment");
 
   MainSequence* demo_ = nullptr;
   float radius_;
@@ -32,7 +34,7 @@ class CircleMaskEffect : public Effect {
   WGPURenderPipeline compute_pipeline_ = nullptr;
   WGPUBindGroup compute_bind_group_ = nullptr;
   UniformBuffer<CommonPostProcessUniforms> compute_uniforms_;
-  UniformBuffer<EffectParams> compute_params_;
+  UniformBuffer<CircleMaskParams> compute_params_;
 
   WGPURenderPipeline render_pipeline_ = nullptr;
   WGPUBindGroup render_bind_group_ = nullptr;
diff --git a/src/gpu/effects/distort_effect.cc b/src/gpu/effects/distort_effect.cc
index d11dfd7..b5acf83 100644
--- a/src/gpu/effects/distort_effect.cc
+++ b/src/gpu/effects/distort_effect.cc
@@ -11,29 +11,36 @@ DistortEffect::DistortEffect(const GpuContext& ctx)
 
 DistortEffect::DistEffect(const GpuContext& ctx, const DistortParams& params)
     : PostProcessEffect(ctx), params_(params) {
-  uniforms_ =
-      gpu_create_buffer(ctx_.device, sizeof(DistortUniforms),
-                        WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst);
+  common_uniforms_.init(ctx_.device);
+  params_buffer_.init(ctx_.device);
   pipeline_ = create_post_process_pipeline(ctx_.device, ctx_.format,
                                            distort_shader_wgsl);
 }
 
 void DistortEffect::render(WGPURenderPassEncoder pass, float t, float b,
                            float i, float a) {
-  DistortUniforms u = {
+  // Populate CommonPostProcessUniforms
+  const CommonPostProcessUniforms common_u = {
+      .resolution = {(float)width_, (float)height_},
+      .aspect_ratio = a,
       .time = t,
       .beat = b,
-      .intensity = i,
-      .aspect_ratio = a,
-      .width = (float)width_,
-      .height = (float)height_,
+      .audio_intensity = i,
+  };
+  common_uniforms_.update(ctx_.queue, common_u);
+
+  // Populate DistortParams
+  const DistortParams distort_p = {
       .strength = params_.strength,
       .speed = params_.speed,
   };
-  wgpuQueueWriteBuffer(ctx_.queue, uniforms_.buffer, 0, &u, sizeof(u));
+  params_buffer_.update(ctx_.queue, distort_p);
+
   PostProcessEffect::render(pass, t, b, i, a);
 }
 
 void DistortEffect::update_bind_group(WGPUTextureView v) {
-  pp_update_bind_group(ctx_.device, pipeline_, &bind_group_, v, {}, uniforms_);
-}
\ No newline at end of file
+
+  pp_update_bind_group(ctx_.device, pipeline_, &bind_group_, v, common_uniforms_.get(), params_buffer_);
+
+}
diff --git a/src/gpu/effects/fade_effect.cc b/src/gpu/effects/fade_effect.cc
index 3efc583..7730a2e 100644
--- a/src/gpu/effects/fade_effect.cc
+++ b/src/gpu/effects/fade_effect.cc
@@ -5,6 +5,12 @@
 #include "gpu/effects/post_process_helper.h"
 #include <cmath>
 
+struct FadeParams {
+  float fade_amount;
+  float _pad[3];
+};
+static_assert(sizeof(FadeParams) == 16, "FadeParams must be 16 bytes for WGSL alignment");
+
 FadeEffect::FadeEffect(const GpuContext& ctx) : PostProcessEffect(ctx) {
   const char* shader_code = R"(
     struct VertexOutput {
@@ -22,7 +28,7 @@ FadeEffect::FadeEffect(const GpuContext& ctx) : PostProcessEffect(ctx) {
       audio_intensity: f32,
     };
 
-    struct EffectParams {
+    struct FadeParams {
       fade_amount: f32,
       _pad0: f32,
       _pad1: f32,
@@ -32,7 +38,7 @@ FadeEffect::FadeEffect(const GpuContext& ctx) : PostProcessEffect(ctx) {
     @group(0) @binding(0) var inputSampler: sampler;
     @group(0) @binding(1) var inputTexture: texture_2d<f32>;
     @group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
-    @group(0) @binding(3) var<uniform> params: EffectParams;
+    @group(0) @binding(3) var<uniform> params: FadeParams;
 
     @vertex
     fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
@@ -90,8 +96,8 @@ void FadeEffect::render(WGPURenderPassEncoder pass, float time, float beat,
     fade_amount = fmaxf(fade_amount, 0.0f);
   }
 
-  float params[4] = {fade_amount, 0.0f, 0.0f, 0.0f};
-  wgpuQueueWriteBuffer(ctx_.queue, params_buffer_.buffer, 0, params,
+  FadeParams params = {fade_amount, {0.0f, 0.0f, 0.0f}};
+  wgpuQueueWriteBuffer(ctx_.queue, params_buffer_.buffer, 0, &params,
                        sizeof(params));
 
   wgpuRenderPassEncoderSetPipeline(pass, pipeline_);
diff --git a/src/gpu/effects/theme_modulation_effect.cc b/src/gpu/effects/theme_modulation_effect.cc
index f9ae636..7c222aa 100644
--- a/src/gpu/effects/theme_modulation_effect.cc
+++ b/src/gpu/effects/theme_modulation_effect.cc
@@ -6,6 +6,12 @@
 #include "gpu/effects/shaders.h"
 #include <cmath>
 
+struct ThemeModulationParams {
+  float theme_brightness;
+  float _pad[3];
+};
+static_assert(sizeof(ThemeModulationParams) == 16, "ThemeModulationParams must be 16 bytes for WGSL alignment");
+
 ThemeModulationEffect::ThemeModulationEffect(const GpuContext& ctx)
     : PostProcessEffect(ctx) {
   const char* shader_code = R"(
@@ -24,7 +30,7 @@ ThemeModulationEffect::ThemeModulationEffect(const GpuContext& ctx)
       audio_intensity: f32,
     };
 
-    struct EffectParams {
+    struct ThemeModulationParams {
       theme_brightness: f32,
       _pad0: f32,
       _pad1: f32,
@@ -34,7 +40,7 @@ ThemeModulationEffect::ThemeModulationEffect(const GpuContext& ctx)
     @group(0) @binding(0) var inputSampler: sampler;
     @group(0) @binding(1) var inputTexture: texture_2d<f32>;
     @group(0) @binding(2) var<uniform> uniforms: CommonUniforms;
-    @group(0) @binding(3) var<uniform> params: EffectParams;
+    @group(0) @binding(3) var<uniform> params: ThemeModulationParams;
 
     @vertex
     fn vs_main(@builtin(vertex_index) vertexIndex: u32) -> VertexOutput {
@@ -97,8 +103,8 @@ void ThemeModulationEffect::render(WGPURenderPassEncoder pass, float time,
       bright_value + (dark_value - bright_value) * transition;
 
   // Update params buffer
-  float params[4] = {theme_brightness, 0.0f, 0.0f, 0.0f};
-  wgpuQueueWriteBuffer(ctx_.queue, params_buffer_.buffer, 0, params,
+  ThemeModulationParams params = {theme_brightness, {0.0f, 0.0f, 0.0f}};
+  wgpuQueueWriteBuffer(ctx_.queue, params_buffer_.buffer, 0, &params,
                        sizeof(params));
 
   // Render