From f6324b0b5d65aef6e713e8b902a6b689659dd27f Mon Sep 17 00:00:00 2001
From: skal <pascal.massimino@gmail.com>
Date: Sun, 8 Feb 2026 21:20:58 +0100
Subject: feat(gpu): Add auxiliary texture masking system
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Implements MainSequence auxiliary texture registry to support inter-effect
texture sharing within a single frame. Primary use case: screen-space
partitioning where multiple effects render to complementary regions.

Architecture:
- MainSequence::register_auxiliary_texture(name, width, height)
  Creates named texture that persists for entire frame
- MainSequence::get_auxiliary_view(name)
  Retrieves texture view for reading/writing

Use case example:
- Effect1: Generate mask (1 = Effect1 region, 0 = Effect2 region)
- Effect1: Render scene A where mask = 1
- Effect2: Reuse mask, render scene B where mask = 0
- Result: Both scenes composited to same framebuffer

Implementation details:
- Added std::map<std::string, AuxiliaryTexture> to MainSequence
- Texture lifecycle managed by MainSequence (create/resize/shutdown)
- Memory impact: ~4-8 MB per mask (acceptable for 2-3 masks)
- Size impact: ~100 lines (~500 bytes code)

Changes:
- src/gpu/effect.h: Added auxiliary texture registry API
- src/gpu/effect.cc: Implemented registry with FATAL_CHECK validation
- doc/MASKING_SYSTEM.md: Complete architecture documentation
- doc/HOWTO.md: Added auxiliary texture usage example

Also fixed:
- test_demo_effects.cc: Corrected EXPECTED_POST_PROCESS_COUNT (9→8)
  Pre-existing bug: DistortEffect was counted but not tested

Testing:
- All 33 tests pass (100%)
- No functional changes to existing effects
- Zero regressions

See doc/MASKING_SYSTEM.md for detailed design rationale and examples.
---
 src/gpu/effect.cc | 66 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

(limited to 'src/gpu/effect.cc')

diff --git a/src/gpu/effect.cc b/src/gpu/effect.cc
index df8ef2d..c2c36b4 100644
--- a/src/gpu/effect.cc
+++ b/src/gpu/effect.cc
@@ -5,6 +5,7 @@
 #include "audio/tracker.h"
 #include "gpu/demo_effects.h"
 #include "gpu/gpu.h"
+#include "util/fatal_error.h"
 #include <algorithm>
 #include <cstdio>
 #include <typeinfo>
@@ -378,11 +379,76 @@ void MainSequence::shutdown() {
     wgpuTextureViewRelease(depth_view_);
   if (depth_texture_)
     wgpuTextureRelease(depth_texture_);
+  for (auto& [name, aux] : auxiliary_textures_) {
+    if (aux.view)
+      wgpuTextureViewRelease(aux.view);
+    if (aux.texture)
+      wgpuTextureRelease(aux.texture);
+  }
+  auxiliary_textures_.clear();
   for (ActiveSequence& entry : sequences_) {
     entry.seq->reset();
   }
 }
 
+// Register a named auxiliary texture for inter-effect sharing
+void MainSequence::register_auxiliary_texture(const char* name, int width,
+                                              int height) {
+  const std::string key(name);
+
+  // Check if already exists
+  auto it = auxiliary_textures_.find(key);
+  if (it != auxiliary_textures_.end()) {
+#if !defined(STRIP_ALL)
+    fprintf(stderr, "Warning: Auxiliary texture '%s' already registered\n",
+            name);
+#endif /* !defined(STRIP_ALL) */
+    return;
+  }
+
+  // Create texture
+  const WGPUTextureDescriptor desc = {
+      .usage =
+          WGPUTextureUsage_RenderAttachment | WGPUTextureUsage_TextureBinding,
+      .dimension = WGPUTextureDimension_2D,
+      .size = {(uint32_t)width, (uint32_t)height, 1},
+      .format = gpu_ctx.format,
+      .mipLevelCount = 1,
+      .sampleCount = 1,
+  };
+
+  WGPUTexture texture = wgpuDeviceCreateTexture(gpu_ctx.device, &desc);
+  FATAL_CHECK(!texture, "Failed to create auxiliary texture: %s\n", name);
+
+  // Create view
+  const WGPUTextureViewDescriptor view_desc = {
+      .format = gpu_ctx.format,
+      .dimension = WGPUTextureViewDimension_2D,
+      .mipLevelCount = 1,
+      .arrayLayerCount = 1,
+  };
+
+  WGPUTextureView view = wgpuTextureCreateView(texture, &view_desc);
+  FATAL_CHECK(!view, "Failed to create auxiliary texture view: %s\n", name);
+
+  // Store in registry
+  auxiliary_textures_[key] = {texture, view, width, height};
+
+#if !defined(STRIP_ALL)
+  printf("[MainSequence] Registered auxiliary texture '%s' (%dx%d)\n", name,
+         width, height);
+#endif /* !defined(STRIP_ALL) */
+}
+
+// Retrieve auxiliary texture view by name
+WGPUTextureView MainSequence::get_auxiliary_view(const char* name) {
+  const std::string key(name);
+  auto it = auxiliary_textures_.find(key);
+  FATAL_CHECK(it == auxiliary_textures_.end(),
+              "Auxiliary texture not found: %s\n", name);
+  return it->second.view;
+}
+
 #if !defined(STRIP_ALL)
 void MainSequence::simulate_until(float target_time, float step_rate,
                                   float bpm) {
-- 
cgit v1.2.3