Crate game_toolkit_dosvideo 

DOS-era PC video for game-toolkit: VGA (mode 13h, Mode X, planar 16-color, 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.

The model

A Dos is a machine with a clock. Everything a program does costs time: a port write (Dos::outb), a video memory write (Dos::poke, priced by the configured BusTiming), computation you choose to charge (Dos::cpu), and waiting for the beam (Dos::wait_vretrace, Dos::wait_line) or polling the status port like DOS programs did (while dos.inb(0x3DA) & 8 == 0 {} works).

The CRT paints the picture as the beam sweeps, from the adapter’s state at that moment. So all the tricks of the era fall out by themselves: palette changes between scanlines (copper bars), changing the start address or line compare for page flipping and split screens, pel panning for smooth scrolling, palette rotation, and the failure modes too: tearing when a copy is overtaken by the beam, a start address that only latches at vertical retrace, the attribute controller flip-flop, CRTC write protection, CGA snow.

Running a program

With the default toolkit feature, implement DosGame and hand it to run. step is one pass of your main loop; the host calls it as often as emulated time allows and shows the frames the CRT produces.

use game_toolkit_dosvideo::prelude::*;

struct Hello;

impl DosGame for Hello {
    fn init(dos: &mut Dos) -> anyhow::Result<Self> {
        dos.set_mode(0x13);
        Ok(Self)
    }

    fn step(&mut self, dos: &mut Dos) {
        dos.wait_vretrace();
        let t = dos.frames() as u32;
        for y in 0..200u32 {
            let row: Vec<u8> = (0..320u32).map(|x| ((x ^ y) + t) as u8).collect();
            dos.poke_slice(0xA0000 + y * 320, &row);
        }
        if dos.key(sc::ESC) {
            dos.exit();
        }
    }
}

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

Re-exports

pub use cga::CgaMonitor;

pub use font::Font;

pub use input::KeyPress;

pub use input::Keyboard;

pub use input::Mouse;

pub use input::sc;

pub use palette::Phosphor;

pub use svga::VbeMode;

pub use game_toolkit;

pub use game_toolkit_dosaudio;

Modules

cga

IBM CGA and the Tandy 1000 / PCjr video subsystem, both built on the Motorola 6845 CRTC.

cpu

Common CPU clock rates, for Dos::cpu.

draw

Drawing the way DOS programs drew: palette programming, register helpers, pixel plotting for every adapter’s memory layout, Mode X with page flipping, and an off-screen Bitmap for double buffering in system memory.

font

Code page 437 bitmap fonts, the character sets of the PC adapters.

hercules

Hercules Graphics Card: MDA-compatible 80x25 monochrome text plus a 720x348 graphics mode with two pages.

input

Keyboard and mouse, the way a DOS program sees them.

palette

The standard colors of the PC display adapters.

prelude

use game_toolkit_dosvideo::prelude::*;

speaker

The PC speaker: a paper cone wired to PIT channel 2 and two bits of port 0x61.

speaker_synth

Tracker music on the PC speaker: play a synthie song (the chiptune engine behind game-toolkit’s synth feature) through the one-bit speaker, the way DOS games did it from their timer interrupt.

svga

A VESA BIOS Extensions 2.0 SVGA card: a full VGA, plus high-resolution and high-color modes reached through a 64 KiB bank window at A000:0000 (VBE 1.2 style, switch banks with function 05h) or a linear framebuffer at LFB_BASE (VBE 2.0, protected-mode programs).

text

Text mode: character/attribute cells at B800:0000 (color) or B000:0000 (monochrome), the hardware cursor, blinking, box drawing, and BIOS-style teletype output.

tui

A ratatui backend that draws into text mode (ratatui feature).

vga

IBM EGA and VGA, at the register level.

Structs

Beam

Where the beam is at some instant.

BusTiming

How long the CPU waits for the video card on each access, in nanoseconds.

CrtFilter

CRT filter settings. Start from a preset (CrtFilter::vga_monitor, CrtFilter::tv, …) and adjust.

Dos

A DOS PC with one display adapter.

DosConfig

Configuration for run.

DosScreen

Shows a Dos picture through game-toolkit: uploads finished frames into a texture, fits them into a rectangle with the right aspect ratio, and feeds the keyboard and mouse.

FrameView

One finished frame, as RGBA8 in visible-area dots.

MachineConfig

Machine configuration.

Timing

Raster timing of the current video mode, in dots (pixel clock ticks) and scanlines.

Enums

Adapter

Which display adapter is installed.

Aspect

How the emulated picture is fitted into the window.

PhosphorMask

The phosphor arrangement behind the glass.

Video

The installed adapter, for read-only inspection.

Constants

MIN_IO_NS

The least an I/O port access costs, whatever the BusTiming says. Without it a while (inp(0x3DA) & 8) loop would never see time pass.

PIT_HZ

1.193182 MHz: the PC crystal (315/22 MHz) divided by 12.

Traits

DosGame

A DOS program.

Functions

run

Open a window and run G on an emulated PC.