# raster-gpu/raster-i architecture

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

- Interactive diagram: https://gitdiagram.com/raster-gpu/raster-i
- Repository: https://github.com/raster-gpu/raster-i

## Overview

##### Project Type and Purpose
- This is a hardware renderer built for real-time rasterization based on a tiled, deferred rendering methodology (specifically inspired by the Pineda style rasterizer). It combines parts written in Chisel HDL (for the overall system and glue logic) with a graphics pipeline implemented in Vitis HLS.
- The purpose is to create an FPGA-based GPU that supports features like hardware-accelerated transform & lighting, deferred Phong shading, MSAA anti-aliasing, and several display effects (dithering and gamma correction) while managing multiple clock domains (system, graphics, and display).

##### Analyzing the File Structure
- At the top level, you have key directories such as:
- “renderer”: Contains the HLS graphics pipeline source files, configuration files (.clang-format, hls_config.cfg) and headers for math utilities, framebuffer handling, meshes, textures, etc.
- “system”: Contains the main integration code (Scala sources in system/src/main/scala for Chisel HDL) and additional hardware building blocks (the Vivado design with IP blocks, TCL scripts, and constraint files).
- “docs”: Documentation (with README and possibly other documents).
- The file tree reveals a clear separation between the rendering pipeline (HLS) and system integration (Chisel HDL and Vivado projects) – each playing a specific role in the overall architecture.
- The presence of build scripts (sbt, Tcl scripts) and configuration files indicates a multi-step build flow: compile HDL, synthesize HLS, then integrate everything in Vivado.

##### Key Architectural Insights from the README
- The rendering unit is split into three main stages:
1. Vertex Transformation (reading transformation parameters, updating mesh vertices)
2. Pixel Interpolation (using eight pipelined interpolator pipelines for MSAA and G-buffer generation)
3. Deferred Shading (executing lighting calculations using the Phong model)
- The display unit is responsible for reading and processing the framebuffer (applying optional ordered dithering and gamma correction) in sync with the VGA signal.
- A framebuffer swapper “glues” the two clock domains by synchronizing the writing (by the renderer) and reading (by the display) of framebuffers.

a. Main Components to Include:
- Rendering Subsystem (Graphics Domain):
- HLS Graphics Pipeline (from “renderer” folder) divided into three stages: Vertex Transformation, Pixel Interpolation, Deferred Shading.
- Temporary Buffers including G-buffers and tile buffers.
- Subsystem (Display Domain):
- VGA Controller (with HD signal timing, horizontal/vertical blanking intervals)
- Post-processing Units (ordered dithering using a Bayer matrix, gamma correction)
- Framebuffer Swapper:
- Acts as a bridge between the graphics and display domains.
- System / Control Subsystem (System Domain):
- Chisel HDL modules (located in system/src/main/scala) such as Fb.scala, Trinity.scala, and display controllers.
- System controller managing overall synchronization.
- Memory Subsystem:
- DRAM/VRAM controller with its dual-port access, managed via an AXI interconnect.
- FPGA Integration Infrastructure:
- Vivado project illustrating the interconnection of IP cores (clock wizard, AXI interconnect, reset modules, etc.) along with the HLS engine and user-defined renderer IP.

b. Relationships and Data Flow:
- Controls from system controllers that trigger synchronization (e.g., swapping framebuffers during vertical blanking intervals).
- AXI interconnect linking both the graphics and display clock domains with the memory controller.

c. Architectural Patterns and Design Principles:
- Clock domain crossings, emphasizing the separation of tasks (rendering vs. display).
- Demonstrate pipelined processing within the rendering unit – illustrate stages sequentially within the graphics domain.
- Feedback loops (like reading transformation data to update vertices) to capture internal data dependencies.
- Use a modular approach to illustrate each subsystem/component.

