# xkostmand/pure3d architecture

> Architecture diagram of the GitHub repository xkostmand/pure3d, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-02-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/xkostmand/pure3d
- Repository: https://github.com/xkostmand/pure3d

## Overview

##### Project type and purpose
- This is a low-level graphics engine (“Pure3D Engine”) written in Java 21 on top of LWJGL 3 and OpenGL 3.3.
- Its purpose is to demonstrate manual GPU interaction, custom shader pipelines, and raw memory management.

##### File structure
- Single Gradle module (build.gradle, settings.gradle).
- Entry point: src/main/java/com/chrys/pure3d/Main.java.
- No separate “frontend”/“backend” folders—this is a standalone rendering engine.
- Dependencies managed via Gradle; wrapper files under gradle/wrapper.

##### README for additional insights
- Core libraries: LWJGL 3 (GLFW + OpenGL), JOML for math.
- Key subsystems: Windowing (GLFW), Rendering Loop, Shader Pipeline (vertex + fragment), Memory Manager for VBOs/VAOs, Input State Management, Math (MVP matrices, lighting).

##### Main components
a. Application / Entry Point (Main)
b. Window & Context Manager (GLFW)
c. Render Loop & Scheduler
d. Resource Manager / Memory Manager (native buffers, VBOs, VAOs)
e. Shader Manager (GLSL 330 pipeline)
f. Math Library (JOML modules: Vector, Matrix)
g. Input Manager (keyboard/mouse state toggles)
h. GPU Driver / Hardware (OpenGL 3.3)

##### Relationships and interactions
- Main initializes Window Manager → creates GLFW window/context.
- Main enters Render Loop:
- Each iteration: Input Manager polls events → updates state.
- Resource Manager provides buffer handles to the GPU.
- Math Library computes MVP matrices → passed as uniforms to shaders.
- All subsystems depend on core LWJGL bindings.

##### Architectural patterns & design principles
- Modular subsystem pattern: separate concerns (windowing, rendering, resource management, math, input).
- Pipeline pattern for shaders (vertex → fragment).
- Game-loop pattern: fixed update + render loop.
- Manual resource lifetime management (allocate on init, free on exit).

##### Technologies, frameworks, libraries
- LWJGL 3 (GLFW bindings, OpenGL bindings)
- JOML for vector/matrix math
- GLSL 330 Core for shader code
- Gradle for build and dependency management

##### Essential details to capture
- Initialization phase (context creation, buffer allocation).
- Per-frame loop (input, update, render).
- Shader pipeline stages and uniform uploads.
- Memory/resource lifecycle (allocate VBO/VAO, free on shutdown).
- Boundary between managed Java heap and native GPU memory.

## Diagram (Mermaid)

```mermaid
graph TD
    %% Host Java Layer
    subgraph "Host (Java Layer)"
        Main["Main"]:::engine
        WindowManager["Window Manager"]:::engine
        InputManager["Input Manager"]:::engine
        RenderLoop["Render Loop"]:::engine
        ShaderManager["Shader Manager"]:::engine
        ResourceManager["Resource Manager"]:::engine
        MathLibrary["Math Library"]:::engine
    end

    %% Native and External Libraries
    subgraph "External Libraries"
        LWJGL["LWJGL 3"]:::external
        GLFW["GLFW"]:::external
        OpenGL["OpenGL 3.3"]:::external
        JOML["JOML"]:::external
    end

    %% Hardware Layer
    GPU["GPU Driver / Hardware"]:::hardware

    %% Build Configuration
    BuildGradle["build.gradle"]:::external
    SettingsGradle["settings.gradle"]:::external
    GradleWrapperProps["gradle/wrapper/gradle-wrapper.properties"]:::external
    GradleWrapperJar["gradle/wrapper/gradle-wrapper.jar"]:::external

    %% Initialization Flow
    Main -->|"initialize()"| WindowManager
    Main -->|"initialize()"| ResourceManager

    WindowManager -->|"glfwCreateWindow()"| GLFW
    WindowManager -->|uses| LWJGL

    ResourceManager -->|"allocateBuffers()"| OpenGL
    ResourceManager -->|uses| LWJGL

    %% Main Loop
    Main --> RenderLoop
    RenderLoop -->|"pollEvents()"| InputManager
    InputManager -->|"glfwPollEvents()"| GLFW
    InputManager -->|uses| LWJGL

    RenderLoop -->|"bindProgram() / draw()"| ShaderManager
    ShaderManager -->|"glUseProgram() / glUniformMatrix4fv()"| OpenGL
    ShaderManager -->|uses| LWJGL

    RenderLoop -->|"getBufferHandles()"| ResourceManager
    RenderLoop -->|"computeMVP()"| MathLibrary
    MathLibrary -->|provides matrices| ShaderManager
    MathLibrary -->|uses| JOML

    OpenGL -->|"draw commands"| GPU
    GLFW -->|"swapBuffers()"| GPU

    %% Dependencies
    Main -->|depends on| LWJGL
    WindowManager -->|depends on| LWJGL
    InputManager -->|depends on| LWJGL
    RenderLoop -->|depends on| LWJGL
    ShaderManager -->|depends on| LWJGL
    ResourceManager -->|depends on| LWJGL

    %% Build Files
    BuildGradle
    SettingsGradle
    GradleWrapperProps
    GradleWrapperJar

    %% Click Events
    click Main "https://github.com/xkostmand/pure3d/blob/main/src/main/java/com/chrys/pure3d/Main.java"
    click WindowManager "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click InputManager "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click RenderLoop "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click ShaderManager "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click ResourceManager "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click MathLibrary "https://github.com/xkostmand/pure3d/tree/main/src/main/java/com/chrys/pure3d/"
    click BuildGradle "https://github.com/xkostmand/pure3d/blob/main/build.gradle"
    click SettingsGradle "https://github.com/xkostmand/pure3d/blob/main/settings.gradle"
    click GradleWrapperProps "https://github.com/xkostmand/pure3d/blob/main/gradle/wrapper/gradle-wrapper.properties"
    click GradleWrapperJar "https://github.com/xkostmand/pure3d/blob/main/gradle/wrapper/gradle-wrapper.jar"

    %% Styles
    classDef engine fill:#c2f0c2,stroke:#333,stroke-width:1px
    classDef external fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef hardware fill:#e0e0e0,stroke:#333,stroke-width:1px
```
