# rekcah97/chip8-emulator architecture

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

- Interactive diagram: https://gitdiagram.com/rekcah97/chip8-emulator
- Repository: https://github.com/rekcah97/chip8-emulator

## Overview

This is a CHIP-8 emulator: the user supplies a ROM path, the main loop loads it, polls mapped keyboard input, runs ten emulation cycles, ticks timers, and presents the framebuffer. The emulator core owns ROM loading, machine state, instruction fetch/dispatch, opcode behavior, and timers; the SDL platform handles window events, keyboard mapping, and display. The README documents the 64×32 display, 10× scaling, and standard opcode coverage. The sampled sources support the main runtime links; SDL is shown as an external dependency.

Main entry points: [`main.cpp`](https://github.com/rekcah97/chip8-emulator/blob/master/main.cpp) (Main loop), [`src/hardware.h`](https://github.com/rekcah97/chip8-emulator/blob/master/src/hardware.h) (Machine state), [`src/platform.cpp`](https://github.com/rekcah97/chip8-emulator/blob/master/src/platform.cpp) (Input polling), [`src/chip8.cpp`](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp) (ROM loader)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime loop"]
  node_entry["Main loop<br/>[main.cpp]"]
end

subgraph group_core["Emulator core"]
  node_loader["ROM loader<br/>[chip8.cpp]"]
  node_state["Machine state<br/>[hardware.h]"]
  node_cycle["Instruction cycle<br/>[chip8.cpp]"]
  node_dispatch["Opcode dispatch<br/>[chip8.cpp]"]
  node_handlers["Opcode handlers<br/>[chip8.cpp]"]
  node_timers["Timers<br/>[chip8.cpp]"]
end

subgraph group_platform["SDL platform"]
  node_input["Input polling<br/>[platform.cpp]"]
  node_display["Framebuffer display<br/>[platform.cpp]"]
end

node_user(("ROM user"))
node_rom["CHIP-8 ROM"]
node_sdl["SDL2"]

node_user -->|"supplies ROM path"| node_entry
node_entry -->|"loads ROM"| node_loader
node_rom -->|"provides bytes"| node_loader
node_loader -->|"writes RAM"| node_state
node_entry -->|"polls input"| node_input
node_input -->|"updates keys"| node_state
node_entry -->|"runs cycles"| node_cycle
node_cycle -->|"dispatches opcode"| node_dispatch
node_dispatch -->|"calls handler"| node_handlers
node_handlers -->|"updates machine"| node_state
node_entry -->|"ticks timers"| node_timers
node_timers -->|"updates timers"| node_state
node_entry -->|"presents screen"| node_display
node_display -->|"renders via"| node_sdl
node_input -->|"polls events"| node_sdl

click node_entry "https://github.com/rekcah97/chip8-emulator/blob/master/main.cpp"
click node_loader "https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp"
click node_state "https://github.com/rekcah97/chip8-emulator/blob/master/src/hardware.h"
click node_cycle "https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp"
click node_dispatch "https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp"
click node_handlers "https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp"
click node_timers "https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp"
click node_input "https://github.com/rekcah97/chip8-emulator/blob/master/src/platform.cpp"
click node_display "https://github.com/rekcah97/chip8-emulator/blob/master/src/platform.cpp"

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_entry,node_user toneBlue
class node_loader,node_state,node_cycle,node_dispatch,node_handlers,node_timers toneAmber
class node_input,node_display toneMint
class node_rom,node_sdl toneIndigo
```

## Components

### Runtime loop

- [Main loop](https://github.com/rekcah97/chip8-emulator/blob/master/main.cpp): `main.cpp`

### Emulator core

- [ROM loader](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp): `src/chip8.cpp`
- [Machine state](https://github.com/rekcah97/chip8-emulator/blob/master/src/hardware.h): `src/hardware.h`
- [Instruction cycle](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp): `src/chip8.cpp`
- [Opcode dispatch](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp): `src/chip8.cpp`
- [Opcode handlers](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp): `src/chip8.cpp`
- [Timers](https://github.com/rekcah97/chip8-emulator/blob/master/src/chip8.cpp): `src/chip8.cpp`

### SDL platform

- [Input polling](https://github.com/rekcah97/chip8-emulator/blob/master/src/platform.cpp): `src/platform.cpp`
- [Framebuffer display](https://github.com/rekcah97/chip8-emulator/blob/master/src/platform.cpp): `src/platform.cpp`

### Other components

- **ROM user**
- **CHIP-8 ROM**
- **SDL2**

## Connections

- ROM user → Main loop: supplies ROM path (evidence: `README.md`)
- Main loop → ROM loader: loads ROM (evidence: `main.cpp`)
- CHIP-8 ROM → ROM loader: provides bytes (evidence: `src/chip8.cpp`)
- ROM loader → Machine state: writes RAM (evidence: `src/chip8.cpp`)
- Main loop → Input polling: polls input (evidence: `main.cpp`)
- Input polling → Machine state: updates keys (evidence: `src/platform.cpp`)
- Main loop → Instruction cycle: runs cycles (evidence: `main.cpp`)
- Instruction cycle → Opcode dispatch: dispatches opcode (evidence: `src/chip8.cpp`)
- Opcode dispatch → Opcode handlers: calls handler (evidence: `src/chip8.cpp`)
- Opcode handlers → Machine state: updates machine (evidence: `src/chip8.cpp`)
- Main loop → Timers: ticks timers (evidence: `main.cpp`)
- Timers → Machine state: updates timers (evidence: `src/chip8.cpp`)
- Main loop → Framebuffer display: presents screen (evidence: `main.cpp`)
- Framebuffer display → SDL2: renders via (evidence: `src/platform.cpp`)
- Input polling → SDL2: polls events (evidence: `src/platform.cpp`)
