# jbikker/tinybvh architecture

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

- Interactive diagram: https://gitdiagram.com/jbikker/tinybvh
- Repository: https://github.com/jbikker/tinybvh

## Overview

##### Main components
- Core BVH Library:
- tiny_bvh.h: The central header implementing the BVH construction, traversal, and conversion functionality.
- Source files like tiny_bvh_anim.cpp, tiny_bvh_collide.cpp, tiny_bvh_minimal.cpp, tiny_bvh_renderer.cpp, etc., which demonstrate different aspects of BVH usage.
- Variants for different BVH layouts (e.g., BVH, BVH4_CPU, BVH8_CPU, BVH_GPU, and templated MBVH).
- OpenCL Integration:
- tiny_ocl.h encapsulates OpenCL device selection, kernel compilation, and host/device buffer management.
- The related external OpenCL directories (and corresponding binaries) indicate how the library wires into vendor-specific drivers.
- External and Third-Party Dependencies:
- Bundled libraries and headers like Embree (for additional ray-tracing implementations), GLFW, and templ8 (for sample rendering).
- OpenCL libraries and helper utilities found under “external/OpenCL” and “tmpl8/lib/OpenCL”.
- Demo/Example Applications:
- Various demos such as the ASCII test renderer (tiny_bvh_minimal.cpp), fenster-based bitmap renderer (tiny_bvh_fenster.cpp), GPU demos (tiny_bvh_gpu.cpp, tiny_bvh_gpu2.cpp), path tracer (tiny_bvh_pt.cpp), and speed test (tiny_bvh_speedtest.cpp).
- Visual Studio solution files and CMakeLists.txt for building the project.
- Build & Deployment Artifacts:
- CMakeLists.txt and Visual Studio project files under vcproj/ and tiny_bvh_test.sln.
- GitHub workflows under .github/workflows for CI.

##### Relationships and interactions
- The core BVH library acts as the engine that builds and traverses the BVH structure. It includes multiple builders which are selectable (plain SAH, AVX optimized, spatial splits, etc.) and conversion functions to switch between different BVH layouts.
- The optional tiny_ocl component interacts with the BVH library to offload BVH traversal via GPU kernels. This integration is supported by linking against the included OpenCL library from “external/OpenCL” (and similarly templated versions under tmpl8).
- Demo applications (standalone source files and VS solutions) act as clients that utilize the BVH library (and sometimes the OpenCL extension) to illustrate different capabilities, such as rendering, collision detection, and performance measurement.
- External dependencies (like Embree and GLFW) are used to showcase integration with other well-known technologies and to provide functionality (e.g., graphical window context, rendering pipelines).

##### Architectural patterns/design principles
- The design emphasizes a modular, header-only approach for the core library. Components are loosely coupled so that tiny_bvh.h remains dependency-free unless OpenCL-specific functionality is required.
- Clear separation between CPU and GPU paths is maintained via different file sets and API calls (for example, BVH_GPU versus BVH4_CPU).
- The use of a “bring your own vector types” (BYOVT) approach indicates a design that emphasizes extensibility and flexibility.
- The presence of multiple demos and build configurations illustrates adherence to cross-platform development principles.

