# dblsai/webgl-fluid architecture

> Architecture diagram of the GitHub repository dblsai/webgl-fluid, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dblsai/webgl-fluid
- Repository: https://github.com/dblsai/webgl-fluid

## Overview

##### Main components
- User Interface & Input Handler – Represent the HTML layer (index.html) that initializes the WebGL canvas, and input devices (mouse clicks, wheel for zoom, etc.) to drive interactions.
- WebGL Rendering Engine – Include the core simulation engine (main.js, tracer.js, webgl-utils.js) that sets up the WebGL context, handles the rendering loop, and orchestrates the shader pipeline.
– Height Map Shader: Adjusts vertex heights based on inputs (mouse, object interaction).
– Normal Map Shader: Computes the water surface normals.
– Step Simulation Shader: Propagates the wave and attenuates the simulation.
– Additional shaders for computing raytraced reflection/refraction, caustics, god rays, and shadows.
- Asset Management and 3D Object Loading – Show the inclusion of external libraries (like Three.js with its OBJ loader and additional modules in the threejs folder) that load and render OBJ files from the objs directory.
- Utility Libraries – Represent supporting libraries (for instance, glMatrix-0.9.5.js for matrix operations, primitives.js for geometric primitives) and external assets like shaders and WebGL extensions.

##### Relationships and Data Flow
- Rendering Engine to the Shader Pipeline blocks. Illustrate that raw simulation data flows into the Height Map Shader, then cascades into the Normal Map and Step Simulation shaders.
- That the outputs of the simulation shaders are used by the final water mesh shader in the rendering process.
- That the Asset Management module (powered by Three.js loaders) feeds 3D object data into the scene and then interacts with water simulation (for example, the OBJ interaction effects).
- Feedback loops where simulation outputs (like caustics, reflections, and refractions) are rendered back to the texture map and influence subsequent simulation frames.

##### Architectural Patterns and Design Principles
- Separation of concerns: the project divides its responsibilities between user interaction handling, real-time simulation, and asset loading.
- Mention the use of shader-based computation: this is a classic application of GPGPU techniques applied to fluid dynamics and rendering (e.g., using offscreen textures for simulation data).
- Integration of third-party libraries (Three.js, glMatrix) which abstract common tasks in 3D mathematics and object handling.

##### Adding Details
– The simulation process: a step-by-step view from user inputs, shader computations, texture updates, and final water rendering.
– The object interaction pipeline: showing how OBJ files from the objs folder are loaded via Three.js, then interact with the water simulation (e.g., through bounding sphere interactions and reflection/refraction modes).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "User Layer"
        UI["User Input/Interface"]:::ui
    end

    subgraph "Rendering Engine"
        MW["main.js"]:::engine
        TR["tracer.js"]:::engine
        WU["webgl-utils.js"]:::engine
    end

    subgraph "Shader Pipeline"
        SH["Height Map Shader"]:::shader
        SN["Normal Map Shader"]:::shader
        SS["Step Simulation Shader"]:::shader
    end

    subgraph "Asset Management"
        OBJL["OBJLoader.js"]:::asset
        OBMTL["OBJMTLLoader.js"]:::asset
        LOADOBJ["loadObj.js"]:::asset
        OBJS["objs/ (3D Objects)"]:::asset
    end

    subgraph "Utility Libraries"
        GLM["glMatrix-0.9.5.js"]:::utils
        PRIM["primitives.js"]:::utils
    end

    subgraph "Documentation"
        README["README.md"]:::doc
        FILES["files/ (Docs & Demos)"]:::doc
    end

    FR["Final Rendering Output"]:::render

    %% Connections from User Layer to Rendering Engine
    UI -->|"triggers"| MW
    UI -->|"triggers"| TR
    UI -->|"triggers"| WU

    %% Rendering Engine feeds data into Shader Pipeline
    MW -->|"feeds shader"| SH
    TR -->|"feeds shader"| SN
    WU -->|"feeds shader"| SS

    %% Asset Management loads objects into Rendering Engine
    OBJL -->|"loads 3D objects"| MW
    OBMTL -->|"loads 3D objects"| MW
    LOADOBJ -->|"loads 3D objects"| MW
    OBJS -->|"supplies objects"| MW

    %% Utility Libraries support both Rendering and Shader modules
    GLM -->|"supports"| MW
    GLM -->|"supports"| SH
    PRIM -->|"supports"| MW
    PRIM -->|"supports"| SS

    %% Documentation supports the User Layer
    README -->|"guides usage"| UI
    FILES -->|"provides demos"| UI

    %% Shader Pipeline produces Final Rendering Output
    SH -->|"renders water surface"| FR
    SN -->|"renders water surface"| FR
    SS -->|"renders water surface"| FR

    %% Feedback loop from final output to rendering engine
    FR -->|"feedback"| MW

    %% Click Events
    click UI "https://github.com/dblsai/webgl-fluid/blob/master/index.html"
    click MW "https://github.com/dblsai/webgl-fluid/blob/master/main.js"
    click TR "https://github.com/dblsai/webgl-fluid/blob/master/tracer.js"
    click WU "https://github.com/dblsai/webgl-fluid/blob/master/webgl-utils.js"
    click OBJL "https://github.com/dblsai/webgl-fluid/blob/master/threejs/OBJLoader.js"
    click OBMTL "https://github.com/dblsai/webgl-fluid/blob/master/threejs/OBJMTLLoader.js"
    click LOADOBJ "https://github.com/dblsai/webgl-fluid/blob/master/loadObj.js"
    click OBJS "https://github.com/dblsai/webgl-fluid/tree/master/objs/"
    click GLM "https://github.com/dblsai/webgl-fluid/blob/master/glMatrix-0.9.5.js"
    click PRIM "https://github.com/dblsai/webgl-fluid/blob/master/primitives.js"
    click README "https://github.com/dblsai/webgl-fluid/blob/master/README.md"
    click FILES "https://github.com/dblsai/webgl-fluid/tree/master/files/"

    %% Styles
    classDef ui fill:#ffcccc,stroke:#cc0000,stroke-width:2px;
    classDef engine fill:#ccffcc,stroke:#008000,stroke-width:2px;
    classDef shader fill:#ccccff,stroke:#0000cc,stroke-width:2px;
    classDef asset fill:#ffffcc,stroke:#cccc00,stroke-width:2px;
    classDef utils fill:#ffccff,stroke:#cc00cc,stroke-width:2px;
    classDef doc fill:#ccffff,stroke:#00cccc,stroke-width:2px;
    classDef render fill:#ffd700,stroke:#b8860b,stroke-width:2px;
```
