# tathack-tathva/chip8-emulator architecture

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

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

## Overview

This is a desktop Chip-8 virtual machine: the user supplies a ROM, the SDL-driven application loads it and runs instructions, then presents the emulated display, keypad input, and sound. The graph separates application I/O, VM state and execution, and SDL output. The README documents the full opcode set and display/audio capabilities; the sampled implementation excerpts are partial, so detailed opcode wiring is not expanded.

Main entry points: [`src/main.cpp`](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp) (Emulator loop), [`src/chip8.cpp`](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp) (Instruction cycle), [`src/chip8.h`](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h) (Pixel display), [`roms`](https://github.com/tathack-tathva/chip8-emulator/tree/main/roms) (Chip-8 ROMs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_app["Application I/O"]
  node_main["Emulator loop<br/>[main.cpp]"]
end

subgraph group_vm["Chip-8 VM"]
  node_loader["ROM loading<br/>[chip8.cpp]"]
  node_state["VM state<br/>[chip8.h]"]
  node_execution["Instruction cycle<br/>[chip8.cpp]"]
  node_display["Pixel display<br/>[chip8.h]"]
  node_keys["Keypad state<br/>[chip8.h]"]
  node_timers["Timers<br/>[chip8.cpp]"]
end

subgraph group_media["SDL Media"]
  node_sdl["SDL2"]
  node_input["Input handling<br/>[main.cpp]"]
  node_renderer["Graphics rendering<br/>[main.cpp]"]
  node_audio["Beep generation<br/>[main.cpp]"]
end

node_user(("User"))
node_roms["Chip-8 ROMs"]

node_user -->|"starts with ROM"| node_main
node_roms -->|"ROM data"| node_loader
node_main -->|"loads ROM"| node_loader
node_main -->|"runs cycles"| node_execution
node_execution -->|"updates state"| node_state
node_execution -->|"draws sprites"| node_display
node_execution -->|"checks keys"| node_keys
node_execution -->|"updates timers"| node_timers
node_sdl -->|"delivers events"| node_input
node_input -->|"sets key state"| node_keys
node_main -->|"polls events"| node_input
node_main -->|"draws frame"| node_renderer
node_renderer -->|"reads pixels"| node_display
node_main -->|"reads sound timer"| node_timers
node_main -->|"sets beep state"| node_audio
node_sdl -->|"invokes callback"| node_audio
node_main -->|"initializes media"| node_sdl

click node_roms "https://github.com/tathack-tathva/chip8-emulator/tree/main/roms"
click node_main "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp"
click node_loader "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp"
click node_state "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h"
click node_execution "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp"
click node_display "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h"
click node_keys "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h"
click node_timers "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp"
click node_input "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp"
click node_renderer "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp"
click node_audio "https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.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_main,node_user toneBlue
class node_loader,node_state,node_execution,node_display,node_keys,node_timers toneAmber
class node_sdl,node_input,node_renderer,node_audio toneMint
class node_roms toneTeal
```

## Components

### Application I/O

- [Emulator loop](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp): `src/main.cpp`

### Chip-8 VM

- [ROM loading](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp): `src/chip8.cpp`
- [VM state](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h): `src/chip8.h`
- [Instruction cycle](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp): `src/chip8.cpp`
- [Pixel display](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h): `src/chip8.h`
- [Keypad state](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.h): `src/chip8.h`
- [Timers](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/chip8.cpp): `src/chip8.cpp`

### SDL Media

- **SDL2**
- [Input handling](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp): `src/main.cpp`
- [Graphics rendering](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp): `src/main.cpp`
- [Beep generation](https://github.com/tathack-tathva/chip8-emulator/blob/main/src/main.cpp): `src/main.cpp`

### Other components

- **User**
- [Chip-8 ROMs](https://github.com/tathack-tathva/chip8-emulator/tree/main/roms): `roms`

## Connections

- User → Emulator loop: starts with ROM
- Chip-8 ROMs → ROM loading: ROM data
- Emulator loop → ROM loading: loads ROM
- Emulator loop → Instruction cycle: runs cycles
- Instruction cycle → VM state: updates state
- Instruction cycle → Pixel display: draws sprites
- Instruction cycle → Keypad state: checks keys
- Instruction cycle → Timers: updates timers
- SDL2 → Input handling: delivers events
- Input handling → Keypad state: sets key state
- Emulator loop → Input handling: polls events
- Emulator loop → Graphics rendering: draws frame
- Graphics rendering → Pixel display: reads pixels
- Emulator loop → Timers: reads sound timer
- Emulator loop → Beep generation: sets beep state
- SDL2 → Beep generation: invokes callback
- Emulator loop → SDL2: initializes media