pcjs/tests/pc/vga/README.md

VGA Tests

To aid in the development of PCjs VGA support, I've started adding some VGA tests to the project. For now, the only "tests" are samples taken directly from Michael Abrash's Graphics Programming Black Book.

Abrash's book is available on many sites, but I'm partial to the Markdown version that James Gregory has made available on GitHub, because (a) it's a brilliant way to render and share the text, and (b) it apparently has Abrash's blessing, so I feel more comfortable forking it, using it, and resharing it.

The main reasons for my fork: to make the book's images display properly on GitHub, and to extract and add assorted source code listings as I need them. Since that project's /src folder contains just the book's text, I've added a /code folder for the source code listings. The name of each source code file matches the name displayed in the text (eg, L23-1.ASM is Listing 23.1 from Chapter 23).

I assume something similar was done on the CD-ROM that accompanied the Black Book, but since I don't have the original book or its CD-ROM, I'm extracting the source code directly from the Markdown text, and then "tabifying" it with 8-column tab stops.

Development of PCjs VGA support has just begun (June 2015), so don't expect everything here to to run properly yet.

---

List of VGA Samples from Michael Abrash's Graphics Programming Black Book:

• Chapter 23: Bones and Sinew
  • L23-1.ASM: Animates four balls bouncing around a playfield by using page flipping and panning
• Chapter 24: Parallel Processing with the VGA
  • L24-1.ASM: Illustrates operation of ALUs and latches of the VGA's Graphics Controller
• Chapter 25: VGA Data Machinery
  • L25-1.ASM: Illustrates operation of data rotate and bit mask features of Graphics Controller
  • L25-2.ASM: Illustrates operation of Map Mask register when drawing to memory that already contains data
  • L25-3.ASM: Illustrates operation of set/reset circuitry to force setting of memory that already contains data
  • L25-4.ASM: Illustrates operation of set/reset circuitry in conjunction with CPU data
• Chapter 26: VGA Write Mode 3
  • L26-1.ASM: Illustrates operation of write mode 3 of the VGA
  • L26-2.ASM: Illustrates high-speed text-drawing operation of write mode 3 of the VGA
• Chapter 27: Yet Another VGA Write Mode
  • L27-1.ASM: Illustrates one use of write mode 2 of the VGA and EGA by animating the image of an "A"
  • L27-2.ASM: Illustrates one use of write mode 2 of the VGA and EGA by drawing lines in color patterns
  • L27-3.ASM: Illustrates flipping from bit-mapped graphics mode to text mode and back
• Chapter 28: Reading VGA Memory
  • L28-1.ASM: Illustrates the use of the Read Map register in read mode 0
  • L28-2.ASM: Illustrates use of read mode 1 (color compare mode) to detect collisions in display memory
  • L28-3.ASM: Illustrates the use of Color Don't Care to support fast read-modify-write operations
• Chapter 29: Saving Screens and Other VGA Mysteries
  • L29-1.ASM: Puts up a mode 10h EGA graphics screen, then saves it to the file SNAPSHOT.SCR
  • L29-2.ASM: Restores a mode 10h EGA graphics screen from the file SNAPSHOT.SCR
  • L29-3.ASM: Illustrates the color mapping capabilities of the EGA's palette registers
  • L29-4.ASM: Demonstrates screen blanking via bit 5 of the Attribute Controller Index register
• Chapter 30: Video Est Omnis Divisa
  • L30-1.ASM: Demonstrates the VGA/EGA split screen in action
  • L30-2.ASM: Demonstrates the interaction of the split screen and horizontal pel panning
• Chapter 31: Higher 256-Color Resolution on the VGA
  • L31-1.ASM: Demonstrates pixel drawing in 320x400 256-color mode on the VGA
  • L31-2.ASM: Demonstrates the two pages available in 320x400 256-color modes on a VGA
• Chapter 32: Be It Resolved: 360x480
  • L32-1.ASM: Illustrates VGA line drawing in 360x480 256-color mode
  • L32-2.C: Sample program to illustrate VGA line drawing in 360x480 256-color mode
• Chapter 33: Yogi Bear and Eurythmics Confront VGA Colors
  • L33-1.ASM: Demonstrates use of the DAC registers by selecting a smoothly contiguous set of 256 colors
• Chapter 34: Changing Colors without Writing Pixels
  • L34-1.ASM: Fills a band across the screen with vertical bars in all 256 attributes
• Chapter 35: Bresenham Is Fast, and Fast Is Good
  • L35-1.C: C implementation of Bresenham's line drawing algorithm
  • L35-2.C: Sample program to illustrate EGA/VGA line drawing routines
  • L35-3.ASM: Fast assembler implementation of Bresenham's line drawing algorithm
• Chapter 47: Mode X: 256-Color VGA Magic
  • L47-1.ASM: Mode X (320x240, 256 colors) mode set routine
  • L47-2.ASM: Mode X (320x240, 256 colors) write pixel routine
  • L47-3.ASM: Mode X (320x240, 256 colors) read pixel routine
  • L47-4.ASM: Mode X (320x240, 256 colors) rectangle fill routine (slow)
  • L47-5.ASM: Mode X (320x240, 256 colors) rectangle fill routine (medium)
  • L47-6.ASM: Mode X (320x240, 256 colors) rectangle fill routine (fast)
  • L47-7.C: Program to demonstrate mode X (320x240, 256-colors) rectangle fill

---

Also, I've updated the PCjs Library disk collection to include a disk image of this directory:

<disk path="/tests/pc/vga/">VGA Tests (Black Book)</disk>

When path refers to a directory (ending with a slash) instead of a disk image, the PCjs client will ask the PCjs web server to enumerate the contents of that directory and send back a JSON-encoded disk image containing all the files in that directory (including any subdirectories) every time that disk is requested. Since this puts an added burden on the server, it's best to do this only when running PCjs from a local PCjs web server.

Since the contents of this particular directory will probably be in flux for a while, I've opted for this approach. Once things settle down, I'll generate a JSON-encoded disk image containing a snapshot of this directory, using the PCjs DiskDump module:

diskdump --dir=. --format=img --output=TESTVGA.img --overwrite

One advantage of using DiskDump is that it automatically converts linefeeds in known text files (including ASM files) into DOS-compatible CR/LF sequences.

I've updated a Compaq DeskPro 386 Machine to use the Library disk collection and automatically load the above disk:

<fdc ref="/disks/pc/library.xml"
     width="340px"
     automount='{A: {name: "PC-DOS 3.00 (Disk 1)",
                     path: "/disks/pc/dos/ibm/3.00/PCDOS300-DISK1.json"},
                 B: {name: "VGA Tests (Black Book)",
                     path: "/tests/pc/vga/"}
     }' />