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.h | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

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

diff --git a/src/gpu/effect.h b/src/gpu/effect.h
index 6ed2c55..6fdb0f4 100644
--- a/src/gpu/effect.h
+++ b/src/gpu/effect.h
@@ -1,7 +1,9 @@
 #pragma once
 #include "gpu/gpu.h"
 #include <algorithm>
+#include <map>
 #include <memory>
+#include <string>
 #include <vector>
 
 class MainSequence;
@@ -112,6 +114,10 @@ class MainSequence {
   void resize(int width, int height);
   void shutdown();
 
+  // Auxiliary texture registry for inter-effect texture sharing
+  void register_auxiliary_texture(const char* name, int width, int height);
+  WGPUTextureView get_auxiliary_view(const char* name);
+
 #if !defined(STRIP_ALL)
   void simulate_until(float target_time, float step_rate, float bpm = 120.0f);
 #endif /* !defined(STRIP_ALL) */
@@ -139,5 +145,13 @@ class MainSequence {
 
   std::unique_ptr<Effect> passthrough_effect_;
 
+  struct AuxiliaryTexture {
+    WGPUTexture texture;
+    WGPUTextureView view;
+    int width;
+    int height;
+  };
+  std::map<std::string, AuxiliaryTexture> auxiliary_textures_;
+
   void create_framebuffers(int width, int height);
 };
-- 
cgit v1.2.3