     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
