# mmp/pbrt-v4 architecture

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

## Overview

##### Project Type and Purpose
- pbrt-v4 is a high-performance, physically based rendering system intended for realistic image synthesis and is used both in academic and professional contexts.
- It supports both CPU-based and GPU-based (CUDA/OptiX) rendering with advanced features like spectral rendering, volumetric scattering, and new light sampling strategies.

##### File Structure to Identify Main Components
- Top-level build and configuration files (CMakeLists.txt, cmake/ folder, .github workflows) indicate the use of CMake as the build system and CI/CD integration.
- The “src” directory is organized into:
- The “pbrt” subdirectory that contains the core renderer code.
- “pbrt/cpu” for CPU-specific rendering implementations.
- “pbrt/gpu” for GPU-specific modules including OptiX integration and CUDA kernels.
- “pbrt/cmd” for command-line utilities (scene conversion, testing, etc).
- “pbrt/util” providing the common utilities (math, logging, file operations, error handling, etc).
- “src/ext” contains third-party libraries and dependencies (e.g., double-conversion, glEnd loading helpers like glad and GLFW, testing frameworks like gtest, image libraries, etc). They are clearly used to underpin many of the renderer’s functionalities without reinventing the wheel.

##### Readme Insights for Architectural Highlights
- The README emphasizes major architectural components:
- Spectral rendering and handling of scene description for physical correctness.
- Separation between “CPU” and “GPU” paths with shared core algorithms.
- Dedicated integrators for various lighting paths including volumetric and many-light sampling.
- Support for external tools like the tev image viewer to display images in real time.
- It also describes that pbrt’s design is modular (refactored APIs, standalone functions for sampling, etc.) and relies heavily on modern C++ (C++17) as well as third-party libraries.

- Following main components:
- Build and Deployment: CMake build scripts, CI workflows (GitHub Actions)
- Core Engine: The “pbrt” core folder containing shared data structures and common utilities (under “pbrt/util”).
- CPU Rendering Path: “pbrt/cpu” contains integrators, rendering loops, and hardware-specific optimizations for CPU.
- GPU Rendering Path: “pbrt/gpu” with CUDA/OptiX integration for fast rendering on supported GPUs.
- Scene Parsing and Command Tools: “pbrt/cmd” for processing scene files, conversions (including pbrt file format upgrade utilities).
- External Dependencies: “src/ext” containing third-party libraries for tasks like image processing, math functions, window/context management, and testing.
- Testing and Validation: The “src/ext/gtest” along with numerous test files in the “pbrt” directories ensure system correctness.

- Relationships and Interactions:
- Input: Scene files (in pbrt file format) are ingested via the command-line interface (pbrt executable under “pbrt/cmd”).
- Scene Processing: The parser and scene converters (found in “pbrt/parser.cpp” and related utilities) break down the scene into data structures.
- Data Flow: The core engine (using data from “pbrt/util”) dispatches rendering jobs to either the CPU path (“pbrt/cpu”) or GPU path (“pbrt/gpu”), based on command-line flags or configuration.
- External Tools: An additional component represents the connection to the external viewer (tev) via network sockets for progressive image display.

- Architectural Patterns & Technologies:
- Modular design: Clear separation of core algorithms and specific rendering backends.
- Dual-path processing: Distinct flow paths for CPU and GPU rendering.
- Utilization of third-party libraries: Integration of external libraries (e.g., GLFW, glad, OpenEXR) enhances functionality without complicating the core code.
- Testing and CI integration ensures code quality and stability.

##### Elements
- Scene input → Scene Parser → Core Engine → (branching to) CPU/GPU Renderer.
- External data (e.g., camera, lighting models) and third-party libraries integrated into the core.
- Core components versus external dependencies.
- Build/integration modules (e.g., CI/CD pipelines) versus runtime components.
- Annotations for key technologies like C++17, CUDA, OptiX, and CMake.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Build & Deployment"
        BD["Build & Deployment"]:::build
    end

    subgraph "Scene Ingestion"
        SI["Scene Input"]:::input
        CMD["Command Tools"]:::command
        SP["Scene Parser"]:::command
    end

    subgraph "Core Engine"
        CE["pbrt Core"]:::core
        UTIL["Utilities"]:::core
    end

    subgraph "Rendering Path"
        CPU["CPU Rendering"]:::rendering
        GPU["GPU Rendering"]:::rendering
    end

    subgraph "External"
        ED["External Dependencies"]:::external
        TEST["Testing & Validation"]:::testing
        TV["External Viewer (tev)"]:::external
    end

    SI -->|"ingests"| CMD
    CMD -->|"processes"| SP
    SP -->|"feeds"| CE
    CE -->|"integrates"| UTIL
    BD -->|"builds"| CE
    CE -->|"dispatches job to"| CPU
    CE -->|"dispatches job to"| GPU
    CPU -->|"outputs image to"| TV
    ED -->|"supports"| CE
    ED -->|"provides tests for"| TEST

    click BD "https://github.com/mmp/pbrt-v4/blob/master/CMakeLists.txt"
    click CE "https://github.com/mmp/pbrt-v4/tree/master/src/pbrt/"
    click CMD "https://github.com/mmp/pbrt-v4/tree/master/src/pbrt/cmd/"
    click SP "https://github.com/mmp/pbrt-v4/blob/master/src/pbrt/parser.cpp"
    click CPU "https://github.com/mmp/pbrt-v4/tree/master/src/pbrt/cpu/"
    click GPU "https://github.com/mmp/pbrt-v4/tree/master/src/pbrt/gpu/"
    click ED "https://github.com/mmp/pbrt-v4/tree/master/src/ext/"
    click TEST "https://github.com/mmp/pbrt-v4/tree/master/src/ext/gtest/"

    classDef build fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef core fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef rendering fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef command fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef testing fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef input fill:#fefefe,stroke:#333,stroke-width:2px;

    class BD build;
    class CE,UTIL core;
    class CPU,GPU rendering;
    class CMD,SP command;
    class ED,TV external;
    class TEST testing;
    class SI input;
```
