<commit_before>This is a collection of demos which, together, show how to use [m4vgalib] to
produce high-quality graphics on an STM32F4 with few external components.

For more information about the approach used, see [m4vgalib].


Prerequisites
=============

I've tested this code most thoroughly using GCC 4.8.3 produced by the
[GCC ARM Embedded] 2014q1 recipe.  These demos do not rely heavily on the C
library, so the fact that the GCC ARM Embedded folks have chosen a very unusual
Newlib configuration won't hurt you.

Most of the code *compiles* with CLang, but I haven't tested an ARM binary
produced by CLang.


Using the Demos
===============

To prepare a fresh clone:

    $ ./bootstrap.sh

To build:

    $ cd build
    $ ./cobble build

Firmware images will be left in `build/demo/*/demo`.  To flash one onto an
STM32F4DISCOVERY board:

    $ ./flash.sh build/latest/demo/rook/demo

(Note that you will need to have wired up the video circuit, described below,
to see any results.)

To do the same through GDB, which is more useful if you're hacking on a demo:

    $ openocd &
    $ ./gdb.sh build/latest/demo/rook/demo
    gdb> flash

To clean:

    $ rm -rf build
    $ ./bootstrap.sh


Tour of the Demos
=================

Each demo has its own `README` file.  To learn more about a demo and which
parts of m4vgalib it exercises, see `demo/*/README.mkdn`.  Here's a brief
overview of each.

All of the demos are stable at 60fps unless otherwise noted.

 - **blt**: a boring demo of m4vgalib's bitblt support (somewhat buggy).
 - **conway**: cellular automata demonstration, achieving almost 29 million
   cell updates per second while generating 800x600 video.
 - **hires_mix**: mixed character and pixel graphics at 800x600.
 - **hires_text**: 80x37 high-res attributed character mode.
 - **horiz_tp**: alternating white/black vertical stripes, which is sometimes
   useful for getting an ornery monitor to sync properly.
 - **midres_graphics**: simple pixel graphics at 640x480.  This exercises
   m4vgalib's 640x480 mode support, but it's not very interesting because I'm
   way more excited about the hires modes.
 - **rook**: realtime wireframe rendering of a piece from [my chess set].
   Perspective projection, rotation, etc.
 - **serial**: a basic "glass teletype."  Accepts input on a UART, prints it
   on the display.
 - **tunnel**: old-school demoscene animation, rendered using chunky pixel
   graphics inside an 800x600 mode.
 - **xor_pattern**: full-screen procedural texture generation.


Connections
===========

The demos assume an 8MHz oscillator, which happens to be the type used on the
STM32F4DISCOVERY board.

[m4vgalib] assumes the following connections:

Pin(s) | Signal | Description
-------|--------|------------
C6     | HSYNC  | governs monitor's horizontal timing
C7     | VSYNC  | governs monitor's vertical timing
C8     | sig B  | used for benchmarking
C9     | sig A  | used for benchmarking
E15:8  | video  | feed to video DAC

The demos further assume that only the bottom six pins of video are connected,
and that they have the following roles:

Pin(s) | Signal | Description
-------|--------|------------
E9:8   | R1:0   | red channel
E11:10 | G1:0   | green channel
E13:12 | B1:0   | blue channel

So while m4vgalib can do 256-color modes, these demos assume 64-color mode,
largely to allow use of a trivial six-resistor R2R ladder DAC on a breadboard.


[m4vgalib]: https://github.com/cbiffle/m4vgalib
[my chess set]: http://cliffle.com/thing/chess-set-i/
[GCC ARM Embedded]: https://launchpad.net/gcc-arm-embedded
<commit_msg>Note joystick, button pins in README.<commit_after>This is a collection of demos which, together, show how to use [m4vgalib] to
produce high-quality graphics on an STM32F4 with few external components.

For more information about the approach used, see [m4vgalib].


Prerequisites
=============

I've tested this code most thoroughly using GCC 4.8.3 produced by the
[GCC ARM Embedded] 2014q1 recipe.  These demos do not rely heavily on the C
library, so the fact that the GCC ARM Embedded folks have chosen a very unusual
Newlib configuration won't hurt you.

