game-toolkit-dosvideo

DOS-era PC video for game-toolkit: VGA (mode 13h, Mode X, 16-color planar, text), EGA, CGA (with composite artifact colors and snow), Hercules, Tandy 1000 and VESA SVGA, emulated at the register level with a beam-accurate CRT.

text_mode with the Standard Galactic Alphabet loaded into the character generator (G) and the VGA monitor CRT filter (Alt+C).

It is not a PC emulator: your game is ordinary Rust. What is emulated is the part DOS programmers fought with, the display adapter: its memory layout, its registers, its timing, and the electron beam that reads it out while you are writing to it. Program it through I/O ports and memory pokes like in 1992, or through the helpers that do the same thing with less typing.

use game_toolkit_dosvideo::prelude::*;

struct Hello;

impl DosGame for Hello {
    fn init(dos: &mut Dos) -> anyhow::Result<Self> {
        dos.set_mode(0x13); // INT 10h, AX=0013h
        Ok(Self)
    }

    fn step(&mut self, dos: &mut Dos) {
        // while (inp(0x3DA) & 8); while (!(inp(0x3DA) & 8));
        dos.wait_vretrace();
        dos.set_palette(1, [63, 0, 0]); // OUT 3C8h / 3C9h
        dos.fill(0xA0000 + 100 * 320, 320, 1); // a red line in A000:7D00
        if dos.key(sc::ESC) {
            dos.exit();
        }
    }
}

fn main() -> anyhow::Result<()> {
    run::<Hello>(DosConfig::new("hello", Adapter::Vga))
}

Gallery

Captured from the running demos (DOSVIDEO_WINDOW_SHOT), some through a CRT preset.

copper_bars: raster bars by rewriting one DAC entry per scanline (VGA monitor filter)	palette_cycling: water, ripples and sun glow move without touching a pixel
modex_scroll: Mode X 320x240, hardware scrolling, split-screen status bar, page flipping	tearing_lab: a full-frame copy on a 16-bit ISA bus, overtaken by the beam
ega_scroller: smooth scrolling with pel panning and latch tile copies (VGA monitor filter)	cga_showcase: 640x200 black-and-white patterns turned into composite artifact colors (TV filter)
cga_showcase: 16 colors on a CGA via the 160x100 tweaked text mode	tandy: Tandy 1000 320x200 in 16 colors
hercules: 720x348, drawn on the hidden page and flipped in vertical retrace (green screen filter)	hercules: MDA text attributes and the 9th-column rule (amber screen filter)
svga: VBE 640x480 in 65536 colors	crt_dither: Bayer dithering to 16 colors, melted by the TV filter
pc_speaker: piano, synthie tracker music on one square wave, PWM samples	text_mode: tile graphics and the Standard Galactic Alphabet in the character generator

The model: a clock, a bus and a beam

A Dos is a machine with a clock. Everything costs time:

• port I/O (outb, inb) and video memory access (poke, peek, poke_slice, fill), priced by the configured BusTiming. An 8-bit ISA card moves about 1 MB/s, a 16-bit ISA VGA 2–4 MB/s, a VLB or PCI card 30–60 MB/s.
• CPU work you choose to charge (dos.cpu(cycles) at the configured clock rate).
• waiting for the beam: wait_vretrace, wait_vblank, wait_line(n), wait_hblank, wait_beam(line, dot), or polling the status port yourself.

The CRT paints the picture as the beam sweeps, dot by dot, from the adapter's state at that moment. Nothing is special-cased, so the tricks of the era just work:

• copper bars: DAC writes between scanlines (at 400-line resolution in mode 13h, into the overscan border too).
• palette cycling and fades.
• page flipping with the start address, which latches at vertical retrace, like the real CRTC.
• split screens with line compare, smooth scrolling with pel panning, virtual screens with the offset register.
• tweaked modes (Mode X, 320x400, 360x240, …): timing and resolution are derived from the CRTC registers, so programming them is enough.
• latch copies (write mode 1) for four planes per byte, set/reset and the bit mask, and read mode 1 color compare.

So do the failure modes:

