# c3viche/skewer architecture

> Architecture diagram of the GitHub repository c3viche/skewer, 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/c3viche/skewer
- Repository: https://github.com/c3viche/skewer

## Overview

##### Project type and purpose
- This is Skewer, a native C++ physically‐based ray tracer library with three executable entry points:
- A command‐line renderer (apps/cli)
- A placeholder GUI renderer (apps/gui)
- A worker for distributed or batch rendering (apps/worker)
- Its purpose is to load scenes (meshes, materials), build acceleration structures, perform deep and layered path‐traced rendering, composite layers, and write image files.

##### File structure and architectural patterns
- Top-level “apps” directory holds each executable’s main.cc.
- “src” is organized by module:
- core – fundamental types (Vec3, Ray, Spectrum, RNG)
- io – file formats (PPM, OBJ via tiny_obj_loader, stb_image)
- scene – scene construction and camera
- materials – BSDF definitions, textures
- geometry – primitives, intersection tests
- accelerators – BVH spatial hierarchy
- integrators – rendering strategies (path tracing, normal visualization)
- film – image buffer and compositing
- session – orchestration: options, multi-threaded render loop
- compositor – deep‐data compositing (folders stubbed)
- Build is driven by CMake; external libraries are included via “external” or fetched (nlohmann/json).

##### Extracted runtime flow from README and code
- CLI app parses flags (–name, –help)
- Calls into RenderSession to load scene and options
- RenderSession builds BVH via the accelerator module
- For each pixel: integrator traces rays; on each hit, queries material.scatter, core RNG, geometry.intersect
- Samples accumulate in film/image_buffer
- Final film is written via io/image_io

##### Components
- CLI Frontend (apps/cli)
- RenderSession Manager (src/session)
- Scene Loader (src/io + src/scene)
- Accelerator (BVH builder/query)
- Geometry & Materials (src/geometry + src/materials)
- Integrator (path_trace, normals)
- Film & Compositor (src/film + src/compositor)
- I/O Layer (image_io, obj_loader)
- External Libraries (stb_image, tiny_obj_loader, nlohmann/json)
- (Optional) Worker & GUI frontends
b. Relationships / data flow:
1. CLI → RenderSession: pass RenderOptions
2. RenderSession → Scene Loader & Accelerator: load geometry, build BVH
3. RenderSession → Integrator: drive render loop
4. Integrator ↔ Accelerator/Geometry: ray intersection queries
5. Integrator ↔ Materials: shading
6. Integrator → Film Buffer: write samples
7. After all pixels: RenderSession → Compositor (for deep layers)
8. Compositor → I/O Layer: write final image (PPM/PNG)
c. Architectural patterns:
- Layered architecture: CLI → Session → Core modules → I/O
- Modular service boundaries per responsibility
- Data‐oriented flow: scene data → BVH → ray loops → buffer
d. Key technologies & frameworks:
- CMake for build orchestration
- std::thread or custom threading in session (inferred)
- stb_image(.h), tiny_obj_loader(.h) for asset I/O
- nlohmann/json for scene metadata (optional)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontends
    subgraph "Frontends"
        CLI["CLI Frontend"]:::frontend
        GUI["GUI Frontend"]:::frontend
        Worker["Worker Frontend"]:::frontend
    end

    %% Rendering Engine
    subgraph "Rendering Engine"
        subgraph "Session"
            RenderSession["RenderSession Manager"]:::engine
        end
        subgraph "Scene Loader"
            SceneLoader["Scene Loader"]:::engine
        end
        subgraph "Accelerator"
            BVH["BVH Accelerator"]:::engine
        end
        subgraph "Geometry"
            Geometry["Geometry Module"]:::engine
        end
        subgraph "Materials"
            Materials["Materials Module"]:::engine
        end
        subgraph "Integrator"
            Integrator["Integrator Module"]:::engine
        end
        subgraph "Film & Compositor"
            Film["Film Buffer"]:::engine
            Compositor["Compositor"]:::engine
        end
        subgraph "I/O Layer"
            IO["I/O Module"]:::engine
        end
    end

    %% Core Types & Utilities
    CoreUtils["Core Types & Utilities"]:::core

    %% External Libraries
    subgraph "External Libraries"
        STB["stb_image / stb_image_write"]:::external
        OBJLoaderLib["tiny_obj_loader"]:::external
    end

    %% Connections
    CLI -->|"pass RenderOptions"| RenderSession
    GUI -->|"pass RenderOptions"| RenderSession
    Worker -->|"pass RenderOptions"| RenderSession

    RenderSession -->|"loadScene()"| SceneLoader
    RenderSession -->|"buildBVH()"| BVH
    RenderSession -->|"driveLoop()"| Integrator

    Integrator -->|"traceRay()"| BVH
    Integrator -->|"intersect()"| Geometry
    Integrator -->|"scatter()"| Materials
    Integrator -->|"writeSample()"| Film

    BVH -->|"uses"| Geometry
    SceneLoader -->|"load meshes"| Geometry
    SceneLoader -->|"load materials"| Materials

    Film -->|"buffer data"| Compositor
    Compositor -->|"composeLayers()"| IO
    RenderSession -->|"finalize() via Compositor"| Compositor
    RenderSession -->|"writeImage()"| IO

    SceneLoader -->|"calls"| STB
    SceneLoader -->|"calls"| OBJLoaderLib
    IO -->|"image read/write"| STB

    RenderSession -->|"utilize"| CoreUtils
    Integrator -->|"random samples"| CoreUtils

    %% Click Events
    click CLI "https://github.com/c3viche/skewer/blob/main/apps/cli/main.cc"
    click GUI "https://github.com/c3viche/skewer/tree/main/apps/gui/"
    click Worker "https://github.com/c3viche/skewer/tree/main/apps/worker/"
    click RenderSession "https://github.com/c3viche/skewer/blob/main/src/session/render_session.h"
    click SceneLoader "https://github.com/c3viche/skewer/blob/main/src/io/scene_loader.h"
    click BVH "https://github.com/c3viche/skewer/blob/main/src/accelerators/bvh.h"
    click Geometry "https://github.com/c3viche/skewer/tree/main/src/geometry/"
    click Materials "https://github.com/c3viche/skewer/tree/main/src/materials/"
    click Integrator "https://github.com/c3viche/skewer/tree/main/src/integrators/"
    click Film "https://github.com/c3viche/skewer/tree/main/src/film/"
    click Compositor "https://github.com/c3viche/skewer/tree/main/src/compositor/"
    click IO "https://github.com/c3viche/skewer/tree/main/src/io/"
    click CoreUtils "https://github.com/c3viche/skewer/tree/main/src/core/"
    click STB "https://github.com/c3viche/skewer/blob/main/external/stb_image.h"
    click OBJLoaderLib "https://github.com/c3viche/skewer/blob/main/external/tiny_obj_loader.h"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#2980B9,color:#000;
    classDef engine fill:#ABEBC6,stroke:#27AE60,color:#000;
    classDef external fill:#F9E79F,stroke:#D68910,color:#000;
    classDef core fill:#D5D8DC,stroke:#85929E,color:#000;
```
