# jeasoon-osp/soft-renderer architecture

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

- Interactive diagram: https://gitdiagram.com/jeasoon-osp/soft-renderer
- Repository: https://github.com/jeasoon-osp/soft-renderer

## Overview

##### Main Components
- Android UI/App Layer: Represented by the Java/Kotlin code (e.g., MainActivity.kt and related graphic classes in com.jeasoon.gl.softrenderer) and Android layout files. This layer manages the app lifecycle, user input, and resource handling.
- JNI Bridge: The “glue” between the Java/Kotlin UI and the native C++ code. This includes interactions defined in the Android project (under app/src/main/java) that delegate calls to native functions.
- Native Rendering Engine (C++ Layer): The heart of the renderer located in app/src/main/cpp. Break this layer into submodules reflecting the internal architecture:
- GPU Simulation Module (under src/gpu): Contains classes such as BufferObject, Program, Texture, Raster, and their variants (e.g., PhongProgram, TextureProgram). These modules simulate aspects of the graphics pipeline.
- Graphics Module (under src/graphic): Handles camera, model, view, and pose management. Under “model” are further divisions, including integration of assimp (and its Android specific IO systems) to load 3D models.
- Mathematical Utilities (under src/math): Implements vectors, matrices, and assorted math functions supporting rendering transformations.
- Utility Module (under src/util): Provides error handling, logging (ALog, Error.cpp), and timing, which are critical for debugging and performance management.
- Asset Management: Located in app/src/main/assets, which holds the 3D model files (monkey.obj, monster.fbx) and possibly texture or other resource files used by the renderer.

##### Relationships and Data Flow
- From the JNI Bridge, illustrate the invocation of C++ native functions, which then branch into the rendering engine.
- How assets (models and textures) are fetched and loaded using assimp and stbi.

##### Important Architectural Patterns and Design Principles
- Layered Architecture: Emphasize the clear separation between the presentation (Android Java/Kotlin), business logic (native C++ rendering engine), and utility (math, gpu, and util modules).
- Modularity: Note that the native code is organized into self-contained modules that communicate through well-defined interfaces.
- JNI as a Communication Bridge: Illustrate how the JNI layer facilitates interaction between the high-level Android components and the performance-critical native modules.

##### Relevant Technologies and Frameworks
- Android Framework: For lifecycle management and UI.
- Kotlin/Java: Used in app/src/main/java.
- C++ with CMake: For native rendering code (note the CMakeLists.txt for building the C++ code).
- Assimp and STB Image Libraries: Mark these as external dependencies integrated into the model and texture loading subsystems.
- gradle and other build scripts: Indicate that the project is built as an Android app using Gradle and Kotlin DSL (build.gradle.kts).

- Clear labels on each component like “Android UI”, “JNI Bridge”, “Rendering Engine Core”, “GPU Simulation”, “Graphics (Camera/Model/View)”, “Math Utilities”, and “Asset Management”.
- Additionally, include notes or call-outs on important design details such as performance optimizations in the native code, the modular design for maintainability, and the specific role each third-party dependency plays.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Android Layer"
        AUI["Android UI/App Layer"]:::android
    end

    subgraph "JNI Bridge"
        J1["Camera JNI"]:::jni
        J2["Pose JNI"]:::jni
        J3["SurfaceView JNI"]:::jni
    end

    subgraph "Native Rendering Engine (C++)"
        NRE["Engine Core"]:::native
        GPU["GPU Simulation Module"]:::native
        GRAPH["Graphics Module (Camera/Model/View)"]:::native
        MATH["Math Utilities"]:::native
        UTIL["Utility Module"]:::native
    end

    subgraph "Assets & External Dependencies"
        ASSET["Asset Management"]:::asset
        EXT_ASSIMP["Assimp Library"]:::external
        EXT_STB["STB Image Library"]:::external
    end

    AUI -->|"callsJNI"| J1
    AUI -->|"callsJNI"| J2
    AUI -->|"callsJNI"| J3

    J1 -->|"bridgesTo"| NRE
    J2 -->|"bridgesTo"| NRE
    J3 -->|"bridgesTo"| NRE

    NRE -->|"delegatesTo"| GPU
    NRE -->|"delegatesTo"| GRAPH
    NRE -->|"delegatesTo"| MATH
    NRE -->|"delegatesTo"| UTIL

    GRAPH -->|"sendsModelData"| GPU
    MATH -->|"supports"| GPU

    ASSET -->|"providesAssets"| GRAPH
    EXT_ASSIMP -->|"assimpForModels"| GRAPH
    EXT_STB -->|"stbiForTextures"| GRAPH

    classDef android fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef jni fill:#F9E79F,stroke:#B7950B,stroke-width:2px;
    classDef native fill:#A9DFBF,stroke:#1D8348,stroke-width:2px;
    classDef asset fill:#F5B7B1,stroke:#922B21,stroke-width:2px;
    classDef external fill:#D7BDE2,stroke:#6C3483,stroke-width:2px;

    click AUI "https://github.com/jeasoon-osp/soft-renderer/blob/master/app/src/main/java/com/jeasoon/gl/softrenderer/MainActivity.kt"
    click J1 "https://github.com/jeasoon-osp/soft-renderer/blob/master/app/src/main/cpp/src/graphic/camera/Camera_jni.cpp"
    click J2 "https://github.com/jeasoon-osp/soft-renderer/blob/master/app/src/main/cpp/src/graphic/pose/Pose_jni.cpp"
    click J3 "https://github.com/jeasoon-osp/soft-renderer/blob/master/app/src/main/cpp/src/graphic/view/SoftGLSurfaceView_jni.cpp"
    click NRE "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp"
    click GPU "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/src/gpu"
    click GRAPH "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/src/graphic"
    click MATH "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/src/math"
    click UTIL "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/src/util"
    click ASSET "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/assets"
    click EXT_ASSIMP "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/include/assimp"
    click EXT_STB "https://github.com/jeasoon-osp/soft-renderer/tree/master/app/src/main/cpp/src/graphic/model/stbi"
```