• tearing when a copy is overtaken by the beam (on a slow bus a full mode 13h frame takes longer than the vertical blank).
• the attribute controller flip-flop, and a blank screen if the palette address source bit isn't set again.
• CRTC registers 0–7 being write-protected.
• leftover garbage after unchaining mode 13h.
• CGA snow in 80-column text.
• the inverted Hercules retrace bit.
• EGA's write-only registers and the 16-color limit of its 200-line modes.
• the mouse driver reporting 640x200 coordinates in mode 13h.

Adapters

SVGA is period-correct for DOS: VBE 1.2 (1991) and 2.0 (1994) were how DOS games reached 640x480 and above.

Layers of API

From most to least authentic, freely mixed:

1. Ports and memory: outb, outw, inb, poke, peek, pokew, poke32, poke_slice, fill, copy_vram, at physical addresses (0xA0000, 0xB8000, …).
2. BIOS: set_mode (INT 10h), vbe_set_mode, vbe_set_bank, vbe_set_display_start, bios_print (teletype with scrolling), load_font, getch / kbhit (INT 16h), mouse() (INT 33h), set_timer_hz / take_timer_ticks (the PIT), exit (INT 21h, 4Ch).
3. Register helpers: set_palette, cycle_palette, fade_palette, seq, gc, crtc, attr, map_mask, write_mode, bit_mask, set_start_address, set_offset, set_line_compare, set_pel_pan, set_border, screen_on.
4. Drawing: pset (any graphics mode, in that mode's memory layout), pset13, blit13, planar_pset, planar_fill_rect, planar_blit, cga_blit, tandy_blit, herc_pset, vbe_pset_banked, vbe_pset_lfb, vbe_write_banked, ModeX (set, pset, fill_rect, blit, VRAM-to-VRAM latch copy, flip), text helpers (text_print, text_box, set_cursor, set_blink, …).
5. Bitmap: an 8-bit back buffer in system memory with lines, rects, circles, blits and bitmap-font text, for double buffering the way most games did.

Keyboard input comes both ways: dos.key(sc::LEFT) is the held-key table a custom INT 9 handler would fill, and getch() / kbhit() is the BIOS buffer.

Looking like a CRT

Pixel-sharp output is the default. DosConfig::with_crt(CrtFilter::tv()) (or Alt+C at run time, cycling off → crisp scanlines → soft glow → VGA monitor → TV → green screen → amber screen) adds a GPU post-filter. The emulated frame has one row per real scanline (400 in mode 13h, 200 on a CGA, 350 on a Hercules card), so the filter can model the beam instead of faking it:

• scanlines: each line is a horizontal stripe of light whose height grows with brightness, so gaps show between dark lines and close between bright ones. 15 kHz modes get visible gaps, 31 kHz VGA gets fine ones.
• beam blur: the horizontal spread of the electron spot. This is what melted dither patterns into the in-between colors the artists of the era counted on.
• phosphor mask (aperture grille, slot mask or shadow mask): light is split into R, G and B stripes or dots on the window's own pixels, the "subpixel" structure the eye fuses back together. It needs about 3 window pixels per triad and fades out below that.
• bloom, curvature, vignette, rounded corners.
• soft glow keeps the colors but uses a monochrome monitor's optics (no mask, soft beam, glowing phosphor): not historical, but easy on the eyes.
• monochrome: the green and amber screen presets show only brightness in the phosphor's color, like a color card on a cheap monochrome monitor.

Every knob is a field of CrtFilter. With DosScreen in your own game, set screen.crt and call screen.draw_crt(&ctx.gfx, frame) after the painter for the frame is dropped.

Dithering and fonts

Bitmap::from_rgba(w, h, rgba, palette, Dither::Bayer4) turns true-color art into palette indices the period way: nearest color, ordered Bayer 2x2 / 4x4 / 8x8, or Floyd-Steinberg error diffusion.

Fonts: Font::vga() (8x16), Font::ega() (8x14), Font::cga() (8x8), and the Standard Galactic Alphabet of the Commander Keen games as Font::sga(), Font::sga_ega() and Font::sga_cga(): letters become Standard Galactic Alphabet glyphs, everything else stays CP437. Load any of them into text mode with dos.load_font(font, 0), or draw with Bitmap::text.

The PC speaker

PIT channel 2 and port 0x61 are emulated on the machine clock, and the speaker output is rendered by integrating the cone position over every audio sample, then played through game-toolkit's audio (or written to a WAV in headless runs: DOSVIDEO_WAV=out.wav).

• dos.sound(hz) / dos.nosound(): Turbo Pascal style, or program the ports yourself (OUT 43h,B6h, the divisor to 42h, bits 0+1 of 61h). Port 61h bit 4 toggles every 15 µs like the DRAM refresh that delay loops counted.
• Melody::new("T140 O3 L4 EEFG GFED ..."): QBasic PLAY strings, in the background.
• dos.speaker_pwm(&samples, 11_025): digitized sound by bit-banging the speaker. It blocks for the length of the sound, as it did.
• With the synth feature, speaker_synth::SpeakerTracker plays a synthie song (the tracker format of game-toolkit's chiptune synth) on the speaker: chords and arpeggio cells become one-note-per-frame arpeggios, drums become pitch sweeps and noise bursts.

Running

run::<G>(DosConfig) opens a game-toolkit window. DosGame::step is one iteration of your main loop; the host calls it as often as emulated time allows, so a loop that waits for the retrace once runs at the mode's refresh rate (70 Hz in mode 13h, 60 Hz in Mode X, ~50 Hz on a Hercules card). Alt+Enter toggles fullscreen, Alt+C cycles the CRT filter. DosConfig::with_keys(&[("B", "bars on/off"), ...]) documents your program's keys; run prints them to stdout at startup, with the host keys. DosConfig picks the aspect (Aspect::Crt by default, so the active area is 4:3 and mode 13h pixels are taller than wide), the overscan border, integer scaling and the CRT filter.

To put a DOS screen into your own Game, use DosScreen directly: feed_input, then step your Dos, upload and draw.

Headless, for tests and screenshots: DOSVIDEO_SHOT=out.png DOSVIDEO_SHOT_FRAMES=120 cargo run --example copper_bars writes the frame as PNG instead of opening a window, and DOSVIDEO_KEYS=30:0x30,90:0x24 taps keys (by scancode) at given frames (also in window mode, counted in host frames). Those shots are the raw emulated frame; to capture the window with the CRT filter, use DOSVIDEO_WINDOW_SHOT=out.png DOSVIDEO_WINDOW_SHOT_FRAMES=90, and DOSVIDEO_CRT=0..6 to pick a preset. dos.frame() gives the last complete frame as RGBA anywhere, with to_png().

Features: toolkit (default) for the game-toolkit host, synth for tracker music on the PC speaker. Without the default toolkit feature the crate has no dependencies at all: just the machine, for tests or for driving it from another frontend.

Demos

task examples            # list them
task run EXAMPLE=copper_bars
task shots               # screenshot every demo headless into target/shots/

Accuracy

The goal is "feels like the hardware, behaves like the hardware where a program can tell", not cycle accuracy. Simplifications worth knowing:

• Memory writes become visible to the beam immediately; the CRTC's character-clock prefetch is not modeled.
• 6845 boards (CGA, Tandy, Hercules) have no blanking registers, so their border width is an approximation.
• CGA composite output is a straightforward NTSC encode/decode of RGBI colors, not a model of the CGA's chroma circuitry; tune it with cga_set_composite_hue.
• EGA and VGA 8-bit mode pass both nibbles through the attribute palette, as the hardware does; per-card quirks of SVGA chipsets are not modeled (it is a generic VBE 2.0 card).
• There is no interrupt-driven code: instead of a timer ISR, count ticks with take_timer_ticks(), and instead of raster IRQs, wait for the beam.

Tasks

task (go-task, Taskfile.dist.yaml) wraps the usual: build, run, test, lint, check (fmt, clippy with and without toolkit, wasm32), ci, docs, shots, font.

License

EUPL-1.2. The VGA BIOS fonts in crates/dosvideo/fonts/vga_8x*.bin are VGA-ROM.F08/F14/F16 from fntcol16, the EGA/VGA font collection (c) 1991, 1992 Joseph (Yossi) Gil, whose individual fonts are public domain; his notice is preserved in fonts/COPYLEFT-fntcol16.TXT.