Starflight in the Forth Dimension

By Jörg Langowski, MacTutor Editorial Board, Grenoble, France

Starflight Demo in Forth

We’ll have another contribution from our active reader in Finland this month. Juri Munkki has worked out some graphics animation routines in Mach 2 which will work with either the alternate screen buffer (fast, but not supported on the Mac II) or with a separately defined off-screen buffer (slower, but Mac II - compatible). The program example is Mike Morton’s Starflight demo, rewritten in Forth. In the course of this article, we will not only learn something about animation in Forth, but also of things to consider in a turnkey application when the alternate screen buffer is used.

Finally, I’ll briefly inform you about the latest release of Mach2 (v2.11). But let’s first look at the graphics animation demo and the comment that I received from Juri with it.

The Many Faces of the Alternate Screen

Animation is the basis of all arcade games. A microcomputer fast enough to satisfy the needs of every games programmer has yet to be designed. An alternate graphics buffer is very useful in eliminating flicker. The program can draw on a buffer while the user is watching the other buffer. When the frame is ready, it is displayed and the previously visible buffer is hidden.

Double buffering is available on the Mac 128K, 512K and Plus, but it is not available on the Mac II and probably will be missing or different in future Macintosh models. Because of this, the programmer must choose between fast animation and future compatibility. This choice has usually been made at the time the program is written, but doesn’t have to be that way.

In this article I will present a basis of a double-buffering animation system. I have written two interchangeable programs that eliminate flicker from animation. The first program can not be used on machines that don’t have the alternate screen, but it is much faster than the other one. The second program should work on all computers.

The second program allocates 22K of RAM and draws only to this place. It then copies the result to the screen with CopyBits. It takes more time because we have to make the copy instead of flipping one bit in the VIA.

There are three main routines: InitAnim, StartDraw and ShowB. In addition to these the program may access a handle to the drawing buffer. An animation program starts by calling InitAnim, which may relaunch if the alternate buffer is not available. StartDraw is called before drawing an animation frame. It clears the buffer to black and makes Grabu the “handle” to the buffer. You may draw directly in the buffer with his own routines or you can use QuickDraw. When the frame is finished, a call to ShowB will either copy it onto the screen or it will switch display buffers.

Freeing the Alternate Buffer for Animation

Gaining access to the alternate buffer has never been easy. With the old ROMs the program had to launch itself to move the stack below the screen memory. New ROMs place the cache RAM on the alternate screen buffer. [Get the idea that Apple is discouraging our use of this feature? -Ed]

Most animation programs don’t work with the cache on because they write directly on the cache memory. The segment loader isn’t smart enough to move or clear the cache when it is asked to launch a program with the alternate screen option set. (See fig. 1)

Fortunately it was very easy to guess where the cache settings were located. Since they are saved even when the computer is turned off, they had to be in the parameter RAM. The parameter RAM is located in the clock chip and it can hold 20 bytes. I examined the parameter RAM with different cache settings and the results can be found in figure 1. Since the old ROMs used only 18 bytes, the cache settings are saved in the two remaining bytes. (Note that all of this discussion assumes a Mac Plus configuration. If the Mac SE and the Mac II are different, I have not fully covered or mentioned those differences)

The cache is never changes while an application is running. The segment loader changes the size of the cache when a new application is launched. It looks at the RAM copy of the parameters to determine if the cache needs to be changed. We can keep the original cache settings in the clock chip while relaunching and restore the original settings by calling _Initutil. (See fig. 2)

Of course, there is a catch. The new ROMs contain an interesting feature. (feature: a bug as described by the marketing department, ref: APPLE ][ reference manual) If the segment loader has to remove the cache, it forgets to allocate the alternate buffer. If the program now looks at CurPageOption, it will see the value it gave when launching and happily overwrite its own stack.

The program has to launch itself twice if the cache is on (Fig. 2). The first time it turns the cache off and tries to launch with the alternate screen in case apple changes the ROMs again. The second time around it probably detects that the stack is in the wrong place and relaunches. This time the segment loader doesn’t have to change the cache, so it gives some thought to the alternate screen. The third time around, there should be no need to relaunch and the program continues.

