web-a2e 1.0.0

package/wiki/Disk-System-Internals.md

@@ -0,0 +1,547 @@
+# Disk System Internals
+
+This page covers the low-level implementation of the Disk II controller card and disk image format support. For user-facing disk drive operations, see [[Disk Drives]].
+
+---
+
+## Table of Contents
+
+- [Architecture Overview](#architecture-overview)
+- [Disk II Controller Card](#disk-ii-controller-card)
+  - [Slot Assignment and Memory Map](#slot-assignment-and-memory-map)
+  - [Soft Switches](#soft-switches)
+  - [Logic State Sequencer](#logic-state-sequencer)
+  - [P6 ROM](#p6-rom)
+  - [Motor Control](#motor-control)
+  - [Stepper Motor and Head Positioning](#stepper-motor-and-head-positioning)
+- [Disk Image Abstraction](#disk-image-abstraction)
+- [DSK Format](#dsk-format)
+  - [File Layout](#file-layout)
+  - [Format Detection](#format-detection)
+  - [Sector Ordering](#sector-ordering)
+  - [Nibblization](#nibblization)
+  - [Denibblization](#denibblization)
+  - [Bit Stream Cache](#bit-stream-cache)
+  - [Disk Rotation Timing](#disk-rotation-timing)
+- [WOZ Format](#woz-format)
+  - [File Structure](#file-structure)
+  - [INFO Chunk](#info-chunk)
+  - [TMAP Chunk](#tmap-chunk)
+  - [TRKS Chunk](#trks-chunk)
+  - [Quarter-Track Support](#quarter-track-support)
+  - [Bit-Level Access](#bit-level-access)
+  - [Sector Decoding](#sector-decoding)
+  - [Export and Saving](#export-and-saving)
+- [GCR Encoding](#gcr-encoding)
+  - [6-and-2 Encoding](#6-and-2-encoding)
+  - [4-and-4 Encoding](#4-and-4-encoding)
+  - [Sector Structure](#sector-structure)
+  - [Self-Sync Bytes](#self-sync-bytes)
+- [Write Support](#write-support)
+- [State Serialization](#state-serialization)
+- [Source Files](#source-files)
+
+---
+
+## Architecture Overview
+
+The disk subsystem has three layers:
+
+| Layer | Class | Responsibility |
+|-------|-------|----------------|
+| Controller | `Disk2Card` | Soft switches, Logic State Sequencer, motor/drive control |
+| Image abstraction | `DiskImage` | Abstract interface for head positioning and data access |
+| Format implementations | `DskDiskImage`, `WozDiskImage` | Format-specific loading, nibblization, bit-level storage |
+
+The controller only communicates through the `DiskImage` interface using phase signals (for head movement) and nibble/bit read/write operations. Format-specific details are hidden behind this abstraction.
+
+---
+
+## Disk II Controller Card
+
+### Slot Assignment and Memory Map
+
+The Disk II occupies slot 6 by default:
+
+| Address Range | Function |
+|---------------|----------|
+| `$C0E0-$C0EF` | 16 soft switches for disk control |
+| `$C600-$C6FF` | 256-byte bootstrap ROM (P5A, 341-0027) |
+
+The card does not use expansion ROM (`$C800-$CFFF`).
+
+### Soft Switches
+
+The 16 soft switch addresses control all disk operations. Each switch is triggered by any access (read or write) to its address:
+
+| Offset | Even (Off/Low) | Odd (On/High) |
+|--------|----------------|---------------|
+| `$00-$01` | Phase 0 off | Phase 0 on |
+| `$02-$03` | Phase 1 off | Phase 1 on |
+| `$04-$05` | Phase 2 off | Phase 2 on |
+| `$06-$07` | Phase 3 off | Phase 3 on |
+| `$08-$09` | Motor off | Motor on |
+| `$0A-$0B` | Select Drive 1 | Select Drive 2 |
+| `$0C-$0D` | Q6 Low (read data) | Q6 High (WP sense / write load) |
+| `$0E-$0F` | Q7 Low (read mode) | Q7 High (write mode) |
+
+The Q6/Q7 combination determines the controller mode:
+
+| Q7 | Q6 | Mode | Operation |
+|----|----|------|-----------|
+| 0 | 0 | Read | Returns data register (shift register output) |
+| 0 | 1 | Sense | Returns write-protect status in bit 7 |
+| 1 | 0 | Write | Writes data register to disk |
+| 1 | 1 | Load | Loads CPU bus data into data register |
+
+### Logic State Sequencer
+
+The heart of the Disk II controller is the Logic State Sequencer (LSS), implemented by the P6 ROM (341-0028). The LSS is a state machine that converts between the serial bit stream on the disk and bytes accessible by the CPU.
+
+**Timing:** The LSS runs at 2x the CPU clock rate (approximately 2.046 MHz). An 8-phase clock divides each 4-cycle bit cell into 8 ticks. Disk read/write occurs only at phase 4 of this clock.
+
+**State machine operation:**
+
+1. At each tick, a P6 ROM address is computed from:
+   - Sequencer state (4 bits, high nibble)
+   - Q7 and Q6 mode bits
+   - Data register bit 7 (QA feedback)
+   - Read pulse from disk (1 = flux transition, inverted for address)
+
+2. The ROM output encodes the next state (high nibble) and an action code (low nibble)
+
+3. Actions on the data register:
+
+| Action Code | Operation | Description |
+|-------------|-----------|-------------|
+| `$0-$7` | CLR | Clear data register to `$00` |
+| `$8`, `$C` | NOP | No operation |
+| `$9` | SL0 | Shift left, insert 0 |
+| `$A`, `$E` | SR+WP | Shift right, insert write-protect bit |
+| `$B`, `$F` | LOAD | Load from CPU bus |
+| `$D` | SL1 | Shift left, insert 1 |
+
+4. In write mode (Q7=1), at phase 4 the sequencer outputs bit 3 of the next state to the disk head.
+
+**Catch-up mechanism:** Rather than running the LSS every CPU cycle, the controller records the last cycle it was clocked and "catches up" when a soft switch is accessed. This is capped at approximately one disk revolution (~53,000 bits x 8 ticks) to prevent excessive computation after long idle periods.
+
+### P6 ROM
+
+The P6 ROM (341-0028) is a 256x4-bit PROM stored in the emulator in de-scrambled BAPD (Beneath Apple ProDOS) logical format. The ROM address is computed as:
+
+```
+address = (state << 4) | (Q7 << 3) | (Q6 << 2) | (QA << 1) | inverted_pulse
+```
+
+The ROM CRC32 (source format) is `b72a2c70`.
+
+### Motor Control
+
+The disk motor has a delayed-off behavior matching real hardware:
+
+- **Motor on:** Immediate; sets `motorOn_` flag and resets the LSS cycle counter
+- **Motor off:** Delayed by approximately 1 second (1,023,000 CPU cycles). The `motorOffCycle_` timestamp is recorded when the off switch is hit, and `isMotorOn()` checks elapsed time lazily
+
+This delay allows software to briefly turn the motor "off" during seeks without actually stopping the disk, which was a common technique.
+
+### Stepper Motor and Head Positioning
+
+The Disk II uses a 4-phase stepper motor for head positioning. The head moves in half-track (2 quarter-track) increments:
+
+1. The controller manages phase magnet states as a 4-bit field (bits 0-3 for phases 0-3)
+2. Stepping occurs when the **current phase is turned OFF** and an adjacent phase is ON
+3. If the next phase (clockwise) is on, the head steps **inward** (higher track numbers)
+4. If the previous phase (counter-clockwise) is on, the head steps **outward** (toward track 0)
+5. If both or neither adjacent phases are on, no stepping occurs
+
+Position tracking uses quarter-tracks (0-139 for DSK, 0-159 for WOZ). The visible track number is `quarter_track / 4`.
+
+---
+
+## Disk Image Abstraction
+
+The `DiskImage` abstract base class defines the interface between the controller and format-specific implementations:
+
+```
+DiskImage (abstract)
+  +-- DskDiskImage   (DSK/DO/PO raw sector format)
+  +-- WozDiskImage   (WOZ 1.0/2.0 bit-accurate format)
+```
+
+Key interface methods:
+
+| Method | Description |
+|--------|-------------|
+| `load()` | Load disk image from raw data |
+| `setPhase()` | Notify of phase magnet state change |
+| `advanceBitPosition()` | Advance disk rotation based on CPU cycles |
+| `readNibble()` / `writeNibble()` | Nibble-level access |
+| `readBit()` / `writeBit()` | Bit-level access (for LSS) |
+| `getSectorData()` | Get decoded sector data for file explorer |
+| `exportData()` | Export in native format for saving |
+
+The disk image manages head positioning internally based on stepper motor phase changes. The controller only knows about phases (0-3), not tracks.
+
+---
+
+## DSK Format
+
+### File Layout
+
+DSK is a raw sector image format storing exactly 143,360 bytes (140 KB):
+
+| Parameter | Value |
+|-----------|-------|
+| Tracks | 35 (0-34) |
+| Sectors per track | 16 |
+| Bytes per sector | 256 |
+| Nibbles per track | 6,656 |
+| Total size | 143,360 bytes |
+
+### Format Detection
+
+Format detection uses content-based heuristics rather than relying solely on file extensions:
+
+1. **ProDOS check:** Examine block 2 (offset 1024) for a volume directory header. A valid ProDOS disk has storage type `$Fx` with a valid name length and ASCII characters. If found, the format is PO (ProDOS order).
+
+2. **DOS 3.3 check:** Examine the VTOC at track 17, sector 0 (offset 69,632). A valid DOS 3.3 disk has a catalog track of `$11-$14`, catalog sector of `$00-$0F`, and DOS version `$03`.
+
+3. **Extension fallback:** If content detection fails, `.po` files are treated as ProDOS order; all others default to DOS order.
+
+### Sector Ordering
+
+Two sector ordering schemes are supported, each with its own logical-to-physical mapping:
+
+**DOS 3.3 order (DSK/DO):**
+
+| Logical | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
+|---------|---|---|---|---|---|---|---|---|---|---|----|----|----|----|----|-----|
+| Physical | 0 | 13 | 11 | 9 | 7 | 5 | 3 | 1 | 14 | 12 | 10 | 8 | 6 | 4 | 2 | 15 |
+
+**ProDOS order (PO):**
+
+| Logical | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 |
+|---------|---|---|---|---|---|---|---|---|---|---|----|----|----|----|----|-----|
+| Physical | 0 | 2 | 4 | 6 | 8 | 10 | 12 | 14 | 1 | 3 | 5 | 7 | 9 | 11 | 13 | 15 |
+
+### Nibblization
+
+When a track is first accessed, the raw sector data is converted to a GCR-encoded nibble stream on demand. Each track contains 16 sectors laid out sequentially:
+
+1. **Gap 1** (first sector) or **Gap 3** (between sectors): Self-sync bytes
+   - First sector: 128 sync bytes
+   - Subsequent sectors: 40 bytes (track 0) or 38 bytes (other tracks)
+2. **Address field:** Prologue + 4-and-4 encoded volume/track/sector/checksum + epilogue
+3. **Gap 2:** 5 sync bytes
+4. **Data field:** Prologue + 343 6-and-2 encoded nibbles + epilogue
+5. **Gap 3 end:** 1 sync byte
+
+The nibble track is padded or truncated to exactly 6,656 nibbles. Each nibble also carries a sync flag indicating whether it is a 10-bit self-sync byte or a standard 8-bit data byte.
+
+### Denibblization
+
+When a modified nibble track needs to be converted back to sector data (for saving), the denibblizer:
+
+1. Creates an extended buffer with wrap-around (500 extra nibbles) to handle sectors that span the track boundary
+2. Searches for address field prologues (`$D5 $AA $96`)
+3. Decodes the 4-and-4 encoded address (volume, track, sector, checksum)
+4. Verifies the address checksum and track number
+5. Finds the data field prologue (`$D5 $AA $AD`) within 50 nibbles
+6. Decodes the 343 6-and-2 encoded nibbles back to 256 bytes
+7. Writes the decoded data to the sector data array using the appropriate sector mapping
+
+### Bit Stream Cache
+
+For LSS-level access, each nibble track can be converted to a packed bit stream. The conversion respects the sync flag:
+
+- **Data bytes:** 8 bits per nibble (MSB first)
+- **Sync bytes:** 10 bits per nibble (8 data bits + 2 extra zero bits)
+
+The total bit count varies per track based on the number of sync bytes. Dirty bit tracks are converted back to nibble tracks before denibblization.
+
+### Disk Rotation Timing
+
+The disk spins at approximately 300 RPM (5 revolutions per second):
+
+| Parameter | Value |
+|-----------|-------|
+| CPU clock | 1,023,000 Hz |
+| Cycles per revolution | ~204,600 |
+| Nibbles per track | 6,656 |
+| Cycles per nibble | ~31 (giving ~297 RPM, within spec) |
+
+The `advanceBitPosition()` method advances the nibble position based on elapsed CPU cycles to simulate continuous disk rotation while the motor is on.
+
+---
+
+## WOZ Format
+
+WOZ is a bit-accurate disk image format that captures exact magnetic flux transitions. It preserves copy-protection schemes and timing variations that sector-based formats cannot represent.
+
+### File Structure
+
+A WOZ file consists of a header followed by a series of chunks:
+
+```
+WOZ Header (12 bytes)
+  +-- INFO chunk (required)
+  +-- TMAP chunk (required)
+  +-- TRKS chunk (required)
+  +-- META chunk (optional, skipped)
+  +-- WRIT chunk (optional, skipped)
+```
+
+**Header format (12 bytes):**
+
+| Offset | Size | Field | Description |
+|--------|------|-------|-------------|
+| 0 | 4 | Signature | `WOZ1` (`$57 $4F $5A $31`) or `WOZ2` (`$57 $4F $5A $32`) |
+| 4 | 1 | High bits | `$FF` (high bit test) |
+| 5 | 3 | LF/CR/LF | `$0A $0D $0A` (line ending test) |
+| 8 | 4 | CRC32 | CRC of all data after this field |
+
+**Chunk header (8 bytes):**
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 0 | 4 | Chunk ID (4 ASCII characters) |
+| 4 | 4 | Data size (not including header) |
+
+### INFO Chunk
+
+The INFO chunk (60 bytes in WOZ2) contains disk metadata:
+
+| Offset | Size | Field | Description |
+|--------|------|-------|-------------|
+| 0 | 1 | Version | 1 or 2 |
+| 1 | 1 | Disk type | 1 = 5.25", 2 = 3.5" |
+| 2 | 1 | Write protected | 0 or 1 |
+| 3 | 1 | Synchronized | Tracks are cross-track synchronized |
+| 4 | 1 | Cleaned | MC3470 fake bits removed |
+| 5 | 32 | Creator | Software that created the image |
+| 37 | 1 | Disk sides | 1 or 2 |
+| 38 | 1 | Boot sector format | 0=unknown, 1=16-sector, 2=13-sector, 3=both |
+| 39 | 1 | Optimal bit timing | In 125 ns units (default 32 = 4 us) |
+| 40 | 2 | Compatible hardware | Bit field |
+| 42 | 2 | Required RAM | Minimum RAM in KB |
+| 44 | 2 | Largest track | Block count of largest track |
+
+### TMAP Chunk
+
+The TMAP (Track Map) chunk is a 160-byte array that maps quarter-track positions (0-159) to track data indices. A value of `$FF` indicates no track data at that position. Multiple quarter-tracks can reference the same track data index, enabling half-track data sharing.
+
+### TRKS Chunk
+
+**WOZ1 format:** Each track entry is a fixed 6,656 bytes:
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 0 | 6,646 | Bitstream data |
+| 6,646 | 2 | Bytes used |
+| 6,648 | 2 | Bit count |
+| 6,650 | 2 | Splice point |
+| 6,652 | 1 | Splice nibble |
+| 6,653 | 1 | Splice bit count |
+| 6,654 | 2 | Reserved |
+
+**WOZ2 format:** A table of 160 track entries (8 bytes each), followed by track bit data at 512-byte block offsets:
+
+| Offset | Size | Field |
+|--------|------|-------|
+| 0 | 2 | Starting block (512-byte blocks from file start) |
+| 2 | 2 | Block count |
+| 4 | 4 | Bit count |
+
+### Quarter-Track Support
+
+WOZ supports 160 quarter-track positions (40 possible track positions x 4 quarter-tracks each). The TMAP provides the indirection layer:
+
+- Standard tracks are at quarter-track positions 0, 4, 8, ..., 136
+- Half-tracks (used by some copy protection) can exist at positions 2, 6, 10, ...
+- Quarter-tracks provide even finer granularity
+
+The stepper motor physics are identical to the DSK implementation but with a wider range (0-159 vs 0-139).
+
+### Bit-Level Access
+
+WOZ stores raw bit data in packed MSB-first format. Reading a nibble from the bit stream follows the Disk II hardware behavior:
+
+1. Read bits sequentially
+2. Skip zero bits until a 1-bit is found (sync region)
+3. Shift bits into an accumulator
+4. When bit 7 of the accumulator is set, the nibble is complete
+
+A safety limit of 64 bits prevents infinite loops on corrupted data.
+
+**Bit timing for WOZ:**
+
+| Parameter | Value |
+|-----------|-------|
+| Cycles per bit | 4 (from optimal bit timing of 32 x 125 ns = 4 us) |
+| Bits per revolution | ~51,200 (standard track) |
+
+### Sector Decoding
+
+WOZ images can be decoded to sector data for the [[File Explorer]]. This enables browsing DOS 3.3 and ProDOS files on WOZ disks:
+
+1. For each track, read nibbles from the bit stream (scanning through twice to handle wrap-around)
+2. Search for address field prologues (`$D5 $AA $96`)
+3. Decode 4-and-4 address fields and verify checksums
+4. Find data field prologues (`$D5 $AA $AD`)
+5. Decode 6-and-2 data fields
+
+Decoding is considered successful if at least 50% of sectors (280 of 560) are recovered. This tolerance allows copy-protected disks with intentionally bad sectors to still have their readable content browsed.
+
+### Export and Saving
+
+WOZ images are exported in WOZ2 format with the following structure:
+
+1. 12-byte WOZ2 header
+2. INFO chunk (68 bytes total with header)
+3. TMAP chunk (168 bytes total)
+4. TRKS chunk with 160-entry track table (1288 bytes)
+5. Track bit data starting at block 3 (offset 1536)
+
+Blank/unformatted disks can be created with 35 tracks of 51,200 bits each, filled with sync bytes (`$FF`).
+
+---
+
+## GCR Encoding
+
+Group Coded Recording (GCR) is the encoding scheme used by the Disk II to store data on floppy disks. It ensures that the encoded bit stream maintains the timing constraints required by the hardware: every byte must have its high bit set and must not contain more than two consecutive zero bits.
+
+### 6-and-2 Encoding
+
+The primary data encoding scheme converts 256 data bytes into 343 disk nibbles (342 encoded + 1 checksum):
+
+**Step 1: Build auxiliary buffer (86 bytes)**
+
+For each of 86 positions, extract bits 0-1 from up to three data bytes:
+- `buffer[i]` bits 0-1 from `data[i]` (with bit swap)
+- `buffer[i]` bits 2-3 from `data[i+86]` (with bit swap)
+- `buffer[i]` bits 4-5 from `data[i+172]` (with bit swap)
+
+**Step 2: Build primary buffer (256 bytes)**
+
+Store bits 2-7 of each data byte (shifted right by 2):
+```
+buffer[86+i] = data[i] >> 2
+```
+
+**Step 3: XOR differential encoding**
+
+Each buffer value is XORed with the previous value before encoding:
+```
+encoded[i] = ENCODE_6_AND_2[buffer[i] XOR prev]
+prev = buffer[i]
+```
+
+**Step 4: Checksum**
+
+The final (343rd) nibble encodes the last pre-XOR buffer value, serving as a checksum.
+
+The 6-and-2 lookup table maps 64 possible 6-bit values to 64 valid disk nibbles (values `$96-$FF` with high bit set and no adjacent zeros).
+
+### 4-and-4 Encoding
+
+Address field values (volume, track, sector, checksum) use a simpler encoding that splits each byte into odd and even bits:
+
+```
+odd  = 0xAA | (value >> 1) & 0x55   // bits 7,5,3,1 -> positions 6,4,2,0
+even = 0xAA | value & 0x55          // bits 6,4,2,0 -> positions 6,4,2,0
+```
+
+Each byte becomes two bytes, both guaranteed to have their high bit set.
+
+### Sector Structure
+
+A complete sector on disk consists of:
+
+```
+[Gap: 14+ sync bytes]
+[Address Prologue: D5 AA 96]
+[Volume odd] [Volume even]
+[Track odd]  [Track even]
+[Sector odd] [Sector even]
+[Checksum odd] [Checksum even]   (checksum = volume XOR track XOR sector)
+[Address Epilogue: DE AA EB]
+[Gap: 6 sync bytes]
+[Data Prologue: D5 AA AD]
+[343 encoded data nibbles]
+[Data Epilogue: DE AA EB]
+```
+
+**Marker bytes:**
+
+| Marker | Bytes | Purpose |
+|--------|-------|---------|
+| Address prologue | `$D5 $AA $96` | Start of address field |
+| Address epilogue | `$DE $AA $EB` | End of address field |
+| Data prologue | `$D5 $AA $AD` | Start of data field |
+| Data epilogue | `$DE $AA $EB` | End of data field |
+| Sync byte | `$FF` | Self-synchronizing (10 bits on disk) |
+
+### Self-Sync Bytes
+
+Self-sync bytes are `$FF` values that occupy 10 bits on disk instead of the standard 8 bits. The extra two zero bits allow the read hardware to regain byte synchronization. When the controller encounters a stream of 10-bit `$FF` values, the shift register naturally aligns to byte boundaries because the `$FF` pattern fills all 8 bits with ones regardless of the starting alignment.
+
+---
+
+## Write Support
+
+Both DSK and WOZ formats support write operations:
+
+**DSK writes:**
+1. Nibbles are written directly to the nibble track cache at the current position
+2. The track is marked dirty
+3. On save, dirty tracks are denibblized back to sector data
+4. For bit-level writes (LSS), bits are written to the bit track cache and later converted back through bit-track -> nibble-track -> sector-data
+
+**WOZ writes:**
+1. Bits are written directly to the track's packed bit array
+2. For nibble writes, 8 bits are written MSB-first
+3. The modified flag is set for the entire image
+
+Write-protected disks reject all write operations. The write-protect status comes from the WOZ INFO chunk or the `write_protected_` flag for DSK images.
+
+---
+
+## State Serialization
+
+The Disk II controller state (32 bytes maximum) includes:
+
+| Field | Size | Description |
+|-------|------|-------------|
+| Motor on | 1 byte | Motor running flag |
+| Selected drive | 1 byte | 0 or 1 |
+| Q6 | 1 byte | Q6 latch state |
+| Q7 | 1 byte | Q7 latch state |
+| Phase states | 1 byte | 4-bit phase magnet field |
+| Data register | 1 byte | LSS shift register value |
+| Drive 0 quarter-track | 1 byte | Head position for drive 0 |
+| Drive 1 quarter-track | 1 byte | Head position for drive 1 |
+| Sequencer state | 1 byte | 4-bit LSS state |
+| Bus data | 1 byte | Last CPU bus value |
+| LSS clock | 1 byte | 8-phase clock position |
+
+Disk image data (sector data and modifications) is saved separately as part of the full emulator state. See [[Save States]] for details.
+
+---
+
+## Source Files
+
+| File | Description |
+|------|-------------|
+| `src/core/cards/disk2_card.hpp` | Disk II controller card interface |
+| `src/core/cards/disk2_card.cpp` | Controller implementation, LSS, P6 ROM |
+| `src/core/disk-image/disk_image.hpp` | Abstract disk image base class |
+| `src/core/disk-image/dsk_disk_image.hpp` | DSK format class declaration |
+| `src/core/disk-image/dsk_disk_image.cpp` | DSK nibblization, denibblization, stepper |
+| `src/core/disk-image/woz_disk_image.hpp` | WOZ format class declaration |
+| `src/core/disk-image/woz_disk_image.cpp` | WOZ parsing, bit-level access, sector decoding |
+| `src/core/disk-image/gcr_encoding.hpp` | GCR encoding tables and function declarations |
+| `src/core/disk-image/gcr_encoding.cpp` | 6-and-2 and 4-and-4 encoding implementation |
+
+---
+
+See also: [[Disk Drives]] | [[File Explorer]] | [[Expansion Slots]] | [[Architecture Overview]]

package/wiki/Display-Settings.md

@@ -0,0 +1,88 @@
+# Display Settings
+
+The Display Settings window controls all visual effects applied to the emulator screen. Open it from **View > Display** in the toolbar.
+
+Every setting is a percentage slider (0-100%) unless otherwise noted. All settings are saved to localStorage and restored automatically on reload. Click **Reset to Defaults** at the bottom of the window to return every setting to its initial value.
+
+---
+
+## Table of Contents
+
+- [CRT Effects](#crt-effects)
+- [Analog Effects](#analog-effects)
+- [Image Controls](#image-controls)
+- [Rendering Options](#rendering-options)
+- [NTSC Effects](#ntsc-effects)
+- [How the Shader Pipeline Works](#how-the-shader-pipeline-works)
+
+---
+
+## CRT Effects
+
+These settings simulate the physical characteristics of a cathode-ray tube monitor.
+
+| Setting | Description |
+|---------|-------------|
+| **Screen Curvature** | Barrel distortion that bows the image outward, mimicking the curved glass of a CRT. At 0% the screen is perfectly flat. |
+| **Screen Border** | Adds a dark border (overscan area) around the display content, simulating the bezel masking seen on real monitors. |
+| **Scanlines** | Horizontal dark lines between each row of pixels. Reproduces the visible gap between phosphor rows on a real CRT. |
+| **Shadow Mask** | A repeating RGB dot pattern overlaid on the image, simulating the aperture grille or shadow mask that separates red, green, and blue phosphor dots. |
+| **Phosphor Glow** | Bloom effect around bright pixels. Simulates the way phosphor coating bleeds light outward on a real tube. |
+| **Vignette** | Darkens the corners and edges of the screen, reproducing the natural brightness falloff at the periphery of a CRT. |
+| **RGB Offset** | Chromatic aberration -- shifts the red, green, and blue colour channels slightly apart, simulating convergence errors in the electron guns. |
+| **Flicker** | Random frame-to-frame brightness variation, reproducing the subtle luminance instability of analog displays. |
+
+## Analog Effects
+
+These settings simulate signal-path imperfections and environmental characteristics of vintage displays.
+
+| Setting | Description |
+|---------|-------------|
+| **Static Noise** | Random grain overlaid on the image, like a slightly noisy video signal. |
+| **Jitter** | Random per-pixel horizontal displacement, simulating timing instability in the video signal. |
+| **Horizontal Sync** | Periodic horizontal distortion bands that slide across the screen, mimicking sync issues in the composite video signal. |
+| **Glowing Line** | A bright horizontal scan beam that sweeps down the screen, reproducing the visible raster scan of a real CRT's electron beam. |
+| **Ambient Light** | Simulates room light reflecting off the glass surface of the monitor. Adds a subtle lightening to the screen. |
+| **Burn In** | Phosphor persistence -- bright areas leave a fading afterimage. The emulator maintains a separate framebuffer that accumulates and decays burn-in over time. |
+
+## Image Controls
+
+Basic picture adjustments that apply on top of all CRT and analog effects.
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| **Brightness** | 100% | Overall luminance. Maps to a 0.5-1.5 multiplier in the shader. |
+| **Contrast** | 100% | Difference between dark and light areas. Also maps to a 0.5-1.5 range. |
+| **Saturation** | 100% | Colour intensity. At 0% the image is greyscale; at 200% colours are vivid. |
+
+## Rendering Options
+
+| Setting | Description |
+|---------|-------------|
+| **Display Mode** | Dropdown with four choices: **Color** (full NTSC colour), **Green** (green phosphor monochrome), **Amber** (amber phosphor), or **White** (white phosphor). Monochrome modes bypass NTSC colour artifacts and render a single-channel image tinted to match the selected phosphor colour. |
+| **Sharp Pixels** | Toggle. When enabled, the WebGL texture uses nearest-neighbour filtering instead of bilinear interpolation, producing crisp pixel edges with no smoothing. When disabled (default), pixels are softly blended. |
+
+## NTSC Effects
+
+These shader-based effects simulate characteristics of the NTSC composite video encoding used by the Apple IIe.
+
+| Setting | Description |
+|---------|-------------|
+| **Color Bleed** | Vertical inter-scanline colour blending. Simulates the way CRT phosphor rows overlap slightly, causing colour from one scanline to bleed into its neighbours. |
+| **NTSC Fringing** | Colour fringing at sharp horizontal edges. Reproduces the magenta/cyan fringes caused by NTSC chroma bandwidth limiting, visible on real hardware at transitions between black and white pixels. |
+
+## How the Shader Pipeline Works
+
+The display passes through a multi-stage WebGL shader pipeline:
+
+1. **Source texture** -- The C++ video renderer produces a 560x384 RGBA framebuffer (double the native 280x192 resolution). This is uploaded to a WebGL texture each frame.
+
+2. **CRT fragment shader** (`crt.glsl`) -- Applies curvature, scanlines, shadow mask, phosphor glow, vignette, chromatic aberration, flicker, static noise, jitter, horizontal sync, glowing line, ambient light, colour bleed, NTSC fringing, monochrome tinting, screen border, and rounded corners in a single pass.
+
+3. **Burn-in pass** (`burnin.glsl`) -- A separate framebuffer accumulates bright pixel values over time and decays them, creating the phosphor persistence effect. This texture is blended back into the main image during the CRT pass.
+
+4. **Edge overlay pass** (`edge.glsl`) -- Draws a subtle highlight around the screen border to simulate light catching the edge of the CRT glass.
+
+All shader parameters are set as WebGL uniforms and update in real time as you drag the sliders. An animated `time` uniform drives effects like static noise, flicker, jitter, and the glowing scan line.
+
+Settings are stored in `localStorage` under the key `a2e-display-settings` as a JSON object. They persist across sessions and are independent of save states.