*********************** HeliOS Copper Functions *********************** HeliOS contains simple to use commands for constructing Amiga copperlists, and these commands are used under the normal Amiga operating system. Once constructed, a copperlist can be used however you wish, whether under the Amiga operating system or under the HeliOS game operating system. In order to install a copperlist under the HeliOS game operating system there are several special commands which are not dissimilar to counterparts used by the Amiga OS. These commands are listed and explained below, and ONLY function when the HeliOS operating system is being used. ******************************** Copperlist construction commands ******************************** You do not need to specify any memory allocation: you simply tell HeliOS to start building a copper list, and it will handle memory allocation automatically. HeliOS automatically allocates some initial memory and builds your copper list sequentially according to your commands, adjusting the copper list memory allocation whenever required. When you have completed your copper list you simply tell HeliOS to finish its copper construction. HeliOS will them move your new copper list to its own correctly sized memory buffer and tidy up, passing you a pointer to your new copperlist. You should NOT start to build a second copper list before you have finished a first one, but if you do HeliOS will automatically close and de-allocate the old copper list which was in progress. Here are the commands used for building copper lists: ----------- COPPERSTART ( - - - CopperStart(l) or null ) ----------- Starts building a copper list and, if necessary, removes any partially built copper lists. This command returns a 32-bit pointer to the start of the initial copper memory allocated by HeliOS, or a 32-bit null value for failure. --------- COPPEREND ( - - - CopperStart(l), CopperLength(l) or null ) --------- Ends the building of a copper list. This command returns a 32-bit pointer to the start of the final copper memory allocated by HeliOS and the 32-bit length of the copperlist in bytes. The COPPEREND command returns a SINGLE 32-bit null value for failure. ---------- COPPERWAIT ( HWait(w), VWait(w), Ctrl(w) - - - flag(w) ) ---------- This command causes HeliOS to add a copper WAIT line to the current copper list being built. The input parameters are standard Amiga copper values, and for details on how this works refer to any text on constructing Amiga copper lists. HeliOS handles "long" screen raster positions (>255) automatically. The result "flag" indicates whether or not the operation was successful. ---------- COPPERSKIP ( HWait(w), VWait(w), Ctrl(w) - - - flag(w) ) ---------- This command causes HeliOS to add a copper SKIP line to the current copper list being built. The input parameters are standard Amiga copper values, and for details on how this works refer to any text on constructing Amiga copper lists. HeliOS handles "long" screen raster positions (>255) automatically. The result "flag" indicates whether or not the operation was successful. ---------- COPPERMOVE ( Value(w), HardwareOffset(w) - - - flag(w) ) ---------- This command causes HeliOS to add a copper MOVE line to the current copper list being built. The first input parameter is the value you want to MOVE into a hardware register. The second input parameter is the offset of the target register from $DFF000. The result "flag" indicates whether or not the operation was successful. --------- COPPERADD ( Value(w) - - - flag ) --------- A special "low-level" HeliOS copper construction command which allows you to add construct "custom" copperlist sequences however you wish. This is a "toolkit" command which causes HeliOS to add the value you have specified as the next 16-bit value in the copper list under construction. COPPERADD is a DANGEROUS command, since it is up to you to ensure the correct format and sequence of any copper commands inserted in this way! The result "flag" indicates whether or not the operation was successful. -------------------------------- Example of building a copperlist -------------------------------- D0 DVARIABLE Copper D0 DVARIABLE CopperLength : Create_Copper COPPERSTART Copper D! [ HEX ] 0 B0 FFFE COPPERWAIT DROP 0 190 COPPERMOVE DROP 0 192 COPPERMOVE DROP 0 194 COPPERMOVE DROP 0 196 COPPERMOVE DROP 0 198 COPPERMOVE DROP 0 19A COPPERMOVE DROP 0 19C COPPERMOVE DROP 0 19E COPPERMOVE DROP [ DECIMAL ] COPPEREND DFLAG IF CopperLength D! Copper D! ELSE DDROP ." Copper Failed!" THEN ; : Free_Copper Copper D@ FREEMEMORY ; ***************************************************************** Commands for custom user-copperlists under the HeliOS game system ***************************************************************** HeliOS runs a custom master copperlist which is constructed like a "ladder" with slots (or "rungs") where individual sub-copperlists may be located. HeliOS maintains an internal table which organises these sub-copperlists into order of operation. When you add a new custom sub-copperlist, or copper strip as HeliOS calls it, the basic idea is that: 1. HeliOS adds a pointer to your new user copperlist to its internal copper table. 2. HeliOS sorts the copper table into correct order, checking to see which copper lists should come first. 3. HeliOS relinks all the pointers in the master copperlist to include all the sub-copperlists in the correct order. There are three main commands for handling this process, and these are part of a number of Display functions by means of which HeliOS allows displays to be modified. All HeliOS display functions start and end with a 32-bit pointer to the current display structure on the stack. This allows you to construct fast economical sequences of commands without the necessity to repeatedly put the display pointer on the stack for each command. Remember to drop the display pointer off the stack after your last command! -------------- ADDCOPPERSTRIP ( Display(l), Copperlist(l) - - - Display(l) ) -------------- Adds your new copperlist pointer to the HeliOS copper table. -------------- REMCOPPERSTRIP ( Display(l), Copperlist(l) - - - Display(l) ) -------------- Removes specified copperlist pointer from the HeliOS copper table. This function only removes the copperlist pointer from the reference table and does not remove the copperlist itself from the display. To remove the copperlist finally from the display, you need to call the REMCOPPERSTRIP function and then call LINKSTRIPS. -------------- SORTSTRIPTABLE ( Display(l) - - - Display(l) ) -------------- Sorts all the sub-copperlists in the HeliOS copper table. ---------- LINKSTRIPS ( Display(l) - - - Display(l) ) ---------- Relinks all the sub-copperlists into the master copperlist. ----------------------------------------- Example of adding a HeliOS sub-copperlist ----------------------------------------- : AddCopper 280 WAITBEAM Display Copper D@ ADDCOPPERSTRIP SORTSTRIPTABLE LINKSTRIPS DDROP ; ************************************************************************** End **************************************************************************