# pargame/metal-cube architecture

> Architecture diagram of the GitHub repository pargame/metal-cube, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/pargame/metal-cube
- Repository: https://github.com/pargame/metal-cube

## Overview

Metal Cube is a C++/metal-cpp macOS app that animates and presents a rotating 3D cube. Its main workflow is native window/view setup, per-frame world-state advancement, camera projection, GPU rendering, and presentation. The graph follows the README’s rendering stages and the sampled Renderer code; app-to-renderer wiring is documented, but the app source and several subsystems were not excerpted, so those links cite the README. The vendored metal-cpp bindings are represented as an API layer, not as separately mapped application features.

Main entry points: [`include/Renderer.hpp`](https://github.com/pargame/metal-cube/blob/main/include/Renderer.hpp) (Cube renderer), [`metal_rotating_cube.cpp`](https://github.com/pargame/metal-cube/blob/main/metal_rotating_cube.cpp) (Frame loop delegate), [`include/World.hpp`](https://github.com/pargame/metal-cube/blob/main/include/World.hpp) (World simulation), [`metal-cpp-extensions/MetalKit/MTKView.hpp`](https://github.com/pargame/metal-cube/blob/main/metal-cpp-extensions/MetalKit/MTKView.hpp) (Window and view)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["App lifecycle"]
  node_native_app["Native app setup"]
  node_window_view["Window and view<br/>[MTKView.hpp]"]
  node_frame_loop["Frame loop delegate"]
end

subgraph group_scene["Scene and projection"]
  node_world_geometry["Cube geometry<br/>[World.hpp]"]
  node_world_state["World simulation<br/>[World.hpp]"]
  node_math["Matrix operations<br/>[Math3D.hpp]"]
  node_observer["Camera projection<br/>[Observer.hpp]"]
end

subgraph group_gpu["Rendering pipeline"]
  node_shader_stages["Vertex and fragment shaders<br/>[Shaders.hpp]"]
  node_renderer["Cube renderer<br/>[Renderer.hpp]"]
end

subgraph group_bindings["Apple API bindings"]
  node_gpu_api["Metal API bindings"]
end

node_user(("User"))
node_apple_platform["Apple graphics platform"]
node_display["Rendered window"]

node_user -->|"launches"| node_native_app
node_native_app -->|"initializes"| node_window_view
node_native_app -->|"sets up"| node_frame_loop
node_frame_loop -->|"advances"| node_world_state
node_world_state -->|"transforms"| node_world_geometry
node_world_state -->|"uses matrices"| node_math
node_frame_loop -->|"renders frame"| node_renderer
node_frame_loop -->|"supplies camera"| node_observer
node_renderer -->|"reads state"| node_world_state
node_renderer -->|"projects through"| node_observer
node_renderer -->|"draws geometry"| node_world_geometry
node_renderer -->|"configures pipeline"| node_shader_stages
node_renderer -.->|"encodes commands"| node_gpu_api
node_gpu_api -.->|"calls"| node_apple_platform
node_window_view -.->|"requests frames"| node_renderer
node_renderer -->|"presents frame"| node_display
node_user -->|"views output"| node_display

click node_native_app "https://github.com/pargame/metal-cube/blob/main/metal_rotating_cube.cpp"
click node_window_view "https://github.com/pargame/metal-cube/blob/main/metal-cpp-extensions/MetalKit/MTKView.hpp"
click node_frame_loop "https://github.com/pargame/metal-cube/blob/main/metal_rotating_cube.cpp"
click node_world_geometry "https://github.com/pargame/metal-cube/blob/main/include/World.hpp"
click node_world_state "https://github.com/pargame/metal-cube/blob/main/include/World.hpp"
click node_math "https://github.com/pargame/metal-cube/blob/main/include/Math3D.hpp"
click node_observer "https://github.com/pargame/metal-cube/blob/main/include/Observer.hpp"
click node_shader_stages "https://github.com/pargame/metal-cube/blob/main/include/Shaders.hpp"
click node_renderer "https://github.com/pargame/metal-cube/blob/main/include/Renderer.hpp"
click node_gpu_api "https://github.com/pargame/metal-cube/blob/main/metal-cpp/Metal/MTLRenderCommandEncoder.hpp"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_native_app,node_window_view,node_frame_loop,node_user toneBlue
class node_world_geometry,node_world_state,node_math,node_observer toneAmber
class node_shader_stages,node_renderer toneMint
class node_gpu_api toneRose
class node_apple_platform,node_display toneIndigo
```

## Components

### App lifecycle

- [Native app setup](https://github.com/pargame/metal-cube/blob/main/metal_rotating_cube.cpp): `metal_rotating_cube.cpp`
- [Window and view](https://github.com/pargame/metal-cube/blob/main/metal-cpp-extensions/MetalKit/MTKView.hpp): `metal-cpp-extensions/MetalKit/MTKView.hpp`
- [Frame loop delegate](https://github.com/pargame/metal-cube/blob/main/metal_rotating_cube.cpp): `metal_rotating_cube.cpp`

### Scene and projection

- [Cube geometry](https://github.com/pargame/metal-cube/blob/main/include/World.hpp): `include/World.hpp`
- [World simulation](https://github.com/pargame/metal-cube/blob/main/include/World.hpp): `include/World.hpp`
- [Matrix operations](https://github.com/pargame/metal-cube/blob/main/include/Math3D.hpp): `include/Math3D.hpp`
- [Camera projection](https://github.com/pargame/metal-cube/blob/main/include/Observer.hpp): `include/Observer.hpp`

### Rendering pipeline

- [Vertex and fragment shaders](https://github.com/pargame/metal-cube/blob/main/include/Shaders.hpp): `include/Shaders.hpp`
- [Cube renderer](https://github.com/pargame/metal-cube/blob/main/include/Renderer.hpp): `include/Renderer.hpp`

### Apple API bindings

- [Metal API bindings](https://github.com/pargame/metal-cube/blob/main/metal-cpp/Metal/MTLRenderCommandEncoder.hpp): `metal-cpp/Metal/MTLRenderCommandEncoder.hpp`

### Other components

- **User**
- **Apple graphics platform**
- **Rendered window**

## Connections

- User → Native app setup: launches (evidence: `README.md`)
- Native app setup → Window and view: initializes (evidence: `README.md`)
- Native app setup → Frame loop delegate: sets up (evidence: `README.md`)
- Frame loop delegate → World simulation: advances (evidence: `README.md`)
- World simulation → Cube geometry: transforms (evidence: `README.md`)
- World simulation → Matrix operations: uses matrices (evidence: `include/World.hpp`)
- Frame loop delegate → Cube renderer: renders frame (evidence: `README.md`)
- Frame loop delegate → Camera projection: supplies camera (evidence: `README.md`)
- Cube renderer → World simulation: reads state (evidence: `README.md`)
- Cube renderer → Camera projection: projects through (evidence: `README.md`)
- Cube renderer → Cube geometry: draws geometry (evidence: `README.md`)
- Cube renderer → Vertex and fragment shaders: configures pipeline (evidence: `README.md`)
- Cube renderer → Metal API bindings: encodes commands
- Metal API bindings → Apple graphics platform: calls
- Window and view → Cube renderer: requests frames
- Cube renderer → Rendered window: presents frame (evidence: `README.md`)
- User → Rendered window: views output (evidence: `README.md`)
