Skip to content
VGA-style video output for STM32F4 processors, in Rust
Branch: master
Clone or download
cbiffle Propagate measurement feature from m4demos to m4vga.
Warning: the way features work in Cargo virtual workspaces is incredibly
hard to understand. Here's what you need to do to have this feature
actually work:

  cd m4demos
  cargo build --feature measurement

Attempting to do it from the workspace root will *silently do the wrong
Latest commit 66e462a Jun 2, 2019
Type Name Latest commit message Commit time
Failed to load latest commit information.
.cargo Fork linker script to allow code in RAM. Jan 29, 2019
doc Update README, split port notes into separate doc. Jun 2, 2019
font_10x16 Split font_10x16 into separate crate. Mar 12, 2019
m4demos Propagate measurement feature from m4demos to m4vga. Jun 2, 2019
m4vga m4vga: add portable bitmap_1 unpacker. Jun 2, 2019
math math: add Vec3::map Mar 12, 2019
notes gfx: port C++ line drawing routine, with tests! Feb 27, 2019
stlmunge stlmunge: make normals available. Mar 17, 2019
wasmdemos wasmdemos: add restart button Jun 2, 2019
.cargo-ok Sketching Jan 16, 2019
.gitignore Update and lock deps. May 30, 2019
.rustfmt.toml rustfmt: change some defaults Mar 12, 2019
.travis.yml Prepare for wasmdemos not being tunnel-specific. Jun 1, 2019
Cargo.lock Add Conway to web demo. Jun 2, 2019
Cargo.toml fx/conway: factor out of conway demo Jun 2, 2019
LICENSE Add a license before publication. Jan 29, 2019 Document wasm build in README. Jun 2, 2019
link-custom.x Fork linker script to allow code in RAM. Jan 29, 2019
openocd.cfg Fix things I noticed by trying to run it. Jan 28, 2019
openocd.gdb Simplify GDB config. Jan 30, 2019


Build Status

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?


Recording of the tunnel demo on a small monitor

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.)


$ 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
You can’t perform that action at this time.