d. Relevant Technologies / Frameworks:
- HLS for the graphics pipeline (Vitis HLS)
- Chisel HDL for the system integration (Scala code)
- Vivado Tools provided IP cores (AXI interconnect, clocking and reset modules)
- FPGA board details (Digilent Arty A7-100T)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rendering Subsystem (Graphics Domain)
    subgraph "Rendering Subsystem (Graphics Domain)"
        R1["HLS Graphics Pipeline"]:::graphics
        R2["Vertex Transformation Stage"]:::graphics
        R3["Pixel Interpolation Stage (MSAA,G-buffer)"]:::graphics
        R4["Deferred Shading Stage"]:::graphics
        R5["Temporary Buffers (G-buffers)"]:::graphics
        R6["HLS Config"]:::graphics
    end

    %% Display Subsystem (Display Domain)
    subgraph "Display Subsystem (Display Domain)"
        D1["VGA Controller"]:::display
        D2["Post-processing Unit (Dithering&GammaCorrection)"]:::display
    end

    %% Framebuffer Swapper (bridging Graphics and Display)
    FBS["Framebuffer Swapper"]:::system

    %% System / Control Subsystem (System Domain)
    subgraph "System / Control Subsystem (System Domain)"
        S1["Chisel HDL Integration"]:::system
        S2["Framebuffer Control (Fb.scala)"]:::system
        S3["Control Logic (Trinity.scala)"]:::system
        S4["Renderer Coordination (Renderer.scala)"]:::system
    end

    %% Memory Subsystem
    subgraph "Memory Subsystem"
        M1["AXI Interconnect"]:::memory
        M2["DRAM/VRAM Controller"]:::memory
        M3["AXI Utils"]:::memory
        M4["Vivado VRAM IP Blocks"]:::memory
    end

    %% FPGA Integration Infrastructure
    subgraph "FPGA Integration Infrastructure"
        I1["Vivado Build Script"]:::integration
        I2["Top-level Integration (top.v)"]:::integration
        I3["Clock Wizard"]:::integration
        I4["Reset Module"]:::integration
    end

    %% Internal Rendering Pipeline Flow
    R1 -->|"stage"| R2
    R2 -->|"stage"| R3
    R3 -->|"stage"| R4
    R4 -->|"stage"| R5
    R1 -->|"configures"| R6

    %% Data Flow Connections
    R5 -->|"render=>framebuffer"| FBS
    FBS -->|"framebuffer=>display"| D1

    %% System/Control Influence on Swapper
    S1 -->|"sync"| FBS
    S2 -->|"control"| FBS
    S3 -->|"control"| FBS

    %% Memory Requests from Multiple Domains
    R1 -->|"req"| M1
    D2 -->|"req"| M1
    S1 -->|"ctrl"| M1

    %% Memory Internal Flow
    M1 --> M2
    M1 --> M3
    M2 --> M4

    %% FPGA Integration and System Connection
    I2 -->|"integrates"| S1
    I2 -->|"integrates"| M1
    I3 -->|"clocks"| I2
    I4 -->|"reset"| I2

    %% Click Events for Component Mapping
    click R1 "https://github.com/raster-gpu/raster-i/blob/main/renderer/src/top.cpp"
    click R6 "https://github.com/raster-gpu/raster-i/blob/main/renderer/hls_config.cfg"
    click D1 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/display/Vga.scala"
    click D2 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/display/Dithering.scala"
    click S2 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/core/Fb.scala"
    click S3 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/core/Trinity.scala"
    click S4 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/renderer/Renderer.scala"
    click M3 "https://github.com/raster-gpu/raster-i/blob/main/system/src/main/scala/utils/Axi.scala"
    click M4 "https://github.com/raster-gpu/raster-i/tree/main/system/vivado/bd/vram/ip"
    click I1 "https://github.com/raster-gpu/raster-i/blob/main/system/vivado/build.tcl"
    click I2 "https://github.com/raster-gpu/raster-i/blob/main/system/vivado/verilog/top.v"
    click I3 "https://github.com/raster-gpu/raster-i/blob/main/system/vivado/ip/clk_wiz/clk_wiz.xci"
    click I4 "https://github.com/raster-gpu/raster-i/blob/main/system/vivado/ip/proc_sys_rst/proc_sys_rst.xci"

    %% Styles for Color Coding
    classDef graphics fill:#d0e8ff,stroke:#0275d8,stroke-width:2px;
    classDef display fill:#d4edda,stroke:#28a745,stroke-width:2px;
    classDef system fill:#ffeeba,stroke:#f0ad4e,stroke-width:2px;
    classDef memory fill:#fbdcdc,stroke:#d9534f,stroke-width:2px;
    classDef integration fill:#d9edf7,stroke:#5bc0de,stroke-width:2px;
```
