********************************************************************** * * * ********************* * * HeliOS Game Functions * * ********************* * * * * * * This section of the dictionary is ordered loosely by grouping * * related functions. * * * * * * Most of the HeliOS game functions are individually discussed * * within the documentation files relating to each part of the game * * system, and are merely summarised here for reference purposes. * * * * * ********************************************************************** ----------------------------------------------------------------------- Resetting the HeliOS game system interrupt routines. ----------------------------------------------------------------------- SETHELIOSINTS ( - - - ) Resets the standard HeliOS game system interrupts after use of SETINT. See also SETINT SETINT ( l1 n1 - - - ) Where l1 = Pointer to your machine code interrupt routine n1 = Interrupt level to be installed (1-7) This routine can be used to set up any of the HeliOS game system interrupts so that when the HeliOS operating system takes over from AmigaDOS the installed interrupt will become operational. The new interrupt must conform to the usual requirements of Amiga interrupt code. The new interrupt will only operate when you start the HeliOS game system, and will not affect the ability of HeliOS to restart the Amiga OS legally. If you are going to change any of the HeliOS interrupts in this way you might wish to change all of them, as you may otherwise produce unpredictable results. However, if you do wish to leave any of the HeliOS interrupt handlers running, here is what they do: Level1 = HeliOS game system master control Level2 = HeliOS keyboard handler Level3 = HeliOS game system master control Level4 = Free Level5 = Free Level6 = HeliOS system timing Level7 = Free You might wish to use this facility if you want to make use of the ability of the HeliOS system to close down the OS and then run your own special game code. You can reset the standard HeliOS game system interrupts using the command SETHELIOSINTS. See also SETHELIOSINTS. ----------------------------------------------------------------------- Text and number rendering using the HeliOS bitmapped font system. ----------------------------------------------------------------------- The HeliOS language has its own built-in bitmapped font text rendering system which provides the following special advantages: 1. Easy design of fonts. 2. Multi-coloured font options. 3. Use in both the Amiga and HeliOS game operating systems. 4. Stencilled font rendering allowing multi-coloured texture mapping. 5. Uses only the CPU, with no blitter access whatever. 6. Very simple to use routines for configuration and text output into either BitMaps or RastPorts. Although it was originally designed for use in games, the HeliOS bitmap font text system may actually be used both under the Amiga operating system and the HeliOS game operating system. This HeliOS text system does not employ the blitter for its rendering operations, and this makes it ideal for use with the HeliOS game system in circumstances where it is not possible to access the blitter: for example while the blitter is being used by the game sprite rendering engine. Because, for easy use with the HeliOS game system, the HeliOS text system intentionally uses only the CPU for all its operations, it can suffer from relatively slow rendering speed in certain circumstances if not used judiciously. You may wish to experiment with various methods of text display to discover what works best in particular circumstances. The HeliOS system can render text using bitmapped font imagery supplied as a simple bitmap picture of all the font characters. Remember, a HeliOS font is simply a picture, nothing more, and can be created, edited, saved and loaded as a normal IFF picture file. The font imagery is loaded into memory as a simple bitmapped graphic using any of the standard HeliOS functions for loading graphics. The SETHELIOSFONT function is then used to set up the HeliOS bitmap font text system to use the loaded bitmapped graphical font. The parameters of the new font are defined by a HeliOS "Font Definition" data structure. ------------------------------------------------------------------- Here are commands used to set up and render text using HeliOS fonts: HELIOSBMTEXT ( BitMap(l), TextString(l), TextLength(w), XPos(w), YPos(w), BPen(w), FPen(w) - - - ) Renders the specified number of characters from a 32-bit addressed uncounted text string into the target BitMap. The top left corner of the display field is specified by "XPos" and "YPos", and the background and foreground colours are specified by "BPen" and "FPen". The font used will be the current HeliOS system bitmap font. Note that the pen colours will only be used when rendering monochrome (not multi-coloured) HeliOS fonts. HELIOSRPTEXT ( RastPort(l), TextString(l), TextLength(w) - - - ) This function renders text into the destination RastPort supplied using the current HeliOS system bitmapped font. The text is rendered (exactly like ordinary "Graphics Library" text) at the current drawing position specified within the RastPort. This can be set by the usual GFXMOVE command or (less wisely) by direct modification of the RastPort parameters. If the font used is a monochrome font the colour information for the background and foreground pens is also derived from the target RastPort parameters as with "Graphics Library" text. LEFTNUM ( BitMap(l), Number(l), FieldLength(w), XPos(w), YPos(w), BPen(w) FPen(w) - - - ) Renders a 32-bit signed "Number" into the target "BitMap" in a left justified numeric display field "FieldLength" characters wide. The top left corner of the display field is specified by "XPos" and "YPos", and the background and foreground colours are specified by "BPen" and "FPen". Note that the pen colours will only be used when rendering monochrome (not multi-coloured) HeliOS fonts. The font used will be the current HeliOS system bitmap font. The "blank" characters in the numeric field will be rendered as the ASCII characters specified in the string NUMFILL. If the system default NUMFILL is used, all blank characters will be rendered as "0". See also RIGHTNUM and NUMFILL RIGHTNUM ( BitMap(l), Number(l), FieldLength(w), XPos(w), YPos(w), BPen(w) FPen(w) - - - ) Renders a 32-bit signed "Number" into the target "BitMap" in a right justified numeric display field "FieldLength" characters wide. The top left corner of the display field is specified by "XPos" and "YPos", and the background and foreground colours are specified by "BPen" and "FPen". Note that the pen colours will only be used when rendering monochrome (not multi-coloured) HeliOS fonts. The font used will be the current HeliOS system bitmap font. The "blank" characters in the numeric field will be rendered as the ASCII characters specified in the string NUMFILL. If the system default NUMFILL is used, all blank characters will be rendered as "0". See also LEFTNUM and NUMFILL NUMFILL ( - - - l1 ) Returns a 32-bit pointer to an address which itself contains a 32-bit pointer to a string 16 characters in length which will be used as the numeric field fill character by the HeliOS operating system's justified number routines. Use NUMFILL like this: CREATEL MyNumFillChars <$ 0000000000000000$ MyNumFillChars NUMFILL D!L The system default NUMFILL uses the ASCII "0" character as above, so if this is your requirement you do not need to reset NUMFILL. See also LEFTNUM and RIGHTNUM SETHELIOSFONT ( FontDefinition(l) - - - ) Where FontDefinition(l) = Pointer to a HeliOS font definition structure. A null parameter restores the default HeliOS 8x8 pixel monochrome font. (See below for a description of the "Font Definition" data structure.) The HeliOS system can render text using bitmapped font imagery supplied as a simple bitmap picture of all the font characters. The SETHELIOSFONT function sets up this HeliOS bitmap font text system to use a font defined by the HeliOS "Font Definition" data structure. Note that if the input parameter is zero the standard HeliOS system default 8x8 pixel font will be re-installed, and that this default font is always resident within the HeliOS system. The HeliOS font system always has the default font preset at startup time, but this is not automatically reset at the end of a program. HeliOS fonts are standard bitmapped graphics which can be created in any art package and saved/loaded as simple IFF pictures: this allows really easy design of new text font effects. A HeliOS font can be either: 1. Monochrome This is a monochrome bitmap which can be rendered in various pen colours exactly like a normal Amiga font. The pen colours for rendering monochrome fonts are derived from: a. The target rendering RastPort. In this case they may be set using GFXSETAPEN and GFXSETBPEN or by writing directly into the RastPort structure. or b. Parameters specified in the special HeliOS text functions which use HeliOS fonts. 2. Multi-coloured This is created as a multi-coloured bitmap image having as many colours as your design requires. Note that, as might be expected, only as many bitplanes as the target display possesses will actually be used when the font is finally rendered. Notes on the HeliOS "Font Definition" data structure: Firstly, here is the layout of the HeliOS font definition structure. Imagery BitMap pointer -> 4 bytes Mask BitMap pointer -> 4 bytes Character cell width -> 2 bytes Character cell height -> 2 bytes Characters per row -> 2 bytes Flags -> 2 bytes Total size = 16 bytes. An example of this in HeliOS code might be as follows. CREATEL MyFontDefinition MyFontBMap D, MyFontMaskBMap D, MyFontCharWidth , MyFontCharHeight , MyFontCharsPerRow , MyFontFlags , This data structure specifies all required information about the bitmapped font imagery being installed into the HeliOS system. Firstly it specifies the imagery BitMap and a mask BitMap. The imagery BitMap must always be supplied, but the mask parameter may be left as null if required. If supplied, the Mask BitMap must define a single bitplane monochrome image, the defined pixels of which will be used as a mask to specify visible pixels of the main font imagery bitmap. Important: It is a requirement that the font mask BitMap must have identical pixel dimensions to the font imagery BitMap. Note that there is a convenient HeliOS function called GETMASK which will automatically generate a mask bitmap from any supplied bitmap, so you can easily generate the mask for any font from the font bitmap itself. The use of a mask allows stencil operations to be employed. For example, the imagery bitmap may be actual character imagery or may be just a solid area of colour pattern information, in which case the Mask supplied may be used as a stencil to "cut out" characters from the solid background. A standard monochrome font bitmap image may be used as a mask to generate a multi-coloured font from a solid "coloured plane area" image bitmap. Remember that it is vital when using texture mapping and masks that the mask image and the font/texture image are of identical dimensions. Failure to observe this criterion will always result in incorrect font rendering, so remember that the pixel width and height of the mask must match those of the the main imagery bitmap exactly. Note that the Mask does NOT operate as a mask on data within the target display, and all characters are rendered to the screen in overwrite mode such that the whole of a rectangular character cell replaces the original screen background information. If you wish to render text with characters having a transparent background you should either render the text into a dummy sprite and then project that onto the screen or use a blitter operation from an intermediate "off screen projection" bitmap. The character cell width and height are simple pixel dimensions, and must be the same for all characters in the font. The "Characters per row" parameter specifies how many characters there are in each row of your supplied font BitMap, and is simply used to tell the HeliOS system how to extract character information from a font image. The "Flags" parameter tells the HeliOS system whether this font is a monochrome or multi-coloured font. Flags = 0 -> Monochrome Flags = 1 -> Multi-coloured Notes on the design of HeliOS fonts: HeliOS fonts are created as normal pictorial bitmap images in any Amiga paint package: the images of the font characters are simply drawn/painted in order into a graphical image. HeliOS fonts must be designed with exactly regular character cell sizes, and a full set of characters must be placed in normal ASCII character order in rows starting from the top left corner of the font image. Thus, a HeliOS font starts with the characters !"#$%&'()*+,-./0123456............etc. then proceeds through the whole of the ASCII character set. The "!" character must be in the top left (0,0 pixel position) cell, followed by the other characters in strict order proceeding from left to right. It is possible to construct a font image using either a single row of characters in a very short and wide bitmap, or using multiple rows in succeeding vertical order (as in an ordinary text layout). e.g. Single row layout: !"#$%&'()*+,-./0123456........................................etc. or Multiple row layout: !"#$%&'()*+ ,-./0123456 ........... ........... ........... .......etc. If you choose to use a multi-row layout you can employ whatever column and row dimensions you wish. The only constraint is that the characters are all represented in strict ASCII order in columns reading from left to right and with rows proceeding down the page from top to bottom. The HeliOS font definition structure specifies the character cell pixel size and the number of characters per row, so that the system can easily extract graphical character cells from the supplied BitMap. ----------------------------------------------------------------------- HELIOSMPOINTER ( flag(w) - - - ) The mouse pointer display within the HeliOS operating system can be enabled and disabled by using this routine: Flag = 1 -> Mouse pointer is on Flag = 0 -> Mouse pointer is off Note that the REPORTMOUSE function must be used to enable continuous mouse position updates. ----------------------------------------------------------------------- WAITBEAM ( n1 - - - ) This is a "quick" version of the GraphicsLib WAITBEAM command for optimum performance in fast game code. WAITFRAME ( - - - ) This routine waits for the HeliOS game system to complete its current frame before returning. FRAMERATE ( _ _ _ l1 ) Returns 32-bit address of 16 bit variable which stores the framerate control parameter for the HeliOS game operating system. To set the HeliOS framerate to 1, you would use: 1 FRAMERATE !L Setting FRAMERATE to 1 will result in HeliOS running at a maximum framerate of 50 frames/second. Setting FRAMERATE to 2 will result in HeliOS running at a framerate of 25 frames/second (= 50/2, or one frame in every 2 video frames). Setting FRAMERATE to 3 will result in HeliOS running at a framerate of approx. 16 frames/second (= 50/3, or one frame in every 3 video frames). etc. etc. FRAMECOUNT! ( n1 - - -) Store n1 as current FrameCount FRAMECOUNT@ ( - - - n1) Get current FrameCount as n1 VBCOUNT! ( n1 - - -) Store n1 as current VBCount VBCOUNT@ ( - - - n1) Get current VBCount as n1 N.B. The above functions allow access to the HeliOS Frame Counter and Vertical Blank counter, which work as follows: Frame Counter -> Counts HeliOS system processing frames This starts at zero when the HeliOS system is started, then it increments by one every time the HeliOS OS has completed one "processing frame" for all its sprites and displays etc. This processing frame time may be just one VB, but it may extend over several VBs as required. VB Counter -> Counts Vertical Blanks This starts at zero when the HeliOS system is started, then it increments by one for every Vertical Blank. This parameter is locked to the Amiga video display rate rather than the processing cycle of the HeliOS system. ----------------------------------------------------------------------- MAKECOPSTRIP ( Slice(l) _ _ _ Slice(l) or null ) Takes the display parameters defined within the Slice structure and creates an appropriate copper list. The copper list is installed in the Slice structure if successful and the Slice pointer is returned. On failure null is returned. FREECOPSTRIP ( Slice(l) _ _ _ ) Removes and frees a Slice structure's copper list which was created by using the HeliOS MAKECOPSTRIP function. ----------------------------------------------------------------------- MAKEDISPLAY ( Display(l) _ _ _ Display(l) or null ) Takes the display parameters defined within the Display and all its associated Slice structures and creates a master display copperlist. The copper list is installed in the Display structure if successful and the Display pointer is returned. On failure null is returned. FREEDISPLAY ( Display(l) _ _ _ ) Removes and frees a Display structure's copper list which was created by using the HeliOS MAKEDISPLAY function. SHOWDISPLAY ( Display(l) _ _ _ ) Installs this display as the current HeliOS active display. ----------------------------------------------------------------------- MAKESLICECONTROL ( Slice(l), Width(w), Height(w) _ _ _ SliceControl(l) or null ) Makes a SliceControl structure to be used in double/triple buffering and scroll functions. All extra display structures, bitplanes etc. are allocated and initialised fully automatically as required. On success a pointer to the new SliceControl structure is returned. On failure null is returned. After making a SliceControl structure all you need to do is INSTALL this control structure using INSTALLSLICECONTROL, upon which all double/triple buffering and scroll functions in this display slice will be carried out automatically by the HeliOS operating system. The width and height parameters determine whether this will be a single, double, or triple buffered slice, as follows: 1. If Width and Height are both zero. This slice is a double buffered slice, which means that two complete display buffers as defined by the Slice structure will be allocated. All graphic operations will be rendered into a background display and automatic display buffer switching is performed, ensuring flicker-free sprites. Each sprite/BOB must have its background saved and restored for each frame. The double buffered display area may be mapped from 16x16 blocks or it may be a complete single section display area. This mode is useful when there are NOT so many sprites on screen that it becomes more efficient to redraw the whole background with a single "blit" than to save and restore the background for each sprite individually. If there are many sprites on screen a triple buffered display may be more efficient. See below. In terms of memory useage, this mode allocates twice the memory required for a single display as defined in the display Slice structure. 2. If Width and Height are both negative. No further display buffers are allocated since this slice is a single buffered slice, so all graphic rendering will be drawn immediately into the bitplanes being displayed. This can result in flickery graphics and is not recommended for games with many moving objects. Each sprite/BOB must have its background saved and restored for each frame. The single buffer display area may be mapped from 16x16 blocks or it may be a complete single section display area. In terms of memory useage, this mode allocates just the memory required for a single display as defined in the display Slice structure. 3. If Width and Height are both positive. This slice is a triple buffered slice, which means that a double buffered display will be created, as well as a third oversized display buffer with "Width x Height" size parameters. The double buffered screen, into which sprite graphics etc. are rendered has dimensions as specified in the Slice structure. The third "triple" buffer contains the full background graphics which are always kept fully intact, so when each double buffered frame is redrawn the background graphics can be restored as a complete single-blit area from the third buffer. The third buffer may be "oversize" so that the display can scroll around it horizontally and vertically. The third buffer may be mapped from 16x16 blocks or it may be a complete single section display area. All graphic operations will be rendered into a background display and automatic display buffer switching is performed, ensuring flicker-free sprites. The display background is fully redrawn from the third buffer each frame, saving the necessity for each sprite to have its background restored. This mode is useful when there are so many sprites on screen that it becomes more efficient to redraw the whole background with a single "blit" than to save and restore each sprite individually. With just a few sprites on screen a double buffered display would usually be more efficient. In terms of memory useage, this mode allocates twice the memory required for a single display as defined in the display Slice structure PLUS the third display buffer which will usually be oversize. Although the third oversize buffer takes extra memory, the display double buffered system need not be oversize. This means that it depends on particular dimesions as to whether triple buffering takes more memory then double buffering. MAKEDPSLICECONTROL ( Slice(l), Wid(w), Hgt(w), Wid(w), Hgt(w)_ _ _SliceCtrl(l) or null ) Makes a pair of cross-linked SliceControl structures to be used in double/triple buffering for dual playfield slices. See documentation for MAKESLICECONTROL for general useage. The difference with MAKEDPSLICECONTROL is that you have two sets of Width and Height parameters, each of which sets up one of the two dual playfield slices. The SliceControl structure returned is the control structure for the first playfield, using the first two Width and Height parameters. A second SliceControl structure is also allocated and cross-linked into the first structure. This means that each dual playfield SliceControl structure contains a pointer to the corresponding SliceControl for the other playfield: * The "SliceControl_DPSControl2" field of the first SliceControl structure holds a pointer to the second SliceControl structure. * The "SliceControl_DPSControl1" field of the second SliceControl structure holds a pointer to the first SliceControl structure. If you need to gain access to the second structure, simply extract the pointer from the first structure, like this: SliceControl1A D@ SliceControl_DPSControl2 INDEXD@L SliceControl1B D! CLEARSLICECONTROLS ( - - - ) Removes any remaining active slice control structures from the HeliOS game system interrupt handler. CLOSESLICECONTROL ( SliceControl(l) - - - ) Closes down a SliceControl structure, deallocating all resources created using MAKESLICECONTROL. Note that dual playfield slices need to have this function called for BOTH of the dual playfield SliceControl structures individually. INSTALLSLICECONTROL ( SliceControl(l) - - - ) Installs a SliceControl structure into the HeliOS operating system. Having done this all sprite rendering will be automatically double or triple buffered as requested, and scrolling can be carried out using simple scroll commands or by setting appropriate fields in the SliceControl structure. The SliceControl structure should be deactivated by using the REMOVESLICECONTROL command. REMOVESLICECONTROL ( SliceControl(l) - - - ) Removes a SliceControl structure from the HeliOS operating system. See also INSTALLSLICECONTROL. MAKESLICEMASK ( SliceControl(l) - - - BitMap(l) or null ) Makes and installs a collision mask for the SliceControl structure, allowing Object-to-Display collision detection for that slice. On failure null is returned. The collision mask is a "shadow" mask constructed from all bits set in all bitplanes. This function installs the collision mask into the SliceControl structure automatically and any previous collision mask is first automatically deallocated. The function also returns a pointer to a BitMap structure which defines the mask plane: this allows you to perform any operations you wish on the collision mask. You must deallocate the mask BitMap using CLOSEBMAP when you have finished with it. ----------------------------------------------------------------------- MAKEFLASH ( FrameList(l), ColorList(l), FlashDef(l) - - - SLFlash(l) ) Where: FrameList = Table of colour RGB definition frames ColourList = Table defining Amiga colours to be flashed FlashDef = Flash dynamic control parameter structure SLFlash = Slice flash control structure Allocates and initialises an SLFlash structure, using information from the three input structures. The SLFlash structure can be used to flash or colour-cycle the colours in any slice using the command FLASHSLICE. The SLFlash structure should be deallocated using FREEMEMORY when you have finished with it. See also FLASHSLICE and FLASHSLICEOFF. See documentation "Colour_Flash_Cycle.Doc" for full discussion. FLASHSLICE ( Slice(l), SLFlash(l) - - - ) Installs SLFlash structure in Slice, setting up colour-cycling. See also MAKEFLASH and FLASHSLICEOFF. See documentation "Colour_Flash_Cycle.Doc" for full discussion. FLASHSLICEOFF ( SLFlash(l) - - - ) Removes SLFlash structure from Slice, stopping colour-cycling. See also MAKEFLASH and FLASHSLICE. See documentation "Colour_Flash_Cycle.Doc" for full discussion. ----------------------------------------------------------------------- FLASHSPRITE (Sprite(l), FlashBit(w) FlashLength(w) - - - ) Where: Sprite -> The SpriteCtrl structure of the sprite you want to flash. FlashBit -> Which bit to test (0-15) to determine if sprite is flashed FlashLength -> How many frames to sustain the flash effect This function will automatically flash a sprite for a certain number of frames, and is usually employed to implement a fast shimmering effect. This type of effect is frequently used in games to give a semi-transparent look to a sprite, perhaps when a game character is shielded, or weakened. The number of frames for which the flash effect will endure is defined by the FlashLength parameter. Whether or not a particular frame will have the sprite image "off" or "on" depends upon the FlashBit parameter, as follows: As the flash period progresses the FlashLength parameter is decremented on a frame by frame basis, and then bit-tested. If the bit corresponding to FlashBit is SET, the sprite will not be drawn (it will be invisible) for that particular frame. If the bit is CLEAR, the sprite will be drawn. For example: FlashBit = 1 FlashLegth = 9 FlashLength frame sequence: 9 8 7 6 5 4 3 2 1 0 <- Decimal 1001 1000 0111 0110 0101 0100 0011 0010 0001 0000 <- Binary ^ ^ ^ ^ ^ ^ ^ ^ ^ ^ <- Bit 1 On On Off Off On On Off Off On On <- Frame This mechanism affords a crude but effective control of the periodicity of the flash, and is adequate for most simple purposes. If you require more sophisticated flash effects it is easy to program your own mechanism using a coded extension to the SpriteCtrl structure. FLASHSPRITEANIM (SpriteAnim(l), FlashBit(w) FlashLength(w) - - - ) Where: SpriteAnim -> The SpriteAnim structure of the anim you want to flash. FlashBit -> Which bit to test (0-15) to determine if sprite is flashed FlashLength -> How many frames to sustain the flash effect This function will automatically flash a sprite animation for a certain number of frames. Please see the documentation of FLASHSPRITE for a full explanation. ----------------------------------------------------------------------- MAKESPRITESET ( BMap(l), X(w), Y(w), Wid(w), Hgt(w), Spt#(w) - - - SpriteSet(l) ) or null Builds a set of Spt# sprites, including sprite control structures, collision masks etc. The sprites are all Wid x Hgt in size, and their imagery is copied from the designated BitMap starting at position X,Y. The sprite imagery is copied sequentially, from left to right, and when the right edge of the source BitMap is reached the process moves down to the next available pixel row and starts again from the left edge. The SpriteControl structures of the new sprites are copied into a SpriteSet table which has the following format: Number of sprites (w) Width (w) Height (w) Depth (w) 1st SpriteControl structure pointer(l) 2nd SpriteControl structure pointer(l) etc. etc. The first sprite pointer is offset 8 bytes from the start of the table. FREESPRITESET ( SpriteSet(l) - - - ) Deallocates a set of sprites created using MAKESPRITESET. INITSPRITESET ( SliceControl(l), SpriteSet(l) - - - ) Initialises a set of sprites to work correctly with a particular slice. This function allocates and initialises everything for double or triple buffering etc., as required, and fully prepares the sprites for use in the designated slice. This operation does all kind of precalculations for blitting etc. which depend on slice display characteristics, so you must not attempt to use initialised sprites in other slices. INITSPRITE ( SliceControl(l), SpriteCtrl(l) - - - ) Initialises a sprite to work correctly with a particular slice. This function allocates and initialises everything for double or triple buffering etc., as required, and fully prepares the sprite for use in the designated slice. This operation does all kind of precalculations for blitting etc. which depend on slice display characteristics, so you must not attempt to use initialised sprites in other slices. CLONESPRITE ( SpriteControl(l) - - - SpriteControl(l) ) Clones a sprite, including FULL initialisation. It is best to use this function AFTER initialising the sprite to be cloned since this will save having to re-initialise the new sprite. FREESPRITE ( SpriteControl(l) - - - ) Deallocates and frees a sprite, including all subsidiary structures. SPRITEFLAGS ( - - - l1 ) A 32-bit addressed variable storing the 16-bit global sprite flag override value. ALL active sprites may be have their "Flags" control fields overridden by storing a non-zero value in the HeliOS "SPRITEFLAGS" variable: this value acts as a "universal sprite flag". The behaviour of the "Flags" value thus imposed will be exactly the same as the normal sprite "Flags" values. e.g. 7 SPRITEFLAGS !L Would cause ALL sprites to skip display updating until you restored the SPRITEFLAGS variable to 0. and 8 SPRITEFLAGS !L Would cause ALL sprites to skip display updating for one frame, after which the SPRITEFLAGS variable would be automatically reset to 0. ----------------------------------------------------------------------- MAKEHSPRITEBLOCK ( ImageID(w), Images#(w), HSImage(l) - - - HSpriteData(l) ) (Returns null for failure.) Makes an HSpriteData image block with ImageID and Images# number of hardware sprite imagery/ctrl sections. The imagery and dimensions of the hardware sprite are taken from an HSImage data definition. The number of image/ctrl sections (Images#) can be up to 255, and the ImageID can be any non-zero number. Each HSpriteData with a different image should have a different ID, but you can have several HSpriteDatas with the same ID if you wish. HeliOS will try to allocate an HSpriteData for use when multiplexing hardware sprites according to a specific ID. If you have 4 HSpriteData blocks with identical IDs and imagery you will be able to have 4 sprites on the same horizontal line. If you have only 1 HSpriteData block for a given image/ID, the sprite will only be able to appear in multiple vertical positions according to how many image/ctrl sections it has. The HSpriteData should be freed when no longer required by using the FREEHSPRITEBLOCK command. MAKEHSPRITEBLOCK_BMAP ( ImageID(w), NumberOfSpriteDefinitions(w), BMap (l), XStart(w), YStart(w), Width(w), Height(w) - - - HSpriteData(l) ) Where: XStart = Top left corner horizontal pixel offset of image start YStart = Top left corner vertical pixel offset of image start Width = Pixel width of image Height = Pixel height of image This function reads imagery from any bitmap and creates a hardware sprite definition. Ideally the bitmap should be of 2-bitplanes depth (4-colours) but the function will automatically handle other bitmap depths, albeit with colours mapped to a standard 4-colour hardware sprite specification. The result will be null if the function fails. MAKEATTHSPRITEBLOCK_BMAP ( ImageID1(w), ImageID2(w), NumberOfSpriteDefinitions(w), BMap (l), XStart(w), YStart(w), Width(w), Height(w) - - - HSpriteData1(l), HSpriteData2(l) ) Where: XStart = Top left corner horizontal pixel offset of image start YStart = Top left corner vertical pixel offset of image start Width = Pixel width of image Height = Pixel height of image This function reads imagery from any bitmap and creates a pair of attached hardware sprite definitions. Ideally the bitmap should be of 4-bitplanes depth (16-colours) but the function will automatically handle other bitmap depths, albeit with colours mapped to a standard 16-colour attached hardware sprite format. The results will both be null if the function fails. MAKEHSPRITEBLOCK_SCTL ( ImageID(w), NumberOfSpriteDefinitions(w), SpriteCtrl(l) - - - HSpriteData(l) ) This function clones the imagery from any software sprite and creates a hardware sprite definition. Ideally the software sprite bitmap should be of 2-bitplanes depth (4-colours) but the function will automatically handle other bitmap depths, albeit with colours mapped to a standard 4-colour hardware sprite specification. The result will be null if the function fails. MAKEATTHSPRITEBLOCK_SCTL ( ImageID1(w), ImageID2(w), NumberOfSpriteDefinitions(w), SpriteCtrl(l) - - - HSpriteData1(l), HSpriteData2(l) ) This function clones the imagery from any software sprite and creates a pair of attached hardware sprite definitions. Ideally the sprite bitmap should be 4-bitplanes deep (16-colours) but the function will automatically handle other bitmap depths, albeit with colours mapped to a standard 16-colour attached hardware sprite format. The results will both be null if the function fails. MAKEAUTOHSPRITEBLOCK ( ImageID(w), Images#(w), SpriteControl(l) - - - HSpriteData(l) ) Makes an HSpriteData image block with ImageID and Images# number of hardware sprite imagery/ctrl sections. The hardware and software sprites are given mutual pointers within their structures which are used internally by some of the HeliOS AutoHSprite functions. The "parent" SpriteCtrl structure should be initialised before calling this function. The imagery and dimensions of the hardware sprite are taken from the SpriteControl structure. The number of image/ctrl sections (Images#) can be up to 255, and the ImageID can be any non-zero number. Each HSpriteData with a different image should have a different ID, but you can have several HSpriteDatas with the same ID if you wish. HeliOS will try to allocate an HSpriteData for use when multiplexing hardware sprites according to a specific ID. If you have 4 HSpriteData blocks with identical IDs and imagery you will be able to have 4 sprites on the same horizontal line. If you have only 1 HSpriteData block for a given image/ID, the sprite will only be able to appear in multiple vertical positions according to how many image/ctrl sections it has. The HSpriteData should be freed when no longer required by using the FREEHSPRITEBLOCK command. MAKEAUTOATTHSPRITEBLOCKS ( ImageID1(w), ImageID2(w), NumberOfSpriteDefinitions(w), SpriteCtrl(l) - - - HSpriteData1(l), HSpriteData2(l) ) Makes a pair of HSpriteData image blocks for an attached hardware sprite. Using this function the hardware and software sprites are given mutual pointers within their structures which are used internally by some of the HeliOS AutoHSprite functions. The "parent" SpriteCtrl structure should be initialised before calling this function. The imagery and dimensions of the hardware sprite are taken from the SpriteControl structure. The number of image/ctrl sections (Images#) can be up to 255, and the ImageID can be any non-zero number. Each HSpriteData with a different image should have a different ID, but you can have several HSpriteDatas with the same ID if you wish. HeliOS will try to allocate an HSpriteData for use when multiplexing hardware sprites according to a specific ID. If you have 4 HSpriteData blocks with identical IDs and imagery you will be able to have 4 sprites on the same horizontal line. If you have only 1 HSpriteData block for a given image/ID, the sprite will only be able to appear in multiple vertical positions according to how many image/ctrl sections it has. The HSpriteData should be freed when no longer required by using the FREEHSPRITEBLOCK command. FREEHSPRITEBLOCK ( HSpriteData(l) - - - ) Frees an HSpriteData image block. MAKEAUTOHSPRITECTRLSET ( HSpriteData(l), Sprite#(w) - - - SpriteSet(l) ) Makes a set of Sprite# SpriteControl structures to correspond with the hardware sprites defined by HSpriteData. This function MUST ONLY be used to operate on HSpriteData structures created using MAKEAUTOHSPRITEBLOCKS and MAKEAUTOATTHSPRITEBLOCKS, since it requires information about the original software sprite from which these functions derived the hardware sprite definition. The new SpriteCtrl structures are used by HeliOS to control motion and collision detection for the associated hardware sprites. The new SpriteSet must be initialised using INITSPRITESET before use. The number of sprites defined by Sprite# determines how many virtual hardware sprites the HeliOS system will use. This number can be as great as 255, but only those images which can find a spare actual hardware sprite available at the right position will be displayed. The availability of hardware sprites depends on the number of images in the HSpriteData (affecting vertical availability), as well as the number of HSpriteDatas installed (affecting horizontal availability). MAKEAUTOHSPRITESET ( BMap(l), XStart(w), YStart(w), Width(w), Height(w), HSprites#(w) ImageId(w), NumberOfImages(w) - - - AutoHSpriteSet(l) ) This function extracts from the bitmap a series of similar sized but possibly different images, read successively from left to right, as might be used for an animation sequence. This is directly analogous to the MAKESPRITESET function used for creating software sprites. This function can be used to generate single sprites, but if used for multiple sprites all the images are given the same ID and can only be used in animations such that only one is "on screen" at any one time. The new SpriteSet must be initialised by using using INITSPRITE on the SpriteCtrl structure of each AutoHSprite before use. You might use the following type of code construct, for example, to initialise the first sprite of the set: MySliceControl MyAutoHSpriteSet 8. INDEXD@L HSB_SCtrl INDEXD@L INITSPRITE Of course you may initialise different sprites for use in different display slices. MAKEAUTOATTHSPRITESET ( BMap (l), XStart(w), YStart(w), Width(w), Height(w), HSprites#(w) ImageId1(w), ImageId2(w), NumberOfImages(w) - - - AutoHSpriteSet1(l), AutoHSpriteSet2(l) ) This function extracts from the bitmap a series of similar sized but possibly different images, read successively from left to right, as might be used for an animation sequence. This is directly analogous to the MAKESPRITESET function used for creating software sprites. This function can be used to generate single sprites, but if used for multiple sprites all the images are given the same ID and can only be used in animations such that only one is "on screen" at any one time. The new SpriteSet must be initialised by using using INITSPRITE on the SpriteCtrl structure of each AutoHSprite before use. You might use the following type of code construct, for example, to initialise the first sprite of the set: MySliceControl MyAutoHSpriteSet 8. INDEXD@L HSB_SCtrl INDEXD@L INITSPRITE Of course you may initialise different sprites for use in different display slices. This initialisation operation only needs to be done for the first of the two AutoHSpriteSets. FREEAUTOHSPRITEBLOCK ( HSprite(l) - - - ) Frees an HSpriteData image block and associated auto sprite control structure. FREEAUTOHSPRITESET ( AutoHSpriteSet(l) - - - ) Frees a complete set of AutoHSprites as created by MAKEAUTOHSPRITESET and MAKEAUTOATTHSPRITESET. Note that the FREEAUTOHSPRITESET will need to be called twice to free each of the two individual AutoHSpriteSets created by MAKEAUTOATTHSPRITESET. INSTALLAUTOHSPRITE ( SpriteCtrl(l), Slot(w) - - - ) This function automatically installs the hardware sprite definition block and SpriteCtrl structure for an AutoHSprite in one operation. Attached sprites are handled automatically, and in this case you should specify the LOWER of the two slot (hardware sprite channel) positions. REMOVEAUTOHSPRITE ( SpriteCtrl(l) - - - ) This function automatically removes the hardware sprite definition block and SpriteCtrl structure for an AutoHSprite in one operation. Attached sprites are handled automatically. REMOVEAUTOHSPRITECTRL ( SpriteCtrl(l) - - - ) Removes only the AutoHSprite SpriteCtrl structure from the automatic HeliOS processing system, without deallocating or changing the sprite structures in any way, and without removing the Hardware Sprite itself from the HeliOS processing system. CLEARAUTOHSPRITES ( - - -) Clears ALL SpriteCtrl structures from the HeliOS AutoHSprite handler and re-initialises the AutoHSprite system. Note that this function does not reset any fields in individual sprite control structures and sprites will be removed "as is". This means that fields such as "SpriteCtrl_Running" within each object will still be left as set when the system was last functioning. If you use this function it is up to you to reset all object parameters as required by your own code. This function ONLY clears the SpriteCtrl handler and does NOT clear the hardware sprite definition channels: if you need to clear these also you must use HSPRITE_REMOVE on occupied channels. ADDAUTOHSPRITECTRL ( SpriteCtrl(l) - - - ) Adds an automatic hardware sprite controller to the HeliOS system. The hardware sprite controller structure is a SpriteCtrl structure like those used by software sprites. This SpriteCtrl structure is used to control all dynamic and collision parameters for a hardware sprite. The use of identical control structures allows very similar, simple and consistent routines for controlling both types of sprite and makes it easy to convert between use of either type of object. INSTALLHSPRITEANIM ( HSAnim(l) - - - ) Installs a hardware sprite animation into the HeliOS AutoHSprite animation control system. REMOVEHSPRITEANIM ( HSAnim(l) - - - ) Removes a hardware sprite animation from the HeliOS AutoHSprite animation control system. HSPRITE_AUTO_ON ( - - - ) Switches on the HeliOS automatic hardware sprite multiplexer. With this switched on you can use the full range of HeliOS hardware sprite multiplexing, animation, and collision detection functions. Otherwise you can still install HeliOS HSprites, but you will have to manipulate then with your own code. HSPRITE_AUTO_OFF ( - - - ) Switches off the HeliOS automatic hardware sprite multiplexer. See also HSPRITE_AUTO_ON. HSPRITE_INSTALL ( HSpriteData(l), Channel(w) - - - ) Installs an HSpriteData imagery/ctrl block into one of the 8 hardware sprite channels. HSPRITE_REMOVE ( HSpriteData(l) - - - ) Removes an HSpriteData imagery/ctrl block from its installation in one of the 8 hardware sprite channels. HSPRITE_PLACE ( AttachFlag(w), XPos(w), YPos(w), Image#(w), HSpriteData(l) - - - ) Places a hardware sprite image on screen, using the Image# numbered image of the HSpriteData sprite set. The Image# parameter starts from 0 (= first image) etc. The "AttachFlag" parameter allows you to specify whether or not HeliOS should set the sprite's attach bit for you. The "X" and "Y" coordinates are specified from pixel "0,0" at the top left hand corner of the visible screen display. HSPRITE_CLEAR (SpriteNum(w) - - -) Clears a hardware sprite from the automatic HeliOS handler which drives the HeliOS dynamic hardware sprite control system. ----------------------------------------------------------------------- MAKEIMAGESET (SourceBMap(l), XStart(w), YStart(w), Width(w), Height(w), Image#(w) - - - ImageList(l)) This function extracts a series of equal sized bitmapped images from a large source bitmap and constructs a series of small bitmaps (fully initialised BMap structures with allocated planes etc.) which it stores in a convenient list format. The list contains header information with details of size and number of the images in the list, as follows: ImageList format: NumImages 16-bit value -> Number of images in list Width 16-bit value -> Pixel width of each image Height 16-bit value -> Pixel height of each image Depth 16-bit value -> BitPlane depth of image set ImageBmap1 32-bit value -> 1st image BMap structure ImageBmap2 32-bit value -> 2nd image BMap structure ImageBmap3 32-bit value -> 3rd image BMap structure etc. In the usual HeliOS manner the operation of bitmap extraction starts at a specified pixel position and reads successive rows of adjacent images from left to right, top to bottom, until the specified number of images has been read. This is a process exactly analogous to similar HeliOS mechanisms for the creation of sprites from large source bitmaps. FREEIMAGESET (ImageList(l) - - -) Frees and deallocates an ImageList with all associated bitmaps. ----------------------------------------------------------------------- GETCOLLHANDLER ( - - - CollHandler(l) or null ) Allocates an automatic collision handler, which can then be installed in any HeliOS collision object by simply storing its pointer in the object's _CollHandler field. Use FREECOLLHANDLER to de-allocate collision handler when finished. See also FREECOLHANDLER FREECOLLHANDLER ( CollHandler(l) - - - ) De-allocates an automatic collision handler. See also GETCOLHANDLER ----------------------------------------------------------------------- INSTALLSPRITE ( SpriteCtrl(l) - - - ) Installs a "software" sprite (BOB) into the HeliOS sprite control system. INSTALLSPRITEANIM ( SpriteAnim(l) - - - ) Installs a "software" sprite (BOB) animation into the HeliOS sprite animation control system. REMOVESPRITE ( SpriteCtrl(l) - - - ) Removes a "software" sprite (BOB) from the HeliOS sprite control system. REMOVESPRITEANIM ( SpriteAnim(l) - - - ) Removes a "software" sprite (BOB) animation from the HeliOS sprite animation control system. ----------------------------------------------------------------------- INSTALLMOTOR ( MotorStruct(l) - - - ) Installs a "motor" operator into the HeliOS motor sytem. N.B. Motors are run in order of installation. See individual docs on PATHs, JOINERs, MOVERs, LIMITERs, ADDERs etc. REMOVEMOTOR ( MotorStruct(l) - - - ) Removes a "motor" operator from the HeliOS motor sytem. See individual docs on PATHs, JOINERs, MOVERs, LIMITERs, ADDERs etc. ----------------------------------------------------------------------- SETFIELD1POS ( XPos(w), YPos(w), SliceControl(l) - - - ) Used to set the display position within an oversized playfield. Sets the supplied X and Y position for Playfield1 of the slice controlled by SliceControl. SETFIELD2POS ( XPos(w), YPos(w), SliceControl(l) - - - ) Used to set the display position within an oversized playfield. Sets the supplied X and Y position for Playfield2 of the slice controlled by SliceControl. SETFIELD1SCROLL ( XScroll(w), YScroll(w), SliceControl(l) - - - ) Used to scroll the display position within an oversized playfield. Scrolls Playfield1 of the slice controlled by SliceControl. SETFIELD2SCROLL ( XScroll(w), YScroll(w), SliceControl(l) - - - ) Used to scroll the display position within an oversized playfield. Scrolls Playfield2 of the slice controlled by SliceControl. ----------------------------------------------------------------------- SETSLICECOLOURS ( Slice(l), ColourTable(l), Start(w), Count(w) - - - ) Sets a sequence of "Count" colour values into the colour registers for "Slice", starting at colour number "Start". The colours are read sequentially from the start of a "ColourTable" which consists of a series of 12-bit RGB values stored in sequential 16-bit cells in the standard Amiga fashion. FREECOLORMAP ( ColorMap(l) - - - ) Deallocates a ColorMap structure created using MAKECOLORMAP. This routine will safely accept a null parameter. MAKECOLORMAP ( ColorTable(l), Count(w) - - - ColorMap(l) ) Allocates an Amiga ColorMap structure and initialises it according to the supplied parameters. ----------------------------------------------------------------------- -------------- 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. ----------------------------------------------------------------------- A note on routines for clearing the HeliOS dynamic operation handlers ----------------------------------------------------------------------- There are several operators which simply and indiscrimately clear out the various HeliOS dynamic systems: CLEARCOLLISIONS CLEARHSPRITEANIMS CLEARHSPRITES CLEARMOTORS CLEARSLICECONTROLS CLEARSPRITEANIMS CLEARSPRITES All these have the same effect: they clear the automatic HeliOS handlers which drive the dynamic behaviour of the associated components. These routines do no other de-allocation, or anything at all other than simply re-initialising the HeliOS dynamic handler lists. These should be used as housekeeping routines, when the HeliOS system is not actually running. ----------------------------------------------------------------------- A useful diagnostic tool ----------------------------------------------------------------------- SHOWTIMING (flag - - -) Flag -> 1=On, 0=Off Switches on and off the HeliOS internal debug colour timing display. This command is only effective when running the HeliOS game system. SHOWTIMING causes colour 0 to be reset each time the HeliOS operating system moves from one of its handler routines to the next. This causes the screen border to change colour, from the top to the bottom of the screen, as each phase of the HeliOS internal system completes its work. It is easy to see, when using this system, which of the HeliOS internal functions is using most CPU time, and it is generally most useful when writing fast arcade games. It is possible to see, graphically and explicitly, just how close your code is coming to the limits of running within a single video frame. Here are the colour allocations: Hex colour value HeliOS routine ---------------- -------------- RGB 000 Restore BOBs 444 Process display controls 777 Process MAP rendering 800 Process sprite animation 080 Draw BOBs 008 Draw hardware sprites 880 Process hardware sprite anims 808 Process collision detection 088 Process motors 000 End of frame ----------------------------------------------------------------------- End -----------------------------------------------------------------------