SPRITE GENERATOR SYSTEM using the NEOCHROME-MASTER ART PROGRAM ============================================================== by Peter Hibbs for the ICTARI USER group. September 1993 INTRODUCTION. This document details a method of generating colour sprites (of any size) using the NEOCHROME-MASTER art program and how to display them in the users program. The NEOCHROME-MASTER program is a modified version of the original NEOCHROME art program from ATARI and has a number of improvements including a facility to cut out a large number of sprite objects from up to 10 Neochrome pictures and store them in a sprite object file which is then saved back to disk. Unfortunately, ATARI have banned the sale of this program for copyright reasons (it is a pity they did not adopt it as the official version) but it is probably still available from some sources. Although the original version did have an option to save sprite objects (as source code) it is not powerful enough to be that useful. A number of other files and programs should be used in conjunction with this document, they are - SPRITE.S Source code for the sprite display routines SPR_INIT.DOC Data sheet for the sprite initialisation S/R M_SPRITE.DOC Data sheet for the m_sprite S/R S_SPRITE.DOC Data sheet for the s_sprite S/R GRIDLOCK.S Source code for the sprite demo program GRIDLOCK.PRG Assembled version of the demo program GRIDLOCK.OBJ Sprite object file for the demo program GRIDLOCK.NEO Neochrome object definitions for the demo program SPR_CHCK.DOC Document file for sprite check program SPR_CHCK.PRG Sprite check program SPR_CHCK.RSC Resource file for SPR_CHCK program SPRITES.TXT This document To write a program using sprites you should follow these steps - 1. First plan out the program and the number, shape, size, etc of the sprites to be used. It is easy to add sprites to the sprite definition picture file at a later stage but it can save a lot of hassle if some thought is given to how they are stored (see later for more info). 2. Run the NEOCHROME-MASTER program (I use version 2.10) and design or import the sprite images. If there are more sprites than can be fitted on one screen, use screens 1-9 as necessary. Screen 0 should be used first and the colour palette set as required, the SPR_CHCK program (described later) uses the screen 0 palette when displaying the sprites. 3. Generate a sprite object file using the CUTTER facility (described later) and save the file to disk using the name of the program being written, i.e. GRIDLOCK.OBJ. 4. Write your program and load the sprite object file into memory somewhere near the start of the program (see the SPR_INIT.DOC data sheet for more information). 5. The program can then display the sprites using the sprite display routines supplied. SPRITE DESIGN. There a number of points to observe when designing sprites and allocating colours to the colour palette. 1. First set up the colour palette. Index colour 0 (the one on the extreme left of the palette display) is always regarded as 'transparent' by the sprite display routines and must not be used as a 'colour'. It would normally be set to black although if a sprite also uses black, it can be made any colour (say a very dark blue) so that black sprites can be seen. Even though index colour 0 is shown as a colour, it will not be displayed within the user program. Note that if black is required as a colour, it must be set up on another index colour (index No 1 for example). Index colour 15 should normally be set to white (or a very light colour) so that the SPR_CHCK program can display the palette correctly. If more than one screen is used to store sprites, the colour palettes on these should be the same as screen 0, as far as possible. 2. Design the sprites and store as many as possible on each screen, especially if they are large or there are a large number or you may run out of screens. It is useful to number each sprite on screen (starting at 1) and to make a note on paper of the number of each sprite and its function for use when writing the program later. When positioning the sprites on screen the y co-ordinate is unimportant. The x co-ordinate of the left edge of the sprite, however, should be set on a 16 pixel boundary. Each sprite should be regarded as being an exact multiple of 16 pixels wide, for example if the visible area of a sprite is 40 pixels wide, it should be regarded as being 48 pixels wide (3x16) when placing other sprites near to it. When the sprite CUTTER option is used, the rectangle around the sprite must be a multiple of 16 pixels wide. This is due to a small bug in NEOCHROME-MASTER which sometimes colours in the transparent pixels around the sprite image if this procedure is not observed. It is also useful to draw a small 'corner' at the top left and bottom right of irregular shaped sprites to assist in the cutting out process later. See the GRIDLOCK.NEO picture for an example of these techniques. The pixel boundaries for the x axis are shown below for reference (to save you working them out) - 0,16,32,48,64,80,96,112,128,144,160,176,192,208,224,240,256,272,288,304 When a sprite is displayed, the program passes the x and y co-ordinates to the sprite S/R to define the position on screen. These co-ordinates (known as the hot spot) normally refer to the top left pixel of the sprite rectangle. For stationary sprites this is usually adequate, however, for moveable sprites it is frequently useful to have the hot spot in the centre of the sprite to make programming easier. Unfortunately, NEOCHROME-MASTER does not provide any facilities for changing the hot spot but it does provide two spare bytes in the sprite object definition file for each sprite which can be used to store an x and y offset value for the hot spot. The SPR_CHCK program (described elsewhere) provides an option to store the offset values in these spare bytes. If this option is required it should be borne in mind when designing the sprite, i.e. the width and height should be an odd number of pixels so that the hot spot can be placed in the exact centre. Also, if a number of sprites are to have the hot spot changed, they should be made consecutive numbers so that the 'range' option in the SPR_CHCK program can be used. Note that the maximum value of the offset is 255 (one byte size). CUTTING OUT SPRITES. When the sprites have been designed (and the NEOCHROME picture saved to disk) it is time to generate a sprite object file. Click on the CUTTER (scissors) icon to display various options most of which are 'greyed' out. If this is a new object file being stored, select the first sprite with the mouse (see below), if a file has already been stored on disk and needs to be amended, click on LOAD and load in the file. Also 'load all used pictures' when requested, this loads in the NEOCHROME screens with the sprite definitions. MAKE SURE that any existing sprite file in memory is first cleared (by clicking on NEW) because any new file loaded in is tagged on to the end of any file already in memory and you will end up with hundreds of sprites (is this a bug or intentional ?). To select a sprite, click on the top left pixel of the sprite rectangle, drag the flashing dotted box down to the bottom right pixel and release the button. Note that the sprite width and height are displayed in the CUTTER box during this operation. As mentioned above, ensure that the left x co-ordinate is on a 16 pixel boundary and the right co-ordinate is on a 16 pixel boundary minus 1. Click on the ADD icon (or press F1) to add the sprite to the object file, the number 001 will appear in the centre box. Repeat the process for each sprite until all sprites have been captured and then click on SAVE to save the sprite file back to disk. Enter an appropriate filename into the file selector (the .OBJ extension is added automatically) and save the file WITH the header information. It is IMPORTANT that when adding further sprites to an existing object file, the last used sprite (this number is shown at the bottom of the CUTTER box) is displayed in the centre box before clicking on the ADD box. If this is not done the additional sprite/s will be placed at the current sprite position and mess up the whole file. To display (or select) a sprite, click on the box either side of the current sprite box until the required sprite number appears in the centre box and then click on SHOW. The dotted rectangle will appear around the selected sprite (you can use the GRIDLOCK.OBJ and GRIDLOCK.NEO files to try these options out). To change an existing sprite first edit the sprite image with the normal NEOCHROME tools and then select it as described above. Move the dotted rectangle to the new position by dragging the bottom right corner (if required) and then click on the CHNGE box to store the new image in the sprite object file. Don't forget to re-save the sprite file AND the NEOCHROME picture to disk. It is also possible to delete a sprite but as this will change all the numbering system it is not recommended, if you plan your sprites properly this should not be necessary anyway. COLOUR PALETTE. The sprite object file does not store any information about the colour palette since the palette colours could be different for sprites on different screens. NEOCHROME-MASTER does have a facility, however, to save the palette information to disk as a source file which can then be imported into the program source file to set up the palette colours at the start of the program. Select the main screen by pressing key 0 on the keypad and then click on the GRABBER (hand) icon. Click on SAVE PALETTE *.S to save the palette colours to disk using a suitable filename. This file should then be inserted into the program source file and used to set the screen colours with the usual BIOS call. The file can then be deleted from the disk, if required. Although the programmer should not need to know the format of the sprite object file it is shown below for reference. ------------ FORMAT OF NEOCHROME-MASTER SPRITE DATA FILE ------------ Offset Size Contents Function Section 1 (Ident and version, 10 bytes) 0 6 'NEOOBJ' Identification characters 6 2 01 01 Version (11) 8 2 nn nn Offset from next byte to section 4 Section 2 (Screen filenames, 14 bytes/filename) 0 1 nn Screen number (0-9) 1 12 FILENAME.OBJ Filename + extn 12 1 00 NUL chr The above section repeated for each screen filename used Section 3 (Offset to end of file and number of sprites, 6 bytes) 0 4 nn nn nn nn Offset to end of file 4 2 nn nn Number of objects in file Section 4 (Header block for sprite objects, 20 bytes/sprite) 0 4 nn nn nn nn Offset to object data block 4 2 nn nn Width of sprite in pixels 6 2 nn nn Height of sprite in pixels 8 2 00 04 Number of planes (always 4) 10 2 nn nn Width of sprite in bytes 12 2 nn nn x co-ordinate in screen 14 2 nn nn y co-ordinate in screen 16 2 00 00 x and y offset values (see text) 18 2 nn nn Screen number (0-9) The above section repeated for each sprite Section 5 (Sprite data, nnnnnnnn bytes/sprite) 0 ? nn nn Sprite data to end of file ------------End of sprite data----------- SPRITE CHECK PROGRAM. One small problem with NEOCHROME-MASTER is that it is not easy to display the sprites easily from within the program one after the other, it is not easy to determine the size of each sprite and it is not possible to set the hot spot offset values. The SPR_CHCK program allows the programmer to display the information on each sprite as well as the sprite images themselves easily. It also allows the sprite object file to be modified with the hot spot offset values and saved back to disk. If the programmer wishes to use these options the SPR_CHCK program should be used to make the necessary changes. See the SPR_CHCK.DOC file for the operating instructions. GRIDLOCK PROGRAM. To demonstrate the use and programming techniques of the sprite routines I have written a simple word game program called GRIDLOCK which programmers may study and change as they like. The source code is provided and should be assembled with the Devpac Assembler using the GEMMACRO, VDILIB and AESLIB files (you will probably have to change the pathnames in the 'include' pseudo ops for your own set up. An assembled version (GRIDLOCK.PRG) is also provided on the disk to try out first, the GRIDLOCK.OBJ file is the sprite data and must be in the same directory as the program itself. The GRIDLOCK.NEO file contains the sprite definitions and can be viewed with the NEOCHROME-MASTER or SPR_CHCK programs. The idea of the game is for two players to make words across and down (as in Scrabble) which must have three or more letters. Each player has alternate turns and moves one letter down into the grid on each turn to try and make a word. A three letter word scores 3 points, a four letter word scores 4 points and so on. Words that are made across and down at the same time score for both words. Press the right button to change a letter after it has been selected. Perhaps someone would like to add to the program so that the computer plays against the user and also keeps score. If you don't like the rules you can make up your own. CONCLUSION. Programmers are welcome to use any of the sub-routines mentioned in this document in their own programs. If, however, they are used in any published programs I would appreciate a mention in the accompanying documentation. If anyone has any comments (good or bad) to make on the above please let me know at - 63 Woolsbridge Road, Ashley Heath, Ringwood, Dorset, BH24 2LX