*************************** HeliOS CODER motor routines *************************** ************ Introduction ************ The HeliOS CODER routines are part of the interrupt-driven game operating system and function as one of the HeliOS "motor" routines. These are fast optimised machine coded routines which can be controlled entirely by pre-defined data structures. These functions only work in HeliOS mode. HeliOS CODER functions allow fast and efficient performance of simple fast machine code or HeliOS programs which you want to run synchronously along with the other HeliOS motor operations. CODERs are designed to allow you to build your own custom motor operators. ****** Timing ****** It is an important consideration that all motor functions are fully synchronised with all other HeliOS internally automated functions and with the display frame rate. Motors are run in the order in which they are installed: you must remember this if you are using one motor function to modify another. ****************** Control structures ****************** The main CODER control structure is as follows: ----------------------- CODER control structure ----------------------- Coder_BeforeForth(w) = HeliOS CFA to run BEFORE each CODER calculation Coder_BeforeCode(l) = Machine code to run BEFORE each CODER calculation Coder_AfterForth(w) = HeliOS CFA to run AFTER each CODER calculation Coder_AfterCode(l) = Machine code to run AFTER each CODER calculation Coder_Flags(w) = Control flags word ( See below) Coder_CountDown(w) = Countdown time (If non-zero sets countdown) Coder_CDFlags(w) = Countdown flags word (-> "Flags" at CountDown time) Coder_CDForth(w) = Countdown HeliOS function CFA (optional) Coder_CDCode(l) = Countdown machine code function pointer (optional) Coder_SkipTimer(w) = CODER skip internal timer register Coder_SkipCount(w) = CODER skip count = How many "ticks" to skip (0=Do all) Coder_ID(w) = Motor handler ID = 4 for CODER Coder_Count(l) = CODER data list count Coder_Data(l) = CODER data list pointer Coder_UserDataPtr(l) = Free user data pointer Coder_UserData1(w) = Free user data1 Coder_UserData2(w) = Free user data2 Coder_UserData3(w) = Free user data3 Coder_UserData4(w) = Free user data4 Coder_UserData5(w) = Free user data5 Coder_UserData6(w) = Free user data6 Coder_UserStatus(w) = Free user status Here is an amplified description of each field: Coder_BeforeForth This field, if non-null, contains the CFA af a HeliOS command which will be run BEFORE each iteration of the CODER function. A 32-bit pointer to the CODER control structure will be placed on the stack when the HeliOS BEFORE command is called, so you must take care to clear the stack. Coder_BeforeCode This field, if non-null, contains a pointer to a machine code routine which will be run BEFORE each iteration of the CODER function. A 32-bit pointer to the CODER control structure will be placed in address register A0 when the BEFORE command code is called. Coder_AfterForth This field, if non-null, contains the CFA af a HeliOS command which will be run AFTER each iteration of the CODER function. A 32-bit pointer to the CODER control structure will be placed on the stack when the HeliOS AFTER command is called, so you must take care to clear the stack. Coder_AfterCode This field, if non-null, contains a pointer to a machine code routine which will be run AFTER each iteration of the CODER function. A 32-bit pointer to the CODER control structure will be placed in address register A0 when the AFTER command code is called. Coder_Flags This field contains the CODER function control flags. The following function control flags are available: 0 = Skip CODER function The CODER operation is skipped, but the "Before" functions are still carried out as usual. -3 = SelfRemove at once Self explanatory! Coder_CountDown Sets up a CountDown, so that after the number of "ticks" specified in this field the CDFlags value will be stored into the Flags field of the CODER command structure. This function is switched off after each CountDown. Coder_CDFlags If a CountDown is being done, the value in this field will be placed in the "Flags" field of the CODER command structure when the CountDown is complete. Coder_CDForth This field contains either null or the CFA of a HeliOS function which you wish to be executed after CountDown has completed. Coder_CDCode This field contains either null or a pointer to a machine code routine which you wish to be executed after the CountDown has completed. Coder_SkipTimer This field is used to store the internal timer status of the CODER motor. Coder_SkipCount This value gives the time delay between each iteration of the CODER function. The CODER will skip however many "ticks" are specified here between each active cycle. A SkipCount value of "0" gives full speed operation. Coder_ID This MUST be set to "4", to identify the CODER function. Coder_Count The number of data items constituting this CODER. Coder_Data A pointer to the start of the sequence of sub-CODER data structures associated with this master CODER control structure. Coder_UserDataPtr This is a "free" field which you can use as you wish. Coder_UserData1 This is a "free" field which you can use as you wish. Coder_UserData2 This is a "free" field which you can use as you wish. Coder_UserData3 This is a "free" field which you can use as you wish. Coder_UserData4 This is a "free" field which you can use as you wish. Coder_UserData5 This is a "free" field which you can use as you wish. Coder_UserData6 This is a "free" field which you can use as you wish. Coder_UserStatus This is a "free" field which you can use as you wish. ************************* **** IMPORTANT NOTES **** ************************* 1. At present CODERs do not have a specific function and make no use of the "CODER_Count" and "CODER_Data" fields: this may change in future....... This does NOT mean that CODERs do not function at present! To get a CODER to run your supplied code the use of the "Before" and "After" functions is all that is necessary to implement the running of your code. 2. If you need to use the blitter when in "HeliOS" mode you MUST use a CODER (or one of the other HeliOS motors) to implement the blitter operation. This is obligatory because the blitter is used extensively by the HeliOS interrupt routines and so it is not available to your foreground code. If you MUST use a blitter-like operation in your foreground code you should use the HeliOS CPU blitter emulation routines in the "HeliOS GraphicsLib". ********************************** HeliOS CODER control command words ********************************** There are NO words specifically to control CODER functions. All control is via the data structures detailed above. CODERs are started by using the expression: MyCODER INSTALLMOTOR CODERs are stopped by using the expression: MyCODER REMOVEMOTOR ************ Using CODERs ************ CODERs are VERY easy to use and to set up. First you need to allocate a master CODER structure: Coder_SIZEOF MAKESTRUCTURE MyCoder D! or something similar...... Then you must initialise the data structure. MyCoder D@ SETSTRUCTURE1 1 Coder_Count STRUCTURE1 !L 1 Coder_SkipCount STRUCTURE1 !L 4 Coder_ID STRUCTURE1 !L 1 Coder_Flags STRUCTURE1 !L Then you can insert a pointer to your code: FIND MyBlitterCode Coder_BeforeForth STRUCTURE1 !L Then you must use INSTALLMOTOR when you want to start the CODER process: MyCoder D@ INSTALLMOTOR ...and REMOVEMOTOR when you want to stop the CODER process: MyCoder D@ REMOVEMOTOR ********************************************************************* End *********************************************************************