clean up and document new explosion.s

1 files changed, 59 insertions, 34 deletions

diff --git a/explosion.s b/explosion.s
index a803d5e..a4e461f 100644
--- a/explosion.s
+++ b/explosion.s
@@ -1,77 +1,102 @@
 ; explosion seen when we're hit by enemy fire.
-; currently just flashes the screen. the apple version is
-; kinda funky-looking, best way I can describe it is that it
-; looks like TV static. would be hard to imitate that on the
-; atari. maybe there should be screen-shaking going on?
-
-; original code was in C, and looked like:
-;; for(i = 0; i < 3; i++) {
-;; 	unsigned char color = PEEK(710) & 0xf0;
-;; 	unsigned char textcolor = PEEK(709);
-;; 	POKE(709,0);
-;; 	POKE(710, color | 0x0c);
-;; 	jsleep(10);
-;; 	POKE(710, color & 0xf0);
-;; 	jsleep(10);
-;; 	POKE(709,textcolor);
-;; }
+; this draws something that looks a bit like TV static, only
+; it's a lot more regular and less random. it somewhat approximates
+; the apple version's explosion, but not all that closely.
 
  .export _explosion
  .include "atari.inc"
  .importzp tmp1, tmp2
  .import _jsleep
 
-iloop_count = tmp1
+static_loop_count = tmp1
 
 ; extern void explosion(void);
-_explosion:
 ; {
+_explosion:
 
- ldy #3 ; loop counter, counts 3 2 1
+ ldy #3 ; explosion_loop counter, counts 3 2 1
 
 ;   {
-@loop:
- lda #$03
- sta iloop_count
+@explosion_loop:
+ lda #$03 ; static_loop runs 3 times
+ sta static_loop_count
 
-@iloop:
+;     {
+@static_loop:
  ldx #0         ; jsleep(2)
  lda #$02
  jsr _jsleep
 
  ldx #2
-@b:
+
+;         {
+;           {
+; let the top part of the screen display normally.
+; garbage begins to display on gr.0 line 8 (the one above the tops
+; of the top row of lorchas).
+@wait4scanline:
  lda VCOUNT
  cmp #(4+8)*4
- bne @b
+ bne @wait4scanline
+;           }
 
-@d:
+;           {
+; load a different random font address on every scanline.
+; CHBASE is the hardware address, not the OS shadow!
+; This isn't as random as I'd like, because ANTIC ignores the
+; bottom 9 bits for GR.0: fonts are 1K and start on a 1K boundary,
+; so the code below picks one of 32 possible "fonts".
+; The LSR below limits us to the first 32K of memory, because:
+; - setting the font address to $d4 - $d7 causes ANTIC to read from
+;   the CCNTL (cart control) area at $d5xx, which makes SpartaDOS X
+;   spontaneously bankswitch (crashing the Atari).
+; - addresses $e0 - $e3 would be the ROM font, which doesn't look
+;   like static. On an XL/XE, $cc - $cf are the international
+;   font too.
+; - reading from the I/O chips in the $d000 area doesn't seem like
+;   a safe thing to do (though it might be OK).
+; If the 'sta WSYNC' were removed, we'd be switching fonts a lot
+; more than once per scanline... but ANTIC only seems to pay attention
+; to CHBASE at the start of a GR.0 modeline, so it's wasted effort.
+
+@randfont:
  sta WSYNC
  lda RANDOM
- lsr ; avoid reading I/O registers, I think it can lock up SDX
+ lsr ; avoid reading upper 32K of address space
  sta CHBASE
  lda VCOUNT
  cmp #(4+23)*4
- bne @d
+ bne @randfont ; stop garbage 2 lines after the bottom row of lorchas
+;           }
+
+; temporarily restore ROM font pointer, so the rest of the frame will
+; display normal spaces.
  lda #$e0
  sta CHBASE
 
  lda RTCLOK+2
-@c:
+;           {
+; wait for start of next TV frame.
+; OS will restore hw CHBASE reg from CHBAS shadow.
+@wait4frame:
 cmp RTCLOK+2
- beq @c
+ beq @wait4frame
+;           }
+
  dex
- bne @b
+ bne @wait4scanline
+;       }
 
- dec iloop_count
- bne @iloop
+ dec static_loop_count
+ bne @static_loop
+;     }
 
  ldx #0         ; jsleep(10)
  lda #$0a
  jsr _jsleep
 
  dey
- bne @loop ; we're done if Y==0
+ bne @explosion_loop ; we're done if Y==0
 ;   }
 
  rts