A Tour of the Mad Pascal Samples: Ten Programs Worth Building

Six Atari screenshots in a grid: a Nyan Cat in chunky pixels, a brown and blue swirl, a yellow wireframe cube, a blue dithered plasma, a green and purple twister, and rows of coloured space invaders above a green ground line

The Mad Pascal repository on GitHub (tebe6502/Mad-Pascal) includes a samples/a8 folder with 38 subfolders of Atari programs: graphics, sound, interrupts, file I/O, compression, games and demo effects. It is the best way to learn the compiler's libraries, but there is little guidance on where to start. We built and ran ten of them, chosen to cover different parts of the system, and this guide says what each one shows and what to look for in its source.

What you need: a working Mad Pascal setup: the compiler mp, MADS, and the repository's lib, base and blibs folders. Mad Pascal: Installing It and Writing Your First Game covers installation and the language. We used Mad Pascal 1.7.9 (the Windows mp.exe, run under Wine on Linux, in a Wine prefix of its own) with a native MADS, and ran the results in atari800 (XL/XE, NTSC).

Building a sample

Every sample builds the same two-step way. From the sample's own folder (some include resource files by relative path):

mp  nyan.pas  -ipath:<MP>/lib -ipath:<MP>/blibs
mads nyan.a65 -x -i:<MP>/base -o:nyan.xex

mp writes nyan.a65. MADS assembles it with the runtime from base into an executable. The blibs path is only needed by samples that use bocianu's extra units, but it does no harm. All ten samples below compiled without changes, and each one ran.

A few source features recur, so it helps to know them before you read:

  • {$r file.rc} links resources: a .rc file lists labels, a type and a file name, and the data lands at the address the label names. This is how pictures, fonts and music get into a program.
  • {$define romoff} tells the runtime to switch the OS ROM out so that the RAM underneath can be used, as two of the samples do.
  • procedure ...; interrupt; and SetIntVec install VBI and DLI routines written in Pascal or inline assembly.
  • absolute places a variable at a fixed address, for example var sine: array [0..255] of byte absolute $0600.

1. demoeffects/3d.pas: a rotating cube

A wireframe cube spins in GRAPHICS 7. It is short and shows three things:

  • float16, Mad Pascal's half-precision floating-point type, used for the rotation with sin and cos.
  • The fastgraph unit's fLine for drawing.
  • Double buffering with NewDisplayBuffer (two GRAPHICS 7+16 screens, one below RAMTOP $C0 and one below $A0) and SwitchDisplayBuffer, called once a frame after pause. The screen you see is never the one being drawn, so the cube doesn't flicker.

2. demoeffects/bobs.pas: the snake-bob illusion

A 1994 effect by Bill Kendrick, ported to Mad Pascal. One circle is drawn per frame with Circle from the graph unit, in GRAPHICS 6. The program keeps three copies of the screen in an array and cycles through them, copying each to the display with Move, drawing the new circle and copying it back. Each circle therefore reappears every third frame and the eye sees a long snake of moving balls. Kendrick's comments in the source explain why it takes three frames rather than two: with two you would see motion but no direction.

3. demoeffects/plasma.pas: a character-set plasma

This plasma, credited to groepaz/hitmen, runs in plain GRAPHICS 0. The makechar procedure builds a 128-character font of dither patterns with increasing numbers of set pixels, and the program points CHBAS (location 756) at it. Every frame, doplasma adds up entries from a 256-byte sine table, using two pairs of moving offsets for the rows and columns, and writes the result into the 40 × 24 text screen. Changing 960 bytes a frame is far cheaper than redrawing a bitmap, and it is a good example of treating a text mode as a low-resolution graphics mode.

4. demoeffects/twister.pas: Pascal plus assembly

A twisting column in GRAPHICS 7, drawn row by row as four horizontal spans whose edges come from a sine table. The table is built at run time by FillSinLow from the fastmath unit into a fixed array at $0600. The span routine h_line is written as an assembler procedure using left and right edge masks. It is a good model for mixing a Pascal main loop with an assembly inner loop, which is how most fast Mad Pascal programs are built.

5. graph_mode_10pp/nyan.pas: GTIA 10++

A Nyan Cat animation in chunky square pixels. It uses the gr10pp unit from bocianu's blibs, which builds a display list of GTIA mode lines stretched by vertical-scroll tricks, with a DLI that rewrites VSCROL, and sets GPRIOR to $81 (GTIA mode 10, nine colours from the player and playfield colour registers). The animation itself is just Move calls copying 26 × 19-byte frames out of a resource into screen memory. See GTIA 9++: Square Pixels and a Quarter of the DMA for how the trick works.

6. graph_mode_4pp/foxmode.pas: mode 4++

The same idea applied to ANTIC mode 4 characters: the gr4pp unit (by bocianu and tebe) describes it as 160 × 240 or 80 × 60 in five colours. The sample loads a font and a screen as resources and shows a dithered picture. It also shows {$define romoff} (font, screen and display list sit at $C000–$D800, under the OS ROM) and a small VBI in inline assembly that resets VSCROL and CHBASE each frame.

7. games/invaders.pas: a complete small game

Invaders by Victor Parada (2016), ported to Mad Pascal by Tebe in the same year. It uses only the standard crt, graph, joystick and math units, with the graphics for the invaders packed into one 78-byte constant array. It is a compact example of a whole game loop in Pascal, and a contrast to the more library-heavy samples. Note the trick at the start: InitGraph(24) followed by InitGraph(0), which the comments explain clears the upper 8K of RAM and then sets up the playfield.

8. graph_crossplatform/mandel.pas: the price of floating point

A Mandelbrot set, adapted from a Turbo Pascal program in Roger T. Stevens's Fractal Programming in Turbo Pascal. It uses the Single (32-bit float) type and the portable graph unit, so the same source builds for other Mad Pascal targets. On the Atari it is a lesson in cost: after 90 seconds, only about a quarter of the picture had appeared. Compare it with the integer-only samples above, and keep floats out of anything that has to run every frame.

9. sound/cmc/default_song/cmc_play.pas: music with the CMC unit

This plays a Chaos Music Composer tune (tekkno.cmc, linked as a resource) through the cmc unit. The player is linked to $F000 under the OS ROM, again with romoff, and the module to $4000. The main loop is simply pause then msx.play once per frame, until a key is pressed. The screen printed Player under OS ROM at $F000., and with the emulator's monitor we could see POKEY's channels being driven while it ran. A neighbouring folder, song_selection, shows how to pick a song within a module, and sound/rmt does the same for Raster Music Tracker files.

10. interrupt/dli_vbl/dli_vbl.pas: display lists and interrupts in Pascal

This one shows two custom display lists written as constant byte arrays (including a mixed screen of GRAPHICS 0, 1, 2 and 12 lines), a VBI that plays RMT music, and DLIs that put colour bars down the sides of the screen. Its title screen reads "RMT-DL-VBL-DLI with MAD Pascal", and it detects PAL or NTSC for correct music speed. Read it next to Display Lists Explained and Vertical Blank Interrupts to see how the hardware techniques translate into Pascal.

Where to go next

The other folders are worth browsing once these make sense: sprite (software sprites), graph_pmg (players and missiles), io_file and io_sparta_dos_x (disk files and SpartaDOS X), compression (LZ4, deflate and others), extra_ram (130XE banks), graph_vbxe (VBXE graphics) and many more in games and demoeffects. Most samples are small enough to read in one sitting, and they are the quickest way to see a unit from lib in use.

Troubleshooting

  • "Can't find unit" errors: pass both -ipath options, and build from the sample's folder so relative resource paths work.
  • The program assembles but crashes at once: check that MADS was given -i:<MP>/base, and that mp and the base folder come from the same release.
  • mp.exe won't start under Wine: a 64-bit-only Wine prefix can't run it. Create a new prefix for it, or build mp natively with Free Pascal.
  • A ROM-off sample hangs on your own machine setup: it needs an XL/XE with RAM under the OS. These samples won't run on a 400/800.
  • The Mandelbrot never finishes: it does, eventually. Lower max_iterations in the source to speed it up.

Further reading

  • The Mad Pascal documentation (English and Polish) linked from the repository's README, and the unit headers in lib, which document each procedure.
  • bocianu's blibs documentation in the blibs/doc folder.
  • On this site: Mad Pascal: Installing It and Writing Your First Game, GTIA 9++: Square Pixels and a Quarter of the DMA, Software Sprites in GRAPHICS 7, Getting Started with RASTER Music Tracker, and the Chaos Music Composer and Mad Pascal entries in the software section.

Credits