******************************************* The HeliOS ScreenFlash/ColourCycle routines ******************************************* Colour cycling ONLY functions in HeliOS mode! ************ Introduction ************ Colour cycling is controlled by "SLFlash" structures which are installed into the HEliOS system and associated with a particular display slice. These "SLFlash" structures "flash" or "cycle" the colours in the slice in a programmable way to allow versatile colour cycling effects. As many Flash/ColourCycle control structures as you like can be installed into any slice: multiple flash structures are placed into a list as they are installed and operate in sequential order. These structures may be added and removed, one at a time, using the command words FLASHSLICE and FLASHSLICEOFF. An "SLFlash" structure is constructed by using the command MAKEFLASH, which in turn uses three further data structures to define various parameters of the colour cycling process. This system allows complex effects and economy of data, since each individual data table can be used simultaneously in several different flash/cycle operations. The "flash" system may be set up with "self-programming" code before and after each flash event, allowing programmable complex special effects. ******************************** Making a flash control structure ******************************** Here is an example of the layout of an SLFlash structure. SLFlash_Flags(w) SLFlash_SequenceCount(w) SLFlash_SequenceDelay(w) SLFlash_RepeatCount(w) SLFlash_RepeatDelay(w) SLFlash_ColorCount(w) SLFlash_Restore(w) SLFlash_AutoRemove(w) SLFlash_WorkCount(w) SLFlash_WorkDelay(w) SLFlash_WorkRepeat(w) SLFlash_ColorStore(l) SLFlash_ColorList(l) SLFlash_FrameList(l) SLFlash_NextFlash(l) SLFlash_PrevFlash(l) SLFlash_BeforeForth(w) SLFlash_BeforeCode(l) SLFlash_AfterForth(w) SLFlash_AfterCode(l) SLFlash_Running(w) Most of these fields are "private" and should not be touched! However, since a pointer to this structure is passed to the BEFORE and AFTER routines mentioned below, it is possible to safely change some of the parameters to reprogram the "flash" while it is running. You may change the following fields and the BEFORE and AFTER routine fields during operation if you wish to do so: SLFlash_SequenceCount(w) SLFlash_SequenceDelay(w) SLFlash_RepeatCount(w) SLFlash_RepeatDelay(w) SLFlash_ColorCount(w) SLFlash_Restore(w) SLFlash_AutoRemove(w) Do not change any of the other fields....... Let's look at how to construct "SLFlash" structures using MAKEFLASH. Here is the stack diagram for MAKEFLASH: MAKEFLASH ( FrameList(l), ColorList(l), FlashDef(l) - - - SLFlash(l) ) As you can see, the command MAKEFLASH requires three data structures: * A frame definition table * A colour definition table * A "master" control data structure We will now look at each of these in turn. ************************ Master control structure ************************ The master control structure determines the dynamic parameters of the colour cycling process. Here is the way the "master" control structure is organised: SLFlashDef SLFlashDef_SequenceCount(w) = How many colour change frames in the sequence SLFlashDef_SequenceDelay(w) = VBlanks between colour change frames SLFlashDef_RepeatCount(w) = How many full sequence repeats (-1 = FreeRun) SLFlashDef_RepeatDelay(w) = VBlanks between each sequence repeat SLFlashDef_ColorCount(w) = Number of colours being changed SLFlashDef_Restore(w) = Set=1 for original colours to be restored SLFlashDef_AutoRemove(w) = Set=1 for flash auto-removal after completion SLFlashDef_BeforeForth(w) = HeliOS code to run before each flash/cycle SLFlashDef_BeforeCode(w) = Machine code to run before each flash/cycle SLFlashDef_AfterForth(w) = HeliOS code to run after each flash/cycle SLFlashDef_AfterCode(w) = Machine code to run after each flash/cycle Here is a more detailed discussion of each field: ------------------------ SLFlashDef_SequenceCount ------------------------ This value determines how many times each colour is changed in the master sequence. The sequence can itself be repeated as many times as you wish. ------------------------ SLFlashDef_SequenceDelay ------------------------ This value determines how many VBlanks elapse between each colour change. ---------------------- SLFlashDef_RepeatCount ---------------------- This value determines how many times the master sequence is repeated. Setting this to "-1" will cause a free-running self-repeating cycle. ---------------------- SLFlashDef_RepeatDelay ---------------------- This value determines how many VBlanks elapse between each repeat of the master sequence, before the sequence starts again. --------------------- SLFlashDef_ColorCount --------------------- This value determines how many colours there are being flashed in each "frame" of the master sequence. ------------------ SLFlashDef_Restore ------------------ This value is a flag which determines whether the original slice colours are restored when the "flash" is removed. Set to "1" = restore colours. --------------------- SLFlashDef_AutoRemove --------------------- This value is a flag which determines whether the "flash" will remove itself automatically when it has completed. Set to "1" = auto-remove. ---------------------- SLFlashDef_BeforeForth ---------------------- This value is the HeliOS CFA of any function you wish to run BEFORE the "flash" is performed each time. A 32-bit pointer to the current SLFlash structure will be on the HeliOS stack when this routine is called, so take care to handle it. This allows fully programmable special "flash" effects. This field can be left null if not required. --------------------- SLFlashDef_BeforeCode --------------------- This value is a pointer to a machine code routine you wish to run BEFORE the "flash" is performed each time. A 32-bit pointer to the current SLFlash structure will be in address register A0 when this routine is called. This allows fully programmable special "flash" effects. This field can be left null if not required. --------------------- SLFlashDef_AfterForth --------------------- This value is the HeliOS CFA of any function you wish to run AFTER the "flash" is performed each time. A 32-bit pointer to the current SLFlash structure will be on the HeliOS stack when this routine is called, so take care to handle it. This allows fully programmable special "flash" effects. This field can be left null if not required. --------------------- SLFlashDef_AfterCode -------------------- This value is a pointer to a machine code routine you wish to run AFTER the "flash" is performed each time. A 32-bit pointer to the current SLFlash structure will be in address register A0 when this routine is called. This allows fully programmable special "flash" effects. This field can be left null if not required. *********************** Colour definition table *********************** The colour definition table is a simple list of 16-bit values defining which Amiga colour registers are to be affected. Here is the way the colour definition table is organised: ColourRegNumber(w) = Amiga colour register number ColourRegNumber(w) = Amiga colour register number ColourRegNumber(w) = Amiga colour register number etc. etc. Up to a total of "ColourCount" (defined in control structure) colours. ********************** Frame definition table ********************** The frame definition table is a simple list of 16-bit RGB values defining all the colours for each frame of the colour cycling process. As usual with the Amiga, colour RGB values are stored as 16-bit cells, but the colour information is only 12-bit in size. Here is the way the frame definition table is organised: ColourRGB(w) = 16-bit cell with 12-bit RGB colour info ColourRGB(w) = 16-bit cell with 12-bit RGB colour info ColourRGB(w) = 16-bit cell with 12-bit RGB colour info etc. etc. Up to a total of "ColourCount" (defined in control structure) colours. ColourRGB(w) = 16-bit cell with 12-bit RGB colour info ColourRGB(w) = 16-bit cell with 12-bit RGB colour info ColourRGB(w) = 16-bit cell with 12-bit RGB colour info etc. etc. Up to a total of "ColourCount" (defined in control structure) colours. etc. etc. Repeated up to "SequenceCount" number of frames. ********** An example ********** \ -------------------------------------------------------------------- \ Start of example \ -------------------------------------------------------------------- \ ------------------------ \ Master control structure \ ------------------------ CREATEL FlashDef 3 , \ Sequence Count = Number of cycle frames 10 , \ Sequence Delay = Ticks between each cycle frame -1 , \ Repeat Count = Forever.... 0 , \ Repeat Delay = No delay between sequence repeats 4 , \ Color Count = Number of colours cycled 1 , \ Restore = Restore original colours 0 , \ AutoRemove = Do not autoremove after cycle 0 , \ BeforeForth = No extra "before" Forth 0. D, \ BeforeCode = No extra "before" Code 0 , \ AfterForth = No extra "after" Forth 0. D, \ AfterCode = No extra "after" Code \ In this example: \ \ ColourCount = 4 \ SequenceCount = 3 \ Our colour definition table would be something like this: CREATEL ColourDef 0 , \ -> Use Amiga Colour 0 1 , \ -> Use Amiga Colour 1 5 , \ -> Use Amiga Colour 5 6 , \ -> Use Amiga Colour 6 \ Our frame definition table would be something like this: CREATEL FrameDef HEX \ Use HEX to make RGB values easy to define and read (see below) 00F0 , \ Colour 0 setting for frame 1 00F5 , \ Colour 1 setting for frame 1 00F3 , \ Colour 5 setting for frame 1 03F3 , \ Colour 6 setting for frame 1 00F0 , \ Colour 0 setting for frame 2 03F3 , \ Colour 1 setting for frame 2 00F3 , \ Colour 5 setting for frame 2 00F5 , \ Colour 6 setting for frame 2 00F0 , \ Colour 0 setting for frame 3 03F3 , \ Colour 1 setting for frame 3 06F3 , \ Colour 5 setting for frame 3 00F5 , \ Colour 6 setting for frame 3 \ ^^^ \ ||| \ ||Blue value column \ || \ |Green value column \ | \ Red value column DECIMAL FrameDef ColorDef FlashDef MAKEFLASH DVARIABLE NewFlash SliceControl1 NewFlash D@ FLASHSLICE \ -------------------------------------------------------------------- \ End of example \ -------------------------------------------------------------------- There are a three very simple commands words which are used to set up and close down the colour cycling system. MAKEFLASH ( FrameList(l), ColorList(l), FlashDef(l) - - - SLFlash(l) ) This routine makes an SLFlash structure for you. The SLFlash structure should be deallocated when you are finished with it, using the HeliOS command FREEMEMORY. This routine returns null in case of (unlikely!) failure. FLASHSLICE ( SliceControl(l), SLFlash(l) - - - ) This routine installs the "flash" into a slice controller. FLASHSLICEOFF ( SLFlash(l) - - - ) This routine removes the "flash" from a slice controller. **************************************************************************