Most of the code *compiles* with CLang, but I haven't tested an ARM binary
produced by CLang.


Using the Demos
===============

To prepare a fresh clone:

    $ ./bootstrap.sh

To build:

    $ cd build
    $ ./cobble build

Firmware images will be left in `build/demo/*/demo`.  To flash one onto an
STM32F4DISCOVERY board:

    $ ./flash.sh build/latest/demo/rook/demo

(Note that you will need to have wired up the video circuit, described below,
to see any results.)

To do the same through GDB, which is more useful if you're hacking on a demo:

    $ openocd &
    $ ./gdb.sh build/latest/demo/rook/demo
    gdb> flash

To clean:

    $ rm -rf build
    $ ./bootstrap.sh


Tour of the Demos
=================

Each demo has its own `README` file.  To learn more about a demo and which
parts of m4vgalib it exercises, see `demo/*/README.mkdn`.  Here's a brief
overview of each.

All of the demos are stable at 60fps unless otherwise noted.

 - **blt**: a boring demo of m4vgalib's bitblt support (somewhat buggy).
 - **conway**: cellular automata demonstration, achieving almost 29 million
   cell updates per second while generating 800x600 video.
 - **hires_mix**: mixed character and pixel graphics at 800x600.
 - **hires_text**: 80x37 high-res attributed character mode.
 - **horiz_tp**: alternating white/black vertical stripes, which is sometimes
   useful for getting an ornery monitor to sync properly.
 - **midres_graphics**: simple pixel graphics at 640x480.  This exercises
   m4vgalib's 640x480 mode support, but it's not very interesting because I'm
   way more excited about the hires modes.
 - **rook**: realtime wireframe rendering of a piece from [my chess set].
   Perspective projection, rotation, etc.
 - **serial**: a basic "glass teletype."  Accepts input on a UART, prints it
   on the display.
 - **tunnel**: old-school demoscene animation, rendered using chunky pixel
   graphics inside an 800x600 mode.
 - **xor_pattern**: full-screen procedural texture generation.


Connections
===========

The demos assume an 8MHz oscillator, which happens to be the type used on the
STM32F4DISCOVERY board.

[m4vgalib] assumes the following connections:

Pin(s) | Signal | Description
-------|--------|------------
C6     | HSYNC  | governs monitor's horizontal timing
C7     | VSYNC  | governs monitor's vertical timing
C8     | sig B  | used for benchmarking
C9     | sig A  | used for benchmarking
E15:8  | video  | feed to video DAC

The demos further assume that only the bottom six pins of video are connected,
and that they have the following roles:

Pin(s) | Signal | Description
-------|--------|------------
E9:8   | R1:0   | red channel
E11:10 | G1:0   | green channel
E13:12 | B1:0   | blue channel

So while m4vgalib can do 256-color modes, these demos assume 64-color mode,
largely to allow use of a trivial six-resistor R2R ladder DAC on a breadboard.

The interactive demos assume a five-way switch joystick and an action button,
all of which are normally open and pull to ground when pressed.

Pin | Signal | Description
----|--------|------------
A4  | Left   | Joystick Left
A6  | Up     | Joystick Up
B15 | Down   | Joystick Down
B14 | Right  | Joystick Right
B13 | Center | Joystick Press
A0  | User   | User (Action) Button

The Joystick pins are identical to those used on the WaveShare Open407V-D board,
with the exception of Right, which must be jumpered.

The User Button is the blue button on the STM32F4DISCOVERY board.

[m4vgalib]: https://github.com/cbiffle/m4vgalib
[my chess set]: http://cliffle.com/thing/chess-set-i/
[GCC ARM Embedded]: https://launchpad.net/gcc-arm-embedded

{'fraction_non_alphanumeric': 0.10393619758168253, 'fraction_numerical': 0.026112683303318753, 'mean_word_length': 3.4151050539466214, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 5, 'https://': 4, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3540766', 'n_tokens_mistral': 2527, 'n_tokens_neox': 2288, 'n_words': 1040}