System Architecture
===================

Reactive Surface FX separates reactive lighting into a decoupled **Target-Driver** pipeline built upon Blender's native modifier stack, BVH spatial trees, and attribute data buses.

The Target-Driver Relationship
------------------------------

* **Display Target**: The receiver mesh that reacts visually and geometrically to incoming light and proximity. Examples: LED screens, pinscreens, water canvases, curved billboards, cloth panels.
* **Proximity Driver**: Any geometric mesh or collection of objects whose spatial presence, motion, and materials trigger illumination on the display target. Examples: falling spheres, animated text digits, spinning blades, moving character limbs.

3-Tier Hybrid Speedup Architecture
----------------------------------

Reactive Surface FX employs a **3-Tier Hybrid Speedup Architecture** (configurable per target via ``evaluation_engine`` as ``HYBRID_SPEEDUP`` or ``LEGACY_CPU``):

1. **Tier 1: Native C++ Geometry Nodes Spatial Engine** (``engine_nodes.py``)

   * Offloads per-face and per-vertex spatial sensing (BVH proximity and directional raycasting), falloff attenuation, PBR material transfer, procedural deformations (*Pinscreen Push*, *Roll / Flip*, *3D Mold Conformance*, *Traveling Wave Ripples*, *Scale / Iris*), and hardware viewport instancing (*Mesh to Points* -> *Instance on Points*) directly into Blender's multithreaded C++ Dependency Graph via the ``.ReactiveSurface_SpatialEngine`` Geometry Nodes modifier.
   * Uses a single-pass SIMD ``Capture Attribute`` stage to evaluate all spatial fields once per domain element without redundant BVH queries, achieving **60+ FPS (< 5 ms)** on 50,000+ polygon surfaces.
   * **Strict Material Preservation**: Never modifies or overrides user materials inside the spatial node tree; custom shader graphs and Principled BSDF materials remain 100% intact.

2. **Tier 2: Hardware-Accelerated 2D Canvas Engine** (``engine_gpu.py``)

   * Accelerates high-resolution **2D Texture Canvas (Bucket Painting)** targets using ``gpu.compute`` GLSL compute shaders (``decay_canvas.glsl`` and ``stamp_contact.glsl``) operating on persistent ``RGBA32F`` GPU textures (``gpu.types.GPUTexture``).
   * Performs parallel texel decay and radial UV contact stamping directly in VRAM in **< 0.5 ms** at 2048×2048 resolution, falling back automatically to the NumPy vectorized pipeline in headless CLI environments without a GPU context.

3. **Tier 3: Stateful Temporal Python Orchestrator** (``engine.py``)

   * Manages temporal phosphor decay, hysteresis, sub-frame motion trail interpolation, ``.npz`` disk cache baking, and non-destructive shader node injection.
   * When temporal decay is active on a ``HYBRID_SPEEDUP`` target, reads pre-computed spatial attributes from the evaluated C++ dependency graph via zero-loop ``foreach_get`` into NumPy arrays, blends temporal state, and writes back ``display_color``.

The Mesh Attribute Data-Bus
---------------------------

Reactive Surface FX exposes standardized procedural attributes on the target mesh that can be read by shaders, Geometry Nodes, and compositors:

.. list-table::
   :header-rows: 1
   :widths: 28 18 54

   * - Attribute Name
     - Type
     - Description
   * - ``display_color``
     - Color (RGBA)
     - Final lit emission color (including temporal phosphor decay when enabled).
   * - ``display_contact_color``
     - Color (RGBA)
     - Instantaneous pre-decay contact emission color computed by the spatial engine.
   * - ``display_base_color``
     - Color (RGBA)
     - Transferred PBR diffuse base color interpolated between target and driver materials.
   * - ``display_metallic``
     - Float
     - Transferred PBR metallic weight interpolated between target and driver materials.
   * - ``display_roughness``
     - Float
     - Transferred PBR roughness weight interpolated between target and driver materials.
   * - ``display_dist``
     - Float
     - Distance to nearest driver surface in meters (0.0 = direct contact).
   * - ``display_penetration``
     - Float
     - Surface penetration depth within the proximity radius in meters.
   * - ``display_hit_loc``
     - Vector (3D)
     - Coordinates of the exact driver contact point.
   * - ``display_hit_normal``
     - Vector (3D)
     - Surface normal vector at the driver contact point.
   * - ``display_offset``
     - Vector (3D)
     - Procedural displacement offset vector (Pinscreen Push, Mold Conformance, Wave Ripple).
   * - ``display_rotation``
     - Vector (3D)
     - Procedural Euler rotation vector (Roll / Flip, Turbulent Noise).
   * - ``display_scale``
     - Float
     - Procedural element scale factor (Scale / Iris and Pixel Gap Bezel).

Non-Destructive Modifier Pipeline
---------------------------------

Reactive Surface FX is **100% non-destructive**:
* The original base mesh vertices, faces, and user materials are never destructively altered.
* All subdivisions, pixel gap bezels, normal pushes, and wave ripples execute through procedural modifier stacks.
* Clicking **Remove Setup** cleanly strips the modifier stack and restores the object's original state instantly.