[stella] Macros to manage memory allocation.

[Albert Yarusso]

I am posting this for Andrew Davie, who is having problems posting to  
the list:

==

Here is some sample code from an unreleased side-scrolling game  
engine I wrote a few years back.  No implementation-specific stuff  
here, just examples of how to do RAM overlays…

     ;------------------------------------------------------------------ 
--------

     MAC OVERLAY ; {name}
     SEG.U OVERLAY_{1}
     org Overlay
     ENDM

     MAC VALIDATE_OVERLAY
         #if * - Overlay > OVERLAY_SIZE
             ERR
         #endif
     ENDM

     ;------------------------------------------------------------------ 
--------

                 SEG.U variables
                 ORG $80

; variables here..
Surround            ds 5
; /snip/snip etc.


;----------------------------------------------------------------------- 
-------

OVERLAY_SIZE    SET 16

         ; This overlay variable is used for the overlay variables.   
That's OK.
         ; However, it is positioned at the END of the variables so,  
if on the off chance we're overlapping
         ; stack space and variable, it is LIKELY that that won't be  
a problem, as the temp variables
         ; (especially the latter ones) are only used in rare occasions.

         ; FOR SAFETY, DO NOT USE THIS AREA DIRECTLY (ie: NEVER  
reference 'Overlay' in the code)
         ; ADD AN OVERLAY FOR EACH ROUTINE'S USE, SO CLASHES CAN BE  
EASILY CHECKED

Overlay         ds OVERLAY_SIZE       ;--> overlay (share) variables
                 VALIDATE_OVERLAY


                 ds RESERVED_FOR_STACK

     ECHO "FREE BYTES IN ZERO PAGE = ", $FF - *
     IF * > $FF
               ERR
     ENDIF

;----------------------------------------------------------------------- 
-------
; OVERLAYS!
; These variables are overlays, and should be managed with care
; That is, variables are ALREADY DEFINED, and we're reusing RAM for  
other purposes

; EACH OF THESE ARE VARIABLES (TEMPORARY) USED BY ONE ROUTINE (AND  
IT'S SUBROUTINES)
; THAT IS, LOCAL VARIABLES.  USE 'EM FREELY, THEY COST NOTHING

; TOTAL SPACE USED BY ANY OVERLAY GROUP SHOULD BE <= SIZE OF 'Overlay'

;----------------------------------------------------------------------- 
-------

                 OVERLAY BuildDrawFlags

BDF_DrawFlagAddress ds 2                ; destination address of draw  
flag (mirrors ScreenBuffer)
BDF_BoardAddress    ds 2                ; source address from Board
BDF_BoardBank       ds 1                ; holds bank of current line
DHS_Y               ds 1
DHS_X               ds 1
DHS_Offset          ds 1
DHS_Line            ds 1
     ;ECHO "FREE BYTES IN OVERLAY_BuildDrawFlags = ", OVERLAY_SIZE -  
( * - Overlay )
                 VALIDATE_OVERLAY

;----------------------------------------------------------------------- 
-------

                 OVERLAY Process

BoulderLeft         ds 2
BoulderRight        ds 2

                 VALIDATE_OVERLAY

;----------------------------------------------------------------------- 
-------

                 OVERLAY TimeSlice

TS_Vector           ds 2                ; vector to correct  
processing code
     ;ECHO "FREE BYTES IN OVERLAY_TimeSlice = ", OVERLAY_SIZE - ( * -  
Overlay )
                 VALIDATE_OVERLAY

;----------------------------------------------------------------------- 
-------


And etc… I think the idea is self-explanatory.  I hope!
Each OVERLAY group of variables share a common starting address, and  
overlap the others.

Cheers
A