# Graphics System

ModuOS supports both **legacy VGA text mode** and **pixel framebuffer graphics**.

The modern graphics path is based on a kernel framebuffer abstraction plus **SQRM GPU modules** (loadable drivers) that provide a framebuffer to the rest of the system.

## Graphics Overview

At a high level:

- **Early boot / fallback**: VGA text mode (`0xB8000`)
- **Graphics mode**: a linear framebuffer (LFB) provided by a GPU driver
  - The framebuffer is consumed by the kernel graphics subsystem (2D drawing, console, UI)

## VGA Text Mode

**Resolution**: 80 columns × 25 rows
**Character cells**: 16 colors foreground + 8 colors background

### VGA Driver

**File**: `src/drivers/graphics/VGA.c`

### VGA Memory

**Memory-mapped**: `0xB8000`

**Character format** (16-bit):
```
Bits 0-7:   ASCII character
Bits 8-11:  Foreground color
Bits 12-14: Background color
Bit 15:     Blink attribute
```

### Color Codes

| Code | Color |
|------|-------|
| 0x0 | Black |
| 0x1 | Blue |
| 0x2 | Green |
| 0x3 | Cyan |
| 0x4 | Red |
| 0x5 | Magenta |
| 0x6 | Brown |
| 0x7 | Light Gray |
| 0x8 | Dark Gray |
| 0x9 | Light Blue |
| 0xA | Light Green |
| 0xB | Light Cyan |
| 0xC | Light Red |
| 0xD | Light Magenta |
| 0xE | Yellow |
| 0xF | White |

### VGA API

```c
// Initialize VGA
void VGA_init(void);

// Clear screen
void VGA_clear_screen(void);

// Print string
void VGA_print(const char *str);

// Print with color
void VGA_print_color(const char *str, uint8_t color);

// Set cursor position
void VGA_set_cursor(int x, int y);

// Get cursor position
void VGA_get_cursor(int *x, int *y);
```

## Framebuffer Graphics (SQRM GPU Modules)

ModuOS uses SQRM modules to provide graphics framebuffers at runtime.

### In-tree GPU SQRM modules

- **QXL GPU** (virtual GPU in QEMU/Spice)
  - Source: `modules/QXL/src/qxl_gpu_sqrm.c`
- **VMware SVGA / VMSVGA** (virtual GPU in VMware / some QEMU configs)
  - Source: `modules/VMSVGA/vmsvga_gpu_sqrm.c`
- **MD VGA Compatible Display Driver** (fallback VGA graphics; typically Mode 13h 320×200×8)
  - Source: `modules/md_vga_compatible_display_sqrm.c`

### How GPU modules are chosen

GPU modules may **defer** to a more specific driver when they detect a known adapter. For example, the MD VGA compatible driver will defer when it detects QXL or VMSVGA so that those drivers can claim the device.

### What a GPU module provides

A GPU module registers a framebuffer descriptor with the kernel (width/height/pitch/bpp/address).
Higher-level components (framebuffer console, 2D UI, apps) render to that framebuffer.

## VBE / VESA BIOS Extensions

VBE can be used as a generic firmware-provided way to set up a linear framebuffer, but it is **not the primary graphics driver path** in ModuOS now that SQRM GPU drivers exist.

If/when a VBE-based driver exists, it should likely live as an **SQRM GPU module** that exposes the VBE linear framebuffer through the same framebuffer interface.

## Next Steps

- [Device Drivers](Device-Drivers.md) - Driver overview
- [Driver API](Driver-API.md) - SQRM module SDK
- [System Architecture](System-Architecture.md) - Graphics in system design