ARM Club 1

home *** CD-ROM | disk | FTP | other *** search

/ ARM Club 1 / ARM_CLUB_CD.iso / contents / apps / program / d / demofx / !DemoFX / FXManual < prev next >

Wrap

Text File | 1991-10-14 | 15.1 KB | 366 lines

DemoFX ~~~~~~ DemoFX is a module containing graphical effects similar to those used in professional games and demos. The purpose of this module is to allow enhancement of P.D. games or demos. The module can take over the repetitive tasks of updating scrolltexts and starfields, allowing the programmer to concentrate on the main program. DemoFX allows control of the machine code effects from BASIC via *commands and SYS calls. To get best use from DemoFX please read this file. *********************************************************************** Quick Copyright Notice ~~~~~~~~~~~~~~~~~~~~~~ The contents of the !DemoFX directory are Public Domain and may be distributed freely. There is no stipulation about breaking the files from the directory up, provided that this Manual file is included with any copies of the DemoFX module. The DemoFX module is distributed on the understanding that it will not be sold for profit (P.D. libraries may charge for disks, carriage etc). The !Convert utility is also P.D. and is subject to similar conditions. *********************************************************************** About the Demo ~~~~~~~~~~~~~~ There is a short demo included with this version of DemoFX to show what can be done. If it repeatedly crashes your computer, load the !RunImage file into BASIC and delete the line that reads: SYS "OS_UpdateMEMC",64,64 then re-save the program as !RunImage. This line speeds up the ROM clock rate from 4 to 8 MHz so that DemoFX and soundtracker can run at the same time. If you have an older computer, then you will have 4MHz only ROMs. If you have to alter the program, you may get some audio interference from soundtracker. DemoFX is in 4 parts, the Scrolltext, the Parallax Starfield, the Screen Fader and the Sprite folder. Each part functions independently of the others. The Scrolltext: ~~~~~~~~~~~~~~~ This module section used the 50Hz VSYNC event to draw a scrolltext along the bottom of the screen. The intended mode of use is 13. It doesn’t work very well outside this mode. If you have used my ScrollText module, you will recognise many similarities (yes, that's right, they're exactly the same!). The scrolltext provides these *commands: *ScrollFile <filename> *ScrollOn *ScrollOff *ScrollGo *ScrollCheck *ScrollFont <1 2 3 4 5 6 7 8 9> <filename> *ScrollWrap *ScrollLine "<text>" *ScrollFile <filename> loads a textfile for scrolling (see below for details) *ScrollOn starts scrolling in current mode. *ScrollOff indefinitely pauses the scrolltext (restart with *ScrollOn) *ScrollGo sets mode 13 then executes *ScrollOn *ScrollCheck checks the error request flag. If set, it returns an error type &DE3 ("Scrolltext to user message") then clears the flag. *ScrollFont <slot> <filename> loads a demofont file (type &601) into the specified slot (where slot is between 1&9). See below about font creation. *ScrollWrap causes instant wrap to start of scroll's text file. *ScrollLine "<text>" temporarily overrides file based scrolling with the specified text. The text can contain any scrolltext control codes but must be 255 or less characters long. Scrolltext files: These are simple ASCII text files which are loaded into the scrolltext module for scrolling. You cannot start scrolling unless a file has been loaded. If you try to do so without a file loaded, a "No scrolltext data" error (type &DE0) will be produced. Files are retained over soft resets. There is no theoretical limit on file size - only that of free memory. Any memory taken up by the file is taken from the RMA. The files MUST be entirely in upper case. Numbers and punctuation can be used normally. You may find that a couple of punctuation symbols have been replaced with other characters. There are a few exceptions to this rule of being in upper case. Some lower case characters are used to produce effects in the scrolltext. Some of these characters take a one digit qualifying number after them. Failure to produce find this qualifier (with the exception of the x command) will probably cause a crash. The commands are: f<n> Select font slot <n>. You must have previously loaded a font into slot <n>, otherwise the font vector still points into the zero page and random garbage will be displayed. The scrolltext's built-in font is in slot 0 Example: THIS IS FONT 0 f1AND THIS IS FONT 1 p pause scrolltext for 1 second. Example: SCROLLING NICELY. AND NOW A PAUSEp s<n> select speed <n> where <n> is between 1 & 9. 1 is the slowest speed, 9 is the fastest. Remember that the greater the speed, the more system time it takes. The system time taken by speed 9 is about 10 times that of speed 1. The default speed is 2. Bear in mind that the scrolltext is almost unreadable at speeds above 3 or 4. Example: s1SLOWLY FIRST, s2THEN FASTER, s3THEN FASTER STILL. s1NORMAL. w causes the scrolltext to wrap to the start of the file. ALL files for scrolling must end with this character to avoid a lot of messy garbage. Example: TIME TO WRAP.....w x<n> causes the error request flag to be set. If *ScrollCheck is used after this point an error will be produced. The one-digit number <n> can be read using SYS "DemoFX_ScrollCheck" TO number. This puts the value of <n> into the BASIC variable number. In this case alone, the qualifier can be omitted. In this case, the program will find a character apart from a number. This causes the error number to be set to &FF (255). When a numeric qualifier is provided, the number is not scrolled. However, if another type of qualifier is given (to set the error number to &FF) then the qualifier will be displayed - this gives compatibility with scrollfiles from earlier scrolltexts. *ScrollCheck cannot differentiate between error numbers. Also, if x0 is used, the error number is set to &A (10). Example: PRODUCING ERROR NUMBER 10 x0 AND ERROR NUMBER 255 x AND ERROR NUMBER 5 x5 The control v is also used internally by the module by the ScrollLine function. DO NOT include this code in ANY file for scrolling. Creation of DemoFonts ~~~~~~~~~~~~~~~~~~~~~ To create a new font for the scrolltext, you must design the letters as sprites. All the sprites must by 32*32 pixels in mode 13 with no palette and no mask. You need to design characters up from ASCII 32 (space). There is no point in designing characters beyond ASCII 96 (£) as these cannot be displayed by the scrolltext. The characters you design must then be placed in a single spritefile in ASCII order from SPACE upwards (ie !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_£). This means that the sprites will appear in ASCII order in the !Paint window. Each letter must also incorporate a gap to separate it from other letters. If you omit this gap, it becomes possible to run the letters together to create wide designs such as pictures or logos. Once this is done, you have to convert the spritefile to a demofont file (type &601). Dragonrider (David Shepherdson) has furnished me with a very nice multitasking program to do this. Once this is finished, you can load the font with *ScrollFont and use it as normal. If the convert program rejects your sprite file, check that all the sprites are of the right size (32*32) and have no masks or palettes included. If, when you use the font, the wrong characters are displayed, then the spritefile was in the wrong order - start again! DO NOT delete the spritefile of your font because it is impossible to recover from the demofont file. Scrolltext SWI (SYS) calls: ~~~~~~~~~~~~~~~~~~~~~~~~~~~ SWI "DemoFX_ScrollFile" (&50004) Load file for scrolling (as in *ScrollFile) Entry: R0 points to control character terminated filename Exit : All registers preserved SWIs "DemoFX_ScrollOn, ScrollOff,ScrollGo" (&50005-&50007) Perform *command of the same name No parameters SWI "DemoFX_ScrollCheck" (&50008) Check for error request and return error number Entry: No entry parameters Exit : R0 contains requested error number or 0 if no error request Note that once this command has been executed that the error request flag is cleared. This ensures that each request only produces one result. SWI "DemoFX_ScrollFont" (&50009) Load Demofont into specified slot Entry: R0 contains slot number R1 points to control character terminated filename Exit : All registers preserved SWI "DemoFX_ScrollWrap" (&5000A) Immediate scrolltext wrap to start. No parameters SWI "DemoFX_ScrollLine" (&5000B) Override file-based scrolling with message Entry: R0 points to control character terminated string. Exit : All registers preserved Note that the string must have one leading and one trailing space (ASCII 32) character. E.g. string = " OVERRIDE MESSAGE " These are all the SWIs provided by the scrolltext section. Scrolltext credits: Coding by BATMAN Help in debugging for 4Mb computers by DRAGONRIDER The Parallax Scrolling Starfield ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This module section uses the 50Hz VSYNC event to draw a field of 255 stars. The scrolling is on 4 levels, brightest stars moving the fastest. The default starfield is one that scrolls from right to left. If the scroll is a horizontal one, then the stars will move slowly up (or down, depending on the direction) the screen. The stars will automatically disappear behind objects drawn on the screen provided that these objects are not the same colour as the stars. When the routine is called, all the stars are unplotted. The routine checks that the pixel is the colour of a star before it is unplotted. The stars are then all replotted in a new position. Before each star is plotted, the routine checks that the pixel is black before the star is plotted. This is how the stars appear to disappear behind white text or coloured logos. If you want to draw a sprite that will appear to float above the stars then do not use colours 254,210,47 or 45 as numbered on the !Paint 256 colour palette. Starfield *Commands: *StarsOn turns the starfield on *StarsOff turns the starfield off Before you use *StarsOn ensure that there is at least 80k of screen memory allocated by the task manager. The starfield is intended for use in 80k modes, but can be used in modes that take up less room provided that there is 80k of screen memory allocated. Mode 13 is the intended mode for use. Starfield SWIs ~~~~~~~~~~~~~~ SWI "DemoFX_StarsOn" (&5000C) Execute *StarsOn No Parameters SWI "DemoFX_StarsOff" (&5000D) Execute *StarsOff No Parameters SWI "DemoFX_StarStep" (&5000E) Set step in bytes between successive plots of the slowest stars. Entry: R0 contains new step Exit : All registers preserved Note that this sets the speed of the slowest level of stars. The other levels move at 2,3 or 4 times this speed depending on their colour. This SWI is also used to set the direction of the starfield. A step of 1 is default, but a step of -1 reverses the starfield direction. A step of 320 (the number of bytes per line in an 80k mode) causes vertical scrolling. You can set the direction easily by assigning a variable X with the horizontal component of movement (i.e. +ve or -ve number less then 320) and variable Y with the vertical component of movement (i.e. +ve or -ve number less than 255) the star step will then be given as X+(320*Y). Note that +ve Y is upwards and +ve X is left. Starfield credits: Coding by BATMAN Preliminary testing by DRAGONRIDER Screen Fader ~~~~~~~~~~~~ This is a simple machine code program that pokes 0 words into screen memory with a step between each. The starting place is then moved on and the process repeated. This causes the screen to be cleared in a pattern. Fader *Commands ~~~~~~~~~~~~~~~ *Fade clears the screen to logical colour 0. This works in any mode though the more memory it has to clear, the slower it is. Fader SWIs ~~~~~~~~~~ SWI "DemoFX_Fade" (&50003) Execute *Fade No parameters SWI "DemoFX_FadeStyle" (&50000) Entry: R0 contains new fade style Exit : All registers preserved. Note that this call sets the gap in bytes between successive pokes of 0 words into screen memory. The default gap is 11. DO NOT set the step to 0. Steps of 5 or greater which are not divisible by 4 are advised. There is no limit to the size of step, but one that is greater than the amount of memory taken by the current mode just causes a plain bottom to top clear. Fader credits Coded by BATMAN Sprite Folder ~~~~~~~~~~~~~ This is only provided as an SWI call. It takes a sprite and plots it onto the screen. Due to the way it is plotted, the sprite seems to swing down from the top. This is similar to the effect used on the Drop Ship title screens. Folder SWIs ~~~~~~~~~~~ SWI "DemoFX_FoldSprite" (&5000F) Fold sprite onto screen Entry : R0 contains sprite type R0=0: Plot sprite R1 points to a sprite file which has been *Loaded into memory. R2 contains the plot offset (see below) R0=1: Plot raw R1 contains the width of the sprite in bytes R2 contains the height of the sprite in scanlines R3 points to the beginning of raw screen data R4 contains the mode for use R5 contains the plot offset R0=2: Plot from user sprite area R1 points to a user sprite area R2 contains plot offset R3 contains the sprite's number. (This is the number of the sprite in the area. E.g. to plot the 5th sprite in the area R3=5. This method is used because it is a lot easier than string searches.) This SWI is either given the mode for use (R0=1) or loads it from the spritefile (R0=0). If the current screen mode is not the one specified then the correct one will be selected. The plot offset is used to set where the sprite will appear. An offset of 0 is at the top left of the screen. Every time you add one to the offset, the fold position will move right. You can move the fold position downwards by adding the number of bytes across the screen to the offset (this value is returned in R3 by SWI "DemoFX_ScreenMem"). When R0=1, this is used to plot raw screen data (a sprite is raw screen data with a header tagged on). This command allows more flexibility, but requires more work to set up. When used with R0=0, only the first sprite in the file is folded. The dimensions of the sprite are automatically read from it's header. Miscellaneous Functions ~~~~~~~~~~~~~~~~~~~~~~~ There are 2 functions which form no part of any of the 3 module sections. These are the ShutDown and ScreenMem SWIs SWI "DemoFX_ScreenMem" (&50001) Read screen memory allocation for current mode. Entry: No entry parameters Exit : R0 points to the bottom of screen RAM R1 points to the top of screen RAM R2 contains the number of bytes used by the current screen mode. R3 contains bytes per line used by the current screen mode. Note: This SWI is used internally by DemoFX, but is made available to the user because I am incredibly generous. SWI "DemoFX_ShutDown" (&50002) Shuts down all DemoFX VSYNC based effects (i.e. scrolltext and starfield) No Parameters That's it for the DemoFX (1.05) manual. If you have any suggestions for more effects, bug reports, or anything (even praise - Hint Hint), contact me at: Batman The Postern Chignal Smealey Chelmsford Essex CM1 4SU TTFN Batman (19/8/91)