Super Merryo Trolls

Heat Wave Effect Detail

To get this effect to work consistently, the stack-tweaking code had to consistently remain at the sides of the screen, even when the screen was scrolling across the level. So we had to erase and redraw the Assembly Language code each time, making sure to leave regular PEA instructions in its wake. If we were scrolling the level forward (terrain moving from right to left), we had to move our stripe of code upwards in memory, writing fresh PEA instructions below. And if we were scrolling the level back, we had to redraw the stripe of code downards in memory, writing PEA instructions above it. Listed below is the source code we wrote for the Merlin 16+ Assembler program to chew on, executed whenever we scroll one line forward:

    DO HeatWave
       phb                    ; save the bank register
       pea #>ForeFld
       plb
       plb                    ; set the bank to that of the PEA Field
]lp  = SizLine - CodeSiz
]lp2 = 0
       LUP #128               ; compiler directive: loop this 128 times
       lda #]lp2*$100 + $e5   ;   CODE: sbc ##
       sta ForeFld + ]lp,y    ; write this code into the PEA Field
]lp  = ]lp + SizLine          ; proceed to the next full line of PEAs
]lp2 = ]lp2 + 2               ; proceed to the next Direct Page word
       --^                    ; end of loop
]lp2 = 0
       LUP #62                ; loop this 62 times, total of 190 PEA lines
       lda #]lp2*$100 + $f5   ;   CODE: sbc ##,x
       sta ForeFld + ]lp,y
]lp  = ]lp + SizLine
]lp2 = ]lp2 + 2
       --^
       lda #$f41b             ;   CODE: tcs, pea #$xxxx
]lp  = SizLine - CodeSiz + 2
       LUP #190               ; loop this 190 times
       sta ForeFld + ]lp,y
]lp  = ]lp + SizLine
       --^
       plb                    ; restore the bank register
       FIN
 

When compiled, this generates a sequence of three unwound loops, bracketed by some code to keep things tidy. The first unwound loop is a series of 128 LDA and STA instructions, like so:

       lda #$00E5
       sta $20ED,y
       lda #$02E5
       sta $21DD,y
       lda #$04E5
       sta $22CD,y
       lda #$06E5
       sta $23BD,y
       lda #$08E5
       sta $24AD,y
       lda #$0AE5
       sta $259D,y
      ...

So what does this code do? Well, it appears to be loading an ever-increasing value into the A register, and storing it into memory at widely-spaced but regular intervals. The Bank register has been set beforehand, so all the STA commands are storing into the memory bank where we keep the PEA Field. The PEA Field starts at offset $2000 within the bank, and a full row's worth of pixel data and PEA instructions is $F0 bytes long, so the first STA is storing its value to the spot just three bytes before the first row ends. And the second STA is storing to the spot just before the second row ends, and so on.

The Y register is also being added to the location of each STA, so by setting the Y register beforehand, we can account for the scrolling of the screen. Setting Y to #$0003 before we run this code will cause all these writes to take place three bytes further down in memory, which is one PEA instruction further along. So this unwound loop is reusable, no matter where the PEA field has scrolled to. It can be used to draw the stripe of code anywhere we need it.

Now here's a snippet of the third unwound loop that the source code generates:

       lda #$F41B
       sta $20EF,y
       sta $21DF,y
       sta $22CF,y
       sta $23BF,y
       sta $24AF,y
       sta $259F,y
      ...

Here, we're storing the same value into each place in memory, so we only need to load the A register with it once, and then we can do all 190 stores in a row. Note that the locations of each STA match up with the locations in the first unwound loop - except that each one is exactly two bytes further along in memory. That's because the first loop wrote one half of the stripe, and this final loop is writing the other half. The halves combine to make four bytes of code written together at regular intervals in the PEA Field.

So what is actually being written into the PEA Field? Well, let's look at the first value we load, in the first loop: #$00E5. The Apple IIgs CPU uses a little-endian architecture, so when we store that into memory it will become the sequence "$E5 $00". The third loop stores #$F41B into memory just after that, creating the four byte sequence "$E5 $00 $1B $F4".