- Clear labels for every component (e.g., “BVH Core”, “BVH GPU Module”, “tiny_ocl”, “OpenCL Drivers”, “Embree Integration”, “Demo Renderers”).
- Annotations that note architectural patterns (dependency injection, modular header-only design) and the design’s scalability for adding further BVH layouts or integration with additional APIs.
- A section for build/development processes (CI via GitHub workflows, Visual Studio/CMake builds) to give context on how the code is integrated and deployed.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Core Libraries"
        direction TB
        coreHeader["BVH Core\n(tiny_bvh.h)"]:::core
        subgraph "BVH Source Files"
            direction TB
            bvhAnim["BVH Animation\n(tiny_bvh_anim.cpp)"]:::core
            bvhCollide["BVH Collision\n(tiny_bvh_collide.cpp)"]:::core
            bvhMinimal["BVH Minimal\n(tiny_bvh_minimal.cpp)"]:::core
            bvhRenderer["BVH Renderer\n(tiny_bvh_renderer.cpp)"]:::core
            bvhCustom["BVH Custom\n(tiny_bvh_custom.cpp)"]:::core
            bvhCustomDouble["BVH Custom Double\n(tiny_bvh_custom_double.cpp)"]:::core
            bvhAnimDouble["BVH Anim Double\n(tiny_bvh_anim_double.cpp)"]:::core
        end
        oclModule["tiny_ocl Integration\n(tiny_ocl.h)"]:::ocl
    end

    subgraph "External Dependencies"
        direction TB
        openCLExt["OpenCL External\n(external/OpenCL)"]:::ext
        tmpl8OpenCL["tmpl8 OpenCL\n(tmpl8/lib/OpenCL)"]:::ext
        embreeDep["Embree\n(external/embree)"]:::ext
        glfwDep["GLFW\n(tmpl8/lib/GLFW)"]:::ext
    end

    subgraph "Demo/Example Applications"
        direction TB
        cpuDemo["CPU Demo Apps"]:::demo
        gpuDemo["GPU Demo Apps"]:::demo
        interopDemo["Interop Demo\n(tmpl8/tiny_bvh_interop.vcxproj)"]:::demo
    end

    subgraph "Build & Deployment"
        direction TB
        cmakeConfig["CMakeLists.txt"]:::build
        vsSolution["Visual Studio Solution\n(tiny_bvh_test.sln)"]:::build
        vcprojFiles["VC Projects\n(vcproj/)"]:::build
        ciDeploy["CI/CD Workflow\n(.github/workflows/tinybvh_sdk_ci.yml)"]:::build
    end

    %% Relationships between Core Libraries and Demo Applications
    cpuDemo -->|"Utilizes"| coreHeader
    gpuDemo -->|"Utilizes"| oclModule
    interopDemo -->|"Interop with"| coreHeader

    %% Core internal relationships
    coreHeader -->|"Builds/Traverses"| bvhAnim
    coreHeader -->|"Builds/Traverses"| bvhCollide
    coreHeader -->|"Builds/Traverses"| bvhMinimal
    coreHeader -->|"Builds/Traverses"| bvhRenderer
    coreHeader -->|"Builds/Traverses"| bvhCustom
    coreHeader -->|"Builds/Traverses"| bvhCustomDouble
    coreHeader -->|"Builds/Traverses"| bvhAnimDouble
    coreHeader -->|"CallsGPU"| oclModule

    %% OpenCL integration relationships
    oclModule -->|"Uses"| openCLExt
    oclModule -->|"Uses"| tmpl8OpenCL

    %% External dependencies used by demos
    cpuDemo -->|"RendersWith"| glfwDep
    gpuDemo -->|"RendersWith"| glfwDep
    cpuDemo -->|"AcceleratedBy"| embreeDep

    %% Build & Deployment linking
    cmakeConfig --- coreHeader
    vsSolution --- coreHeader
    vcprojFiles --- coreHeader
    ciDeploy --- cmakeConfig
    cpuDemo -->|"BuiltVia"| vsSolution
    gpuDemo -->|"BuiltVia"| vsSolution
    interopDemo -->|"BuiltVia"| vsSolution

    %% Click Events for Core BVH Library
    click coreHeader "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh.h"
    click bvhAnim "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_anim.cpp"
    click bvhCollide "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_collide.cpp"
    click bvhMinimal "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_minimal.cpp"
    click bvhRenderer "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_renderer.cpp"
    click bvhCustom "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_custom.cpp"
    click bvhCustomDouble "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_custom_double.cpp"
    click bvhAnimDouble "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_anim_double.cpp"

    %% Click Events for OpenCL Integration
    click oclModule "https://github.com/jbikker/tinybvh/blob/main/tiny_ocl.h"
    click openCLExt "https://github.com/jbikker/tinybvh/tree/main/external/OpenCL"
    click tmpl8OpenCL "https://github.com/jbikker/tinybvh/tree/main/tmpl8/lib/OpenCL"

    %% Click Events for External Dependencies
    click embreeDep "https://github.com/jbikker/tinybvh/tree/main/external/embree"
    click glfwDep "https://github.com/jbikker/tinybvh/tree/main/tmpl8/lib/GLFW"

    %% Click Events for Demo Applications and Build Artifacts
    click interopDemo "https://github.com/jbikker/tinybvh/blob/main/tmpl8/tiny_bvh_interop.vcxproj"
    click cpuDemo "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_minimal.cpp"
    click gpuDemo "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_gpu.cpp"
    click cmakeConfig "https://github.com/jbikker/tinybvh/blob/main/CMakeLists.txt"
    click vsSolution "https://github.com/jbikker/tinybvh/blob/main/tiny_bvh_test.sln"
    click vcprojFiles "https://github.com/jbikker/tinybvh/tree/main/vcproj"
    click ciDeploy "https://github.com/jbikker/tinybvh/blob/main/.github/workflows/tinybvh_sdk_ci.yml"

    classDef core fill:#f9f,stroke:#333,stroke-width:2px;
    classDef ocl fill:#ccf,stroke:#333,stroke-width:2px;
    classDef ext fill:#cfc,stroke:#333,stroke-width:2px;
    classDef demo fill:#fc9,stroke:#333,stroke-width:2px;
    classDef build fill:#cff,stroke:#333,stroke-width:2px;
```
