========================================================================
             LIVE-CODE PATH TRACER / RAY TRACER - DOCUMENTATION
========================================================================

Welcome to your lightweight, browser-based, client-side Path Tracer and Whitted Ray Tracer. 
This document outlines the architectural implementation details, execution pipeline, 
rendering modes, geometry compilation specifications, and configuration parameters 
needed to maximize your productivity inside this live code sandbox workspace.

------------------------------------------------------------------------
1. WORKSPACE INTERFACE OVERVIEW
------------------------------------------------------------------------
The system divides your browser screen into two standalone functional halves:

A. VIEWPORT CANVAS (Left Pane):
   - Targets a true 1080p (1920x1080) internal processing buffer regardless of display scale.
   - Automatically utilizes progressive accumulation textures when Path Tracing is active.
   - Integrates an advanced screen-space Fast Approximate Anti-Aliasing (FXAA) pass 
     coupled with an ACES Filmic Tone Mapping Curve and a 2.2 Gamma correction step.

B. GLSL LIVE CODE BLOCK (Right Pane):
   - Displays a clean, monochrome code window running inside an unadorned `<textarea>` terminal.
   - Includes full, immediate syntax tracking via an automated error window that unfurls 
     at the base if a parsing or compilation problem arises.
   - Features dual-state control headers:
     * [EXECUTE]: Compiles the current textarea script into the active WebGL program, resets 
                  accumulation calculations, and spins up background execution loops.
     * [STOP]: Freezes all ray tracing execution threads instantly, switching the canvas into a 
               quiescent safe loop to completely eliminate GPU and CPU overhead.

------------------------------------------------------------------------
2. DUAL CORE RENDER MODES
------------------------------------------------------------------------
At the very peak of your code panel, you can alter the physical behavior of light transport 
calculations by reconfiguring the following macro definition macro:

   #define RENDER_MODE 1

Modes available for processing:

• MODE 0: PURE WHITTED RAY TRACING (#define RENDER_MODE 0)
  - Purpose: For lightning-fast, predictable geometric testing, clean previews, and styling.
  - Performance: Operates at an immediate, static sample ceiling (Noise-free on sample 1).
  - Physics: Fires clean, deterministic primary and secondary specular reflection/refraction 
    vectors. Diffuse objects utilize a fast hard-ambient shading approximation to produce flat, 
    un-bounced shadows. Anti-aliasing relies exclusively on the screen FXAA pipeline pass.

• MODE 1: PROGRESSIVE PATH TRACING (#define RENDER_MODE 1)
  - Purpose: For high-end photorealism, soft ambient occlusion shadows, color bleeding, 
    and microfacet surface qualities.
  - Performance: Progressively refines. The engine constantly accumulates random paths 
    across thousands of sub-frames, crisping and smoothing out the scene over time.
  - Physics: Traces stochastic light trajectories across 6 full light bounces. Utilizes 
    sub-pixel jittering for absolute edge-smoothing anti-aliasing alongside a randomized index 
    of refraction (IOR) calculation to produce rich chromatic light dispersion through dielectrics.

------------------------------------------------------------------------
3. THE PHYSICS MATERIAL PIPELINE
------------------------------------------------------------------------
When defining custom geometric elements within the `mapScene` function graph, your paths 
must assign a descriptive `Material` structure to the output hit profile pointer:

   Material(vec3 emit, vec3 color, float rough, int type, float ior)

Parameters breakdown:
1. vec3 emit  -> The RGB emissive light energy pushed from the surface. Setting this above 
                 zero transforms your primitive directly into a physical light emitter. 
                 (Example: vec3(12.0, 10.0, 8.0) for a rich, warm studio lamp panel).
2. vec3 color -> The base reflection albedo hue of the material (RGB floats from 0.0 to 1.0).
3. float rough-> Surface microfacet roughness (0.00 = perfect glass/chrome mirror, 1.00 = matte).
4. int type   -> Assigns one of three processing engine models:
                 * MAT_DIFFUSE (0): Spreads scattered rays evenly across a cosine hemisphere.
                 * MAT_METAL   (1): Reflects rays using a specular mirror calculation mixed 
                                    with your custom microfacet roughness jitter.
                 * MAT_GLASS   (2): Utilizes Snell's Law and a Schlick Fresnel approximation 
                                    to divide ray paths into pure reflection and true refraction.
5. float ior  -> Index of Refraction (used exclusively by MAT_GLASS). Typical real-world baselines:
                 * Water: 1.33
                 * Window Glass: 1.52
                 * Heavy Flint Crystal: 1.62
                 * Diamond: 2.42

------------------------------------------------------------------------
4. CORE PREFAB DICTIONARY
------------------------------------------------------------------------
The engine compiles a set of mathematical Signed Distance Field (SDF) functions under the hood. 
You can call these analytical primitives natively anywhere inside your scene generation code:

• SPHERE PREFAB:
  - Call signature: sdSphere(p, vec3 center, float radius)
  - Example: float ball = sdSphere(p, vec3(0.0, 0.0, 3.0), 0.5);

• BOX PREFAB:
  - Call signature: sdBox(p, vec3 center, vec3 halfDimensions)
  - Example: float cube = sdBox(p, vec3(1.0, -0.5, 4.0), vec3(0.3, 0.3, 0.3));

------------------------------------------------------------------------
5. ADVANCED ARCHITECTURAL DESIGN: COMPILING HINGED DOORS
------------------------------------------------------------------------
To implement interactive moving architectural elements without complex matrix arrays, 
the template scene exposes a spatial translation helper function:

   vec3 rotateY(vec3 position, vec3 pivotPoint, float angleInDegrees)

This function takes your coordinate space, shifts it to a custom structural center point, 
rotates the entire coordinate plane, and translates it back. By wrapping a standard `sdBox` 
inside this space, you can control the hinge offset of a door seamlessly:

   // 1. Establish the exact coordinate position of your wall hinge
   vec3 hingePivot = vec3(-1.4, 0.2, 4.5); 
   
   // 2. Rotate your evaluation coordinates based on a top-level float variable
   vec3 rotatedDoorSpace = rotateY(p, hingePivot, -DOOR_ROTATION);
   
   // 3. Build a standard box using the altered coordinate system
   float dDoor = sdBox(rotatedDoorSpace, vec3(-0.8, 0.2, 4.5), vec3(0.58, 1.15, 0.04));

To change the scene orientation, adjust the global scalar `const float DOOR_ROTATION = 45.0;` 
at the top of your editor window and click EXECUTE to update the scene.

------------------------------------------------------------------------
6. EXPORTING AND SAFELY RUNNING MODIFICATIONS
------------------------------------------------------------------------
- To adjust the background sky, flip `#define USE_CUSTOM_SKYBOX` to 1 and modify `SKYBOX_COLOR`.
- When constructing complex geometric scenes, utilize GLSL min/max boolean union logic. 
  For example, to drill holes or create archways, subtract an object using a negative distance value:
  `float shape = max(baseWall, -cutoutBox);`
- If you run into optimization issues on low-spec integrated graphics chipsets, you can lower 
  the overall tracing computation complexity inside your code panel by changing `#define MAX_BOUNCES 6` 
  to a lower value like `3` or `4`.
========================================================================
I do not care if there are little to use prefabs, I am not adding more.
========================================================================