Here's what that sequence means in Assembly Language:

       sbc $00          ; $E5 00
       tcs              ; $1B
       pea #$????       ; $F4 ?? ??

There are question marks at the end because we don't know what data the PEA instruction is going to push. We've written the $F4, invoking the PEA, but we don't know what comes after it in memory, past our four byte sequence. Actually it doesn't matter what's there, because that data is going to be overwritten later on by the block-drawing routine, when it draws the stripe of graphics that have just been scrolled onto the screen. What we've done here is make sure that the necessary PEA instruction exists.

So how does it all come together? Suppose we want to draw our graphics to the screen. We set all the registers up, tweak some softswitches, and then jump headlong into the PEA Field. Along comes the computer's CPU, executing PEA instructions in the field, pushing data onto the screen:

      ...
       pea #$3033
       pea #$0100
       pea #$1111
       pea #$4411
      ...

When it nears the end of the first row, it encounters this:

      ...
       pea #$1000
       pea #$0000
       pea #$5533
       sbc $00
       tcs
       pea #$0000
       pea #$1000
       pea #$1111
      ...

... And keeps on going, merrily executing the PEAs for the second row.

SBC stands for Subtract With Carry. It does some math on the A register. This particular variation of SBC is subtracting the value it finds in Direct Page location $00 from the A register. (For a description of the Direct Page, see the main document.) The next instruction after that is TCS, which transfers the contents of the A register into the stack pointer, overwriting the old value. So the next row of screen data no longer has to pick up exactly where the last row left off. It can begin wherever it wants - wherever the new stack pointer points to.

At the end of the second row, the CPU encounters this:

      ...
       pea #$7677
       pea #$7777
       pea #$7777
       sbc $02
       tcs
       pea #$0000
       pea #$1110
       pea #$1011
      ...

Which performs another subtraction on the A register, this time using the value that's in Direct Page location $02, instead of location $00. The value goes into the stack pointer just like before, and the third row begins. Since this is the Heat Wave effect, it probably appears on the screen slightly askew from the second.

This pattern continues, subtracting a different value loaded from the Direct Page for each line. Because each line gets its own value, we can set the offset for each line independantly. In the case of Heat Wave, this means that some lines can get only slightly skewed, while others get very skewed, making the whole effect transition smoothly from calm at the top to manic at the bottom, like real heat rising from the desert floor. It can also change over the course of the game. How did we make the effect scroll smoothly up the screen? Elementary, my dear Watson. We just chose a slightly different pointer for the Direct Page each time, in a loop the size of a wave.

But there's one more problem to solve: Each line needs its own independent value in the Direct Page. The Direct Page can be used to address 256 bytes - or 128 16-bit values. That covers the first 128 lines just fine. But what about the remaining 62?

That's what the second unwound loop described in our source code is for. It generates a sequence like so:

       lda #$00F5
       sta $98ED,y
       lda #$02F5
       sta $99DD,y
       lda #$04F5
       sta $9ACD,y
       lda #$06F5
       sta $9BBD,y
       lda #$08F5
       sta $9CAD,y
       lda #$0AF5
       sta $9D9D,y
      ...

This sequence looks a lot like the first loop, except it's writing further down in memory. In fact, it's picking up where the first loop left off, completing the stripe of code. The crucial difference between the two loops is that the $E5 in each LDA of the first loop has been replaced with an $F5.

We saw above that $E5 represents "SBC $??". The $F5 here represents "SBC $00,x". By loading the X register with #$0100 before jumping into the PEA Field, we can use it to refer to memory just beyond the usual reach of the Direct Page. Thus, we can provide independent values for all 190 lines of the display. Hah!

So, all in all, we've written macro code that automatically unwinds into Assembly Language code whose purpose is to dynamically modify other Assembly Language code, which is then executed by the CPU whenever we draw a screenful of graphics. If you had to do this in any of your CS classes, let me know. I'll be surprised.

The contents of the memory pointed to by the Direct Page are left as an exercise to the reader. As an aid to understanding it, consider that filling the whole region with the value #$00F0 will make the screen draw normally. (Remember, the stack pushes backwards, and the rows are also in reverse order.)