m4vga-rs

This crate provides 800x600 60fps graphics on the STM32F407 microcontroller. The observant reader will note that the STM32F407 has no video hardware, or enough RAM to hold an 800x600 color image. So how does m4vga get high-res color video out of it?

Magic.

This is a rewrite of my C++ library m4vgalib, plus ports of my collection of m4vgalib demos. It is still a work in progress. (If you're curious, see my notes on the port.)

(As of quite recently, several of the demos also compile for another platform without video hardware: WebAssembly.)

Why this is interesting

Mostly because it's really hard. I've got four CPU cycles per pixel to work with, and any variation in timing will corrupt the display.

The Demos

The demo main files live in m4demos/src/bin, though the core implementations of several of the demos have migrated into the fx directory.

• conway: full-screen Conway's Game of Life at 60fps -- that's 28.8 million cell updates per second, for a budget of 5 cycles per update (not counting video generation).

• hires_text: 80x37 text mode. Each character has adjustable foreground and background colors. This is boring to watch but technically interesting.

• horiz_tp: generates a display calibration pattern of vertical stripes. This also demonstrates how to write a simple m4vga-based demo in 40 lines of code.

• poly3: a tumbling dodecahedron made of solid polygons, with basic lighting.

• rook: high-resolution 3D wireframe model with thousands of polygons, plus scrolling text. (The model is from my chess set).

• rotozoom: old-school texture transform effect providing rotation and scaling. This is chunky (400x300) to save RAM...which is still too much data to double-buffer. This uses a trick to prevent tearing.

• tunnel: demoscene "tunnel zoomer" effect drawing shaded textured graphics at 60fps. (This one is also 400x300, but it's hard to notice at speed.)

• xor_pattern: fullscreen procedural texture with smooth scrolling. Demonstrates how to add a custom assembly language raster function.

Building it

All of this is tested only on Linux, but it should work on Mac -- though you'll have to translate the commands below to your package manager of choice.

Web target

I recently made the core of m4vga portable, and I'm gradually porting demos to run on WebAssembly. While this is less exciting than running on a real, resource-starved microcontroller, it gives you a way to test out the code without having to move a bunch of wires around.

First, follow the Rust WASM setup guide here. In short, you will need Rust, wasm-pack, and npm. (Debian/Ubuntu users: the ancient npm in apt will not work.)

Now:

$ wasm-pack build -- -p m4vga-wasm-demos
$ (cd www; npm run start)

Point a browser at http://localhost:8080/ and you should be able to view the demos!

Microcontroller target

You will need an STM32F407-based board to run this on; I use the STM32F4-Discovery because it's really cheap. Hook it up to a VGA connector according to my instructions for C++.

I recommend following the setup chapters from the Rust Embedded book. In particular, you need to have Rust and you need to make Rust aware of the cross compilation target we're using here:

$ rustup target add thumbv7em-none-eabihf

You will also need a GNU ARM toolchain to compile the assembly language routines. On Arch:

$ sudo pacman -S arm-none-eabi-{gcc,newlib}

On Ubuntu, the system ships an ancient version of GCC, but since we're only assembling this is okay:

$ sudo apt-get install gcc-arm-none-eabi

Now you should be able to compile everything by entering:

$ cargo build --release

This will deposit several demo binaries in target/thumbv7em-none-eabihf/release/.

And if you start openocd (tested with version 0.10) in this directory, it will pick up the openocd.cfg file automagically, and (from a separate terminal) you can flash one of the demos by typing:

$ cargo run --release --bin horiz_tp