Jörg’s Commentary

As Juri’s examples contains a lot of new interesting definitions that can be useful in other contexts, I’ll add some explanatory remarks. First, you won’t be able to run the alternate screen buffer version of the demo if you have things installed in high memory that would be overwritten. TMON is an example of a resident program that won’t work with programs using the alternate screen, except if you install it in the system heap. Second, testing the first version from Mach2 (not having TURNKEYed the program) will most probably throw you back into Mach2 again if a condition arises that causes the program to relaunch itself. Then you should reload the demo and start again. The second version with an off screen buffer defined independently of the alternate screen will have none of these problems as long as enough buffer memory (22K here) is available.

We have already seen (in the last column) the new version of ANEW that will work with Mach2.1 (and Mach2.11 as well). You find other words, like RECT etc., known from MacForth but absent in Mach2. 4ASCII is very useful to create 32-bit ASCII names - for resource names, etc.

ZPSET (in the last part of the demo) is a routine that clears (i.e. sets to white) a point in a graphics buffer (which might be the screen itself) given its X- and Y- coordinates. It requires the previous definition of a handle GRABU to this graphics buffer. In the code for ZPSET, you should carefully look at the way the X-coordinate is converted to a row and bit address. The row column number is just X/8, and the remainder of X/8 is inverted to get the bit address within the row byte. This is because, counting X from left to right, a higher X actually corresponds to a lower bit within one byte. ZPSET furthermore assumes that each line is 512 points (64 bytes) long, which makes calculation of the offset from the Y-coordinate easy, simply shift by 6 bits. I+ and W/ come in handy to speed up integer arithmetic.

The alternate screen version of the demo (code between the definitions DOUBLEBUFFERING and Updatescreen) is hardware-dependent only in the sense that it requires an alternate screen which can be switched on and off by setting a bit in the VIA, that this screen starts 32K below the normal screen and is 512 by 342 pixels big. Absolute addresses are taken from the corresponding global memory locations, offset from A5 for the screen and in low memory for the VIA.

The word OTHERPAGE will flip from one screen to the other, returning 0 or 1 depending which screen is used. This is done by directly addressing the VIA chip. GOFORTH is used to start the program; if the alternate screen memory is not available, it will relaunch until it is.

The words contained in this part of the program are redefined in Listing 2 for working with Mac video setups that do not have the alternate screen. To use it, simply insert the code at the position indicated in the listing. Although this version is slower than the first one, it is the only one that would work on a MacII. I’m being cautious here, since I do not yet have a MacII to play around with, but I don’t see why it shouldn’t work; except for the different screen dimensions, which are still assumed to be 512 by 342. For the MacII, of larger screens, this would have to be changed accordingly.

In the second version, a separate graphics buffer is defined for drawing, which is dumped to the screen using CopyBits each time the screen is updated. If the screen dimensions are always 512 by 342, you can use BlockMove instead of CopyBits, which is slightly faster. The ClearBuf routine still assumes the Mac512/+/SE screen dimensions and would also have to be changed for other screen sizes.

Juri also sent me a very interesting example of line drawing animation making use of the same concepts as outlined above. I’m not including that here because of space limitations; we might, however, see it in a later column.

Latest Mach2 update - v2.11

Mach2 finally has an editor. Single-window yet, and no command line capability, but works well. To keep two files open at the same time, you still have MockWrite. The new Mach2 release has - of course - some bugs corrected, most important for me is that the debugger now works flawlessly, and integrates itself very nicely with other debugging environments such as TMON. There is a DEBG resource (one long word), which when zero, doesn’t activate the debugger when Mach2 is launched, when non-zero, activates it, but when it is =2, pressing the interrupt button will transfer you to TMON or whatever debugger you have installed instead of the Mach2 debugger.

The assembler has been changed to include 68881 codes (no 68020 code yet, this has to be simulated by DC.W XXXX instructions), and some bugs have been removed.

The SANE interface has been extended and now includes all functions defined for the SANE packages. Integer arithmetic on the 68020 is speeded up by a package of 68020 definitions for the basic integer operations which may be substituted for the normal definitions.

The source code for the I/O task (which is the equvalent of the main event loop in Mach2) is included in full, may be modified and the modified version integrated into the Mach2 application. This allows you to even further customize the behavior of standard Mach2 objects (windows, controls etc.); especially important if you want to have exact control over the points where task switching can occur.

MPW may now be used as a ‘scripting’ environment to create large Mach2 applications. Which means, of course, that one may maintain the code with Make and the likes. [Does this mean we’ll soon have an MPW-compatible Mach2 and I can call my Forth words from Pascal or vice versa?? Shouldn’t be too difficult...]

The update also included System 4.1 and Finder 5.5, which was good for me since they hadn’t been officially available at that time for us Frenchies.

Un petit mot pour les Français

As you may or may not have heard, MacTutor will be present at this year’s AppleExpo in Paris at the beginning of October. Serge Rostan - from Infotique - is organizing a get-together of Macintosh developers and people from MacTutor on this occasion. If you are thinking of going to the conference and joining that meeting, you should contact him (see Infotique’s advertisement in this issue for a phone #). We are all looking forward to some exciting discussion! [Discussion, heck! Laura is looking forward to the romance of Paris. I wanted to bring our bicycles, but she objected! -Ed]

Listing 1: Starflight demo, alternate screen version
( © Juri Munkki for MacTutor )

( Notice: this program was edited for publication which might have introduced 
minor errors. 
If you have the Ram cache set, the alternate screen version will ONLY 
work as a turnkey application. Clear the cache BEFORE starting Mach2 
for testing this version from within Mach2. Also make sure you have not 
installed TMON or other nasty things in high memory. 
--  JL --


ONLY FORTH DEFINITIONS 
ALSO MAC ALSO ASSEMBLER
( Anew:  Used in the form: ANEW PROGRAM_NAME. 
  It tries to find the PROGRAM_NAME and forget it if it is found. 
  It then creates PROGRAM_NAME and continues. It should be
  used in the beginning of the program. Old versions are then
  automatically forgotten, if they exist. )
: ANEW { | LEN }
  32 WORD DUP C@ 1+ NEGATE -> LEN
  FIND SWAP DROP
   IF .s LEN >IN +! 
      [‘] DUMP ( dump is defined just before FORGET )
      2+ @ 6 + EXECUTE CALL DRAWMENUBAR THEN
 LEN >IN +!
CREATE DOES> DROP
;
( Heapvar:
  Used in the form: HEAPVAR VARIABLE_NAME. 
  If VARIABLE_NAME exists, it returns the handle from 
  VARIABLE_NAME to the heap. It should be used
  before ANEW to free space from the heap. )
: HEAPVAR
  32 WORD
  FIND IF LINK>BODY EXECUTE 
     @ DUP 
     IF DUP CALL HUNLOCK DROP
            CALL DISPOSHANDLE DROP ELSE DROP THEN
     ELSE DROP
   THEN
;

: RECT
 CREATE
 SWAP 2SWAP SWAP
 W, W, W, W,
;

GLOBAL
 CODE !RECT
    MOVE.L    (A6)+,A0
    MOVE.W    14(A6),(A0)+
    MOVE.W    10(A6),(A0)+
    MOVE.W     6(A6),(A0)+
    MOVE.W     2(A6),(A0)+
    ADDA.L    #16,A6
    RTS
END-CODE

GLOBAL
 CODE OFF
    MOVEA.L   (A6)+,A0
    CLR.L    (A0)
    RTS
END-CODE
MACH

GLOBAL
 CODE ON
    MOVEA.L   (A6)+,A0
    MOVE.L    #-1,(A0)
    RTS
END-CODE

GLOBAL
 CODE SCALE
    MOVE.L   (A6)+,D0
    BMI.S    @1
    MOVE.L   (A6),D1
    ASL.L    D0,D1
    MOVE.L   D1,(A6)
    RTS
@1  MOVE.L   (A6),D1
    NEG.L    D0
    ASR.L    D0,D1
    MOVE.L   D1,(A6)
    RTS
END-CODE

GLOBAL
 CODE @MOUSE
    SUBQ.L    #4,A6
    MOVE.L    A6,-(A7)
    _GETMOUSE
    RTS
END-CODE

( 4ASCII nnnn 
converts the 4 character string into its numeric value.  It can only 
be used in the immediate mode. Examples below )
: 4ASCII 
 0
4 0 DO
  8 SCALE 0 WORD 1+ C@ + 
LOOP
;

( *** The part that has to be exchanged with Listing 2 on machines without 
the alternate screen memory starts here *** )

ANEW DOUBLEBUFFERING 

( Low RAM location of system parameters )
    504 CONSTANT SYSPARAM

( Segment loader global containing last page request )
HEX 936 CONSTANT CURPAGEOPTION
    910 CONSTANT CURAPNAME
( VIA base address from apple’s equate files  )
   1D4 CONSTANT VIA
( offset to buffer A. The screen bit is there )
  1E00 CONSTANT VIABUFA
( Bit 6=$40 is the video bit )
    40 CONSTANT VIDEO2

EQU VIAq     $01D4

( offset to buffer B. The sound bit is there.
  We don’t use it yet...later we might write
  a simple sound driver using this location   )
     0 CONSTANT VIABUFB
     7 CONSTANT SOUNDBITS ( Volume            )
     3 CONSTANT SOUNDPAGE ( Bit 3=Sound page  )
EQU VIABUFBq $0000
DECIMAL

( Pointer to upper left of screen )
        VARIABLE SCREENMEM
( Pointer to upper left of graphics buffer )
        VARIABLE GRABPTR
( “Handle” to the graphics buffer )
        VARIABLE GRABU

( I had some problems using the Forth definition of
  _Launch in my programs. This works... )
CODE LAUNCHIT
    MOVE.L (A6),A0 ( Parameterptr is in the stack )
    _LAUNCH        ( Launch with parameters at A0 )
    RTS            ( We should never arrive here! )
END-CODE

GLOBAL ( It is always useful to know A5, so I made
         this definition global. We use it to find
         where the screen is located. A5 points to
         your variables, but it can also be used to
         find quickdraw’s globals. )
CODE GETA5
    MOVE.L   A5,-(A6)
    RTS
END-CODE
MACH

( We examine the stack pointer to see if it is
  located on the alternate buffer. )
CODE GETA7
    MOVE.L   A7,-(A6)
    RTS
END-CODE
MACH

( This code does not work on “Mac” with non-standard
  screen resolution. Using the second buffer is not
  portable anyway. We clear the screen to black. )
CODE ClearBuf ( ADDR )
    MOVE.L   (A6)+,A0
    MOVEQ.L  #-1,D0   ( Black=-1, White=0 )
    MOVE.W   #341,D1  ( 342 rows)
@1  MOVE.L   D0,(A0)+ ( 16*4 bytes*8 bits )
    MOVE.L   D0,(A0)+ (        =512 pixels)
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    DBRA     D1,@1
    RTS
END-CODE

( Change the video screen bit and report
  the currently visible video page. 
  0= Alternate
  1= Primary   )
GLOBAL
CODE OTHERPAGE ( - ThePage )
    MOVEA.L VIAq,A0
    LEA     $1E00(A0),A0 ( Buffer A )
    MOVEQ.L #1,D0
    BCHG    #6,(A0)      ( Bit 6=Page)
    BEQ.S   @1
    MOVEQ.L #0,D0
@1  MOVE.L  D0,-(A6)
    RTS
END-CODE

( Show the other buffer.
  This word always ends drawing. )
GLOBAL
: SHOWB        OTHERPAGE DROP ;

( Stardraw stores the address of the
  current buffer in GRABPTR. SCREENMEM
  always points to the normal screen.
  It then clears the invisible buffer.

  Call startdraw when you begin drawing
  on the screen. )
GLOBAL
: STARTDRAW
 VIA @ VIABUFA + C@ VIDEO2 AND 
 IF -32768 ELSE 0 THEN
 SCREENMEM @ + DUP GRABPTR ! CLEARBUF
;

GLOBAL
: GOFORTH
( If we have the options we want )
CURPAGEOPTION W@ IF
( See if we really have the other buffer.
  The stack may still be there. )

 GETA7
 GETA5 @ 122 - @ 32768 - >
         ( False=stack is not in the way )

 ELSE -1 ( We don’t have the option we want )
 THEN

 IF ( Set the cache off, but do not copy
      the result into parameter RAM. )
  SYSPARAM 18 + W@ -33 AND SYSPARAM 18 + W!
                ( Pad contains the parameters    )
  -1 PAD 4 + !  ( -1 is alternate screen & sound )
  CURAPNAME PAD !
  PAD LAUNCHIT  ( never goes beyond this point...)
 THEN
 ( We finally have the options we wanted. Restore
   the cache setting from the clock chip RAM. )
  CALL INITUTIL DROP
;


( INITBUF gets the correct page option then
  finds the location of the primary screen
  by looking at ScreenBits. The address
  is found at -122(A5). It then stores a
  pointer to grabptr in grabu. GRABU is
  used in my drawing routines. )
GLOBAL
: InitBuf
      GOFORTH ( Get the alternate page )
         GETA5 @ 122 - @ SCREENMEM !
         GRABPTR GRABU !
         STARTDRAW
;

( UpdateScreen should be called whenever you want
  to show the results on the screen. Usually SHOWB
  would swap screens if you used 2 buffers. In the
  the other version, it does a ShowB.
  Here, it is does nothing )
GLOBAL
: UpdateScreen ;
MACH
( *** end of alternate screen-dependent part *** )

ANEW STARFLIGHT
ONLY FORTH DEFINITIONS ALSO MAC ALSO ASSEMBLER ALSO FORTH

GLOBAL
CODE ZPSET ( X Y )
    MOVE.L  (A6)+,D1  \ Y
    MOVE.L  (A6)+,D0  \ X

    MOVEA.L GRABU,A0
    MOVEA.L (A0),A0   \ Grabu is a handle!

    ASL.W   #6,D1     \ Row=64*Y -> 64 BYTES/ROW

    MOVE.W  D0,D2     \ column=X/8 
    LSR.W   #3,D2

    AND.B   #7,D0     \ Bit=NOT(x and 7)
    NOT.B   D0

    ADD.W   D2,D1     \ addr=base+row+column
    BCLR    D0,(A0,D1.W)
    RTS
END-CODE

Global
CODE I+
    ADD.L   D6,(A6)
    RTS
END-CODE
MACH

Global
CODE W/
    MOVE.L  (A6)+,D0
    MOVE.L  (A6),D1
    DIVS.W  D0,D1
    EXT.L   D1
    MOVE.L  D1,(A6)
    RTS
END-CODE

\ Originally written by Mike Morton for Mactutor
\ Translated to Mach 2 by Juri Munkki

\ constants
 140 constant NumStars
 256 constant MaxX
 172 constant MaxY
   8 constant MaxZ   ( really is 2^8 )
 256 constant Xcen
 172 constant Ycen
0 0
342 512 rect MyBits
\ variables
variable zr Numstars 2* 4 - vallot
variable xr Numstars 2* 4 - vallot
variable yr Numstars 2* 4 - vallot
variable speed

: MakeStar  {  star  -- really 2 * index }
 
 CALL Random MaxX Mod xr star + W!
 CALL Random MaxY Mod yr star + W!

 1 MaxZ scale zr star + W!
;
: MoveStars
 NumStars 2* 0 do
 zr i + w@ L_Ext 0> if
  xr i+ w@ L_Ext MaxZ scale zr i+ w@ w/ Xcen +
  yr i+ w@ L_Ext MaxZ scale zr i+ w@ w/ Ycen +
   2dup pad w! pad 2+ w!
   pad @ myBits call ptinrect
      if ZPSET zr i+ w@ Speed @ - zr i+ w!
    else 2drop i MakeStar then
  else i MakeStar then
 2 +loop
;
: Initialize
 NumStars 2* 0 do
  i MakeStar
 2 +loop
;
: DoStars
call hidecursor
 Initialize
begin
 StartDraw
 @MOUSE -20 SCALE 0 MAX SPEED !
 MoveStars
 ShowB
  call button if 
   call tickcount
    begin 
     @MOUSE -20 SCALE 0 MAX SPEED !
     MoveStars UpdateScreen
     call button 0= until
   call tickcount swap - 5 < else 0 then
 until

begin otherpage until
call showcursor
;
: GoStars
 InitBuf
 DoStars
 Bye
;

Listing 2: Changes necessary for alternate screen version

HEAPVAR GraBu
ANEW GRAPHICS_BUFFER

ONLY FORTH DEFINITIONS DECIMAL
ALSO MAC ALSO ASSEMBLER ALSO FORTH
VARIABLE GraBu 0 GRABU !
VARIABLE SCREENMEM
GLOBAL
CODE GETA5
    MOVE.L   A5,-(A6)
    RTS
END-CODE
MACH

CODE ClearBuf ( ADDR )
    MOVE.L   (A6)+,A0
    MOVEQ.L  #-1,D0
    MOVE.W   #341,D1
@1  MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+

    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    MOVE.L   D0,(A0)+
    DBRA     D1,@1
    RTS
END-CODE

GLOBAL
        VARIABLE FULLSCREENPORT
        VARIABLE DRAWINGPORT
0 0 342 512 RECT FULLSCREENRECT
( We initialize the graphics buffer to
  hold 512*342, although we do not know
  that the screen is just that size. )
: InitBuf
         512 342 8 */ CALL NEWHANDLE DROP GraBu !
         GRABU @ CALL HLOCK DROP
         GETA5 @ 122 - @ SCREENMEM !
( Open a port for ShowB
  This is not necessary when you use version 1
  of showb. )
         112 CALL NEWPTR DROP FULLSCREENPORT !
         112 CALL NEWPTR DROP DRAWINGPORT !
         FULLSCREENPORT @ CALL OPENPORT
         DRAWINGPORT    @ CALL OPENPORT
           GRABU @ @ PAD !
                  64 PAD 4 + W!
         0 0 342 512 PAD 6 + !RECT
         PAD CALL SETPBITS
;
GLOBAL

: STARTDRAW
 GRABU @ @ CLEARBUF
;

GLOBAL
( This is definiton 1 of showb. It is not compatible
  with nonstandard screen resolutions. You can use
  this version while debugging programs on a Mac.
: SHOWB
 GRABU @ @ 21888 SCREENMEM @ CALL BLOCKMOVE DROP 
; )
( This is definition 2 of showb. It uses CopyBits and
  is thus works with any computer that has Quickdraw.)
: SHOWB
 DRAWINGPORT @ 2+ FULLSCREENPORT @ 2+ ( BitMaps )
 DRAWINGPORT @ 8 + DUP ( Rects=512*342 )
 0 ( SrcCopy ) 0 ( No region ) CALL COPYBITS
;
( Since we only display the normal graphics page,
  otherpage should always return 1 )
GLOBAL
1 CONSTANT OTHERPAGE

( UpdateScreen is called when you want to show
  the results on the screen. Usually SHOWB would
  swap screens if you used 2 buffers. In the
  2 buffer version, updatescreen does absolutely
  nothing. Here, it does a SHOWB. )
GLOBAL
: UPDATESCREEN
 SHOWB
;