Challenges found writing an 8k Lores Apple II Demo
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
by DEATER (Vince Weaver, vince@deater.net)
http://www.deater.net/weave/vmwprod/mode7_demo/
====================================================
19 March 2018
GOAL:
~~~~~
This started out as some SNES style mode7 pseudo-3d graphics code
I came up with while working on my TF7 game. The graphics looked
pretty cool, so I started developing a demo around it.
The codesize ended up being roughly around 8kB, so I thought I'd
make it into an 8k demo. There aren't many out there for the Apple II.
and a Mockingboard sound card.
The demo tries to hit the lowest common denominator for Apple II systems,
so in theory you could have run this on an Apple II in 1977 if you
were rich enough to afford 48k of RAM. The Mockingboard sound wasn't
available until 1981, but still this all predates the Commodore 64.
USING:
~~~~~~
Boot disk on a real system, or emulator with Mockingboard support.
Applewin works fine (even under Wine on Linux).
MESS does too, it's harder to setup (ROMs) but the audio sounds clearer.
If you have no emulator you can try one of the online javascript ones.
https://www.scullinsteel.com/apple2/
Hardware:
~~~~~~~~~
The Apple II has a 6502 processor running at roughly 1.023MHz.
Early models only shipped with 4k of RAM, but later 48k, 64k, and 128k
systems were common.
The most common disk drive was the Disk II which typically held
140k of data (single-sided).
The only sound available was a bit-banged speaker. No timer,
if you wanted music you had to cycle-count via the CPU.
Later some sound cards were available. This demo uses the
Mockingboard which has dual AY-3-8910 sound chips. Each
chip provides 3 channels of square waves, with noise and
envelope effects available.
GRAPHICS
~~~~~~~~
The Apple II had nice graphics for its time, with this time being
around 1977. Otherwise it is quite limited.
Hardware Sprites? No
Linear framebuffer? No
User-defined charset? No
Blanking interrupts? No
Palette selection? No
Hardware scrolling? No
Hardware page flip? Yes
The hi-res graphics mode was a complex mess of NTSC hacks by Woz.
You got 280x192 graphics, with 6 colors available. However the colors
were from NTSC artifacts and there were limitations on which colors
could be next to each other (in blocks of 3.5 pixels) as well as
fringing. Also the addresses were interleaved, so not a linear
framebuffer. Hi-res page0 is at $2000 and page1 at $4000.
Optionally 4 lines of text can be shown at the bottom of the
screen instead of graphics.
The lo-res mode is a bit easier to use. It is 40x48 blocks
(40x40 if 4 lines of text are displayed at the bottom).
15 colors are available, though there is fringing at the edges.
Again the addresses are interleaved. Lo-res page0 is at $400
and page1 is at $800.
========================================
DETAILED STEP-BY-STEP REVIEW OF THE DEMO
========================================
BOOTLOADER
~~~~~~~~~~
A BASIC "HELLO" program loads the binary.
This just makes things auto-boot at startup, this doesn't count
towards the executable size, you could manually BRUN the 8k program
if you wanted.
The binary is loaded at $2000 (hi-res page0) and BASIC kicks into
HIRES mode before loading so you can watch as the memory is loaded
from disk in a seemingly random pattern.
Since this is an 8k demo, the entirety of the program is shown on
the screen (or would be if we POKEd the right address to turn off
the 4 lines of text on the bottom of the screen).
Execution starts at address $2000
DECOMPRESSER
~~~~~~~~~~~~
The binary is LZ4 encoded. The decompresser flips to HGR page 1 so
we can watch memory as the program is decompressed.
The LZ4 decompression code was written by qkumba (Peter Ferrie).
http://pferrie.host22.com/misc/appleii.htm
The actual program/data decompresses to around 22k starting at $4000.
It over-writes parts of DOS3.3, but since we won't be using the disk
anymore this isn't an issue.
At the top left corner of the screen you'll see the VMW triangles logo
as it decompresses. To do this I had to put the proper bit pattern
at $4000, $4400, $4800, and $4C00. I mean to have some words too
but ran out of disk space. The bit pattern at $4000 is executable
and is run as code.
Optimizing for code size inside of a compressed binary is a pain.
Removing instructions sometimes made the binary larger as it no longer
compressed as well. Long runs of values (such as 0 padding) are
essentially free. This was a difficult challenge.
FADE EFFECT
~~~~~~~~~~~
The title screen fades in from black.
This is a software hack, with a lookup table copying from an off-screen
buffer. The Apple II doesn't have any palette support.
TITLE SCREEN
~~~~~~~~~~~~
Once things are decompressed, we jump to $4000. We switch to low-res
mode for the rest of the DEMO.
A background image is loaded from disk. This is RLE encoded (probably
unnecessary when being further LZ4 encoded).
Why not just load the program at $400 and load the graphics image for
free? Well, remember the graphics are 40x48 (shared with the text).
Really it's 40x24, with each text char mapping to 4-bits top/bottom
for color. Do the math, we have 1k reserved for this mode but 40x24
is only 960 bytes. It turns out there are "holes" in the address range
that aren't displayed, and various pieces of hardware use these holes
as scratchpad memory. So if you just blindly uncompress graphics data
there you can corrupt the scratchpad. So you have to be careful
when uncompressing to skip the holes.
The title screen has scrolling text at the bottom. This is nothing fancy,
the text is in a buffer off screen and a 40x4 chunk of RAM is copied in
every so many cycles.
You might notice that there is tearing/jitter in the scrolling, even
though we are double-buffering the graphics. This is because there is
not a reliable cross-platform way to get the VBLANK info (especially
on older machines) so we are having some bad luck about when we flip
pages.
MOCKINGBOARD MUSIC
~~~~~~~~~~~~~~~~~~
I like chiptune music, especially that for AY-3-8910 based systems.
Before obtaining a Mockingboard I built a Raspberry Pi chiptune player
that is essentially the same hardware.
Most of my sound infrastructure involves YM5 files, which are often used
by ZX Spectrum and ATARI ST users. These are usually register dumps
taken typically at 50Hz. So to play them back you just have to interrupt
50 times a second and write the registers.
To program the Mockingboard, each AY-3-8910 chip has 14 sound related
registers that control the 3 channels. Each AY chip has a dedicated
VIA 6522 parallel I/O chip that handles the I/O.
Doing this quickly enough is a challenge on the Apple II. For each
register you have to do a handshake, set the register # and the value.
This can take upwards of 40 1MHz cycles per register.
For complex chiptune files (especially those written on an ST with much
faster hardware) it's sometimes not possible to get exact playback
due to the delay. Also one AY is on the left channel and one on the right
so you have to write both if you want sound from both speakers.
I have a whole suite of code for manipulating YM sound data, in my
vmw-meter git repository.
The first step for getting this to work is detecting if a mockingboard is
there. This can be in any slot 1-7 on the Apple II, though typically
Slot 4 is standard (in this demo we only check slot 4).
The board is initialized, and then one of the 6522 timers is set to
interrupt at 25Hz (it has to be an on-board timer as the default
Apple II has no timers).
Why 25Hz and not 50Hz? At 50Hz with 14 registers you use 700 bytes/s.
So a 2 minute song would take 84k of RAM, much more than is available.
For this demo I run at 25Hz, and also pack the 14 registers of the data
into 11 (there are various fields that are not packed well, we can
unpack at play time). Also I stripped out the envelope data as many
songs do not use it (so this is a lossy compression method).
Also, we keep track of the last values written last frame and only
write out to the board if things change, which helps with the latency
a bit.
The sound quality suffered a bit, but it's hard to fit a catchy chiptune
file in 8K.
The song being played is a stripped down and re-arranged version of
"Electric Wave" from CC'00 by EA (Ilya Abrosimov).
MODE7 BACKGROUND
~~~~~~~~~~~~~~~~
"MODE7" was a Super Nintendo (SNES) graphics mode that took a tiled
background and transformed it to look as if it was squashed out to
the horizon, giving a 3d look. The SNES did this in hardware, but
in this demo we do this in software.
As found on Wikipedia, the transform is of the type
[x'] = [a b]([x]-[x0])+[x0]
[y'] [c d]([y] [y0]) [y0]
For our code, we managed to reduce things to a small number of additions
and subtractions for each pixel on the screen. Of course the 6502 can't
do floating point, so we do fixed point math. We convert as much as we
can to table lookups that are pre-calculated. We also make liberal use
of self-modifying code.
Despite all of this there are still some cases where we have to do a
16bit x 16bit = 32bit multiply, something that is *really* slow on 6502,
around 700 cycles (for a 8.8 x 8.8 fixed point multiply).
To make this faster we use a method described by Stephen Judd.
The key to note is that (a+b)^2 = a^2+2ab+b^2 and (a-b)^2=a^2-2ab+b^2
and if you add them you can simplify to:
(a+b)^2 (a-b)^2
a*b = --------- - -------
4 4
This is you have a table of squares from 0..511 (all 8-bit a+b and a-b
will fall in this range) then you can convert a multiply into a table
lookup plus a subtract.
The downsize is you will need 2kB of squares lookup tables (which can
be generated at startup). This reduces the multiply cost to the order
of 200 to 250 cycles.
By using the fast multiply and a lot of careful optimization you can
generate a Mode7 background in 40x40 graphics mode at about 5 frames/second.
The engine can be parameterized with different tilesets to use, which we
do to provide both a black+white checkerboard background, as well as the
island background from the TFV game.
BOUNCING BALL ON CHECKERBOARD
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
What would a demo be without some sort of bouncing geometric shape.
This is just done with 16 sprites. The sphere was modeled in OpenGL
from a 2000-era game-engine that I never finished. I then took screenshots
and then reduced the size/color to an appropriate value.
The shadow is also just sprites.
The clicking noise on bounce is just touching the speaker at $C030.
It's mostly there to give some sound effects for those playing the demo
without a mockingboard.
TFV SPACESHIP FLYING
~~~~~~~~~~~~~~~~~~~~
The spaceship, water splash, and shadows are all sprites. This is all
done in software, the Apple II has no sprite hardware.
This is the TFV game engine flying-spaceship code, with the keyboard
routines replaced to read from memory instead (sort of like a script
of what to do when).
STARFIELD
~~~~~~~~~
The starfield is your typical starfield code. Only 16 stars are modeled.
It re-uses the fast-multiply code from the mode7 graphics.
Random number generation is not fast on the 6502, so we cheat.
Originally we had a 256-byte blob of "random" values generated earlier.
This wasted space, so now instead we just treat the executable code
at $5000 as if it were a block of random numbers. This was arbitrarily
chosen, I tried different areas of memory until I got one where the
stars seemed to move in a pleasing pattern.
A simple state machine controls if the stars move or not, whether the
background is cleared or not (the streak effect) and what color the
background is (for the blue flash).
The ship moving to the distance is just done with different sized sprites.
RASTERBARS/CREDITS
~~~~~~~~~~~~~~~~~~
The credits happen with the starfield continuing to run.
The text is written in the bottom 4 lines of the screen. Some inverse-mode
space characters are used to try to make it look like graphics are surrounding
the text. It's actually possible with careful cycle counting to switch
modes fast enough to have actual mixed graphics/text (See the FrenchTouch
demos) but I was too lazy to attempt that here.
The rasterbar effect isn't really rasterbars, it's just a rainbow assortment
of lines being drawn with a SINEWAVE lookup table.
It's the same rasterbar code from my chiptune player demo. I ended up
optimizing it a lot via inlining and a few other ways because it turned
out just drawing a horizontal line can take a very long time.
The rotating text is just taking the output string and rapidly rotating the
character values through the ASCII table.
The annoying clicking noise is the same speaker effect caused by hitting
$C030.
Choosing who to thank ended up being extremely critical to fitting in 8kB,
as unique text strings do not compress well. I'm also still not satisfied
with how the centering looks.
Memory Map
==========
(not to scale)
-------- $ffff
| ROM/IO |
-------- $c000
| | 32k decompress
-------- $4000
| load | 8k
-------- $2000
| free |
-------- $1c00
| Scroll |
| Data |
-------- $1800
|Multiply|
| Tables |
-------- $1000
|GR pg 2 | 1k
|-------- $0c00
|GR pg 1 | 1k
|-------- $0800
|GR pg 0 | 1k
-------- $0400
| | 0.5
-------- $0200
| stack | 0.25
-------- $0100
|zero pg | 0.25
------- $0000
e0febd1a90
