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:

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.