FastGfx V0.2a By David Newton (dave@nbsamiga.demon.co.uk)


INTRODUCTION:

 FastGfx is a complete set of BlitzBasic2 routines to do all your required
gfx work using the cpu (instead of the blitter) so that FastMem can be used
instead of ChipMem. This set of routines can be used to render all your
software's graphics to a temporary fastmemory bitmap, and then copied to
your screens bitmap. Alternately, you can just use fastmemory shapes, and
draw directly to chipmemory bitmaps.


DISCLAIMER:

THIS SOFTWARE IS SUPPLIED 'AS IS' : THE ENTIRE RISK AS TO THE USE OF THE
SOFTWARE IS ASSUMED BY THE USER. IN NO EVENT WILL THE AUTHOR BE LIABLE
FOR DIRECT OR INDIRECT DAMAGE OR LOSS RESULTING FROM THE USE/MISUSE OF
THIS SOFTWARE.


USAGE:

Here is a list of all the routines included with FastGfx, and the required
input and output (if any). Some of the routines are functions so that you
can test to see if the routine was successful.  Those routines that are
functions will have a * against it, and this means it returns true or
false, meaning whether the function was able to perform it's task without
any problems. All the routines names are case sensetive.


*InitFastShape{MaxFastShape}

This routine sets up the FastGfx shape system for a maximum number of
MaxFastShape shapes to be used. You need to call this before any 
shape/blit/block routines are called. If this function returns false,
then you can't use the shape system as there's been a problem (some
memory problem), so you would need to do some form of error checking, and
inform the user and quit the program. If you don't use any of the 
shape/blit/block routines in your program, then you don't need to call this.


RemoveFastShapes{}

This routine kills ALL FastGfx shapes, and frees all the memory for all the
shapes. You don't need to call this as Blitz will free all the memory at the
end of the program (with END). If you call this in your program, do not make
any more shape/blit/block calls after, as this will almost certainly crash.


FreeFastShape{FastShape}

This routine frees the graphic memory (and mask) of FastGfx shape number
FastShape. You can then later make a new shape in this shape, but until
then, you won't be able to use this shape.


*MakeBitmap{Bitmap,Width,Height,Depth,Memory}

This routine makes a standard blitz bitmap, that is compatible with blitz,
and also compatible with the FastGfx routines. Simply pass the bitmap number
to create, and the width and height and depth of the bitmap. You also need
to pass the Memory Type you want the bitmap to be allocated with. This is
a standard amiga memory type value (as used by Exec), and you will find
a brief description of these in the CONSTANTS section of this document.
This routine will return true or false depending whether the bitmap was
created or not. If you create a CHIPMEM bitmap, then all the standard
blitz drawing and graphics functions will work on the bitmap, if
you choose fastmemory, only FastGfx will be able to render to that bitmap.


*TestCpuBitmap{Bitmap}

This routine tests a standard blitz bitmap to see if it is compatible with
the FastGfx set of routines. Simply pass the number of the blitz bitmap you
wish to test. This should be done on all bitmaps not made using the 
MakeBitmap FastGfx command (above). If this returns false, it means that
you can not use the FastGfx graphics commands on this bitmap, and so you 
should inform the user, and exit. MakeBitmap always makes bitmap's that 
work with FastGfx, this was only included so you could test a screens 
bitmap, or a standard blitz bitmap for compatiblity.


SetCpuBitmap{Bitmap}

This routine sets the blitz bitmap passed to be used for all the FastGfx
routines. This is similar to the blitz Use Bitmap command, and makes all
further routines output/input to and from this bitmap. Just supply the
blitz bitmap number. This must be done atleast once, to direct all the
routines to a bitmap. You must call this to be able to output any gfx
at all!


SetCpuScroll{Bitmap}

This routine is similar to the SetCpuBitmap routine. This sets the source
bitmap for any further scroll routine calls. This must be set atleast once
for any scroll calls to be used. The idea behind having a set scroll source
routine is that usually, you want to copy from the same source everytime,
and this allows you to set the source once, and you can still change the
source for further scroll routine calls by using this routine again.


CpuBlockScroll{XSrc,YSrc,Width,Height,XDest,YDest}

This routine copies a section of the source bitmap (the source bitmap is
set using the SetCpuScroll routine) from XSrc,YSrc to XDest,YDest on the
destination bitmap (the source and destination can be the same). The
destination bitmap is the currently used FastGfx bitmap (set by using the
SetCpuBitmap routine). The Width and Height of the block are specified
using Width and Height. This is the BLOCK version of the Scroll command,
which means that all X positions, and the Width, must be a multiple of 16
pixels. (ie, X could be 0,16,32,48,64 etc). This is faster than the normal
CpuScroll command, and should be used for moving big chunks of bitmaps
around.


GetFastShape{FastShape,X,Y,Width,Height}

This routine grabs a FastGfx shape from the currently used FastGfx bitmap
(set by SetCpuBitmap) into the FastGfx shape number FastShape. This can
be used to get any size shape, and from any x and y positions (on the 
bitmap). It will also make a mask for the shape.


FreeFastCookie{FastShape}

This routine frees a FastGfx shape's mask. This is only useful if you want
to output the shape using the block command, as the block command doesn't
require a mask. You can not blit the shape after calling this, as it has
no mask.


MakeFastCookie{FastShape}

This routine makes a mask for a FastGfx shape. This is only useful if you
have free the mask using the FreeFastCookie routine, or if you have change
the shape's graphics.


CpuBlit{FastShape,X,Y}

This routine blits the FastGfx shape number FastShape, onto the currently
used bitmap (set by using SetCpuBitmap) at x,y. There is no clipping, and
it can be blitted to any x and y position on the bitmap. The bitmap must
have the same (or bigger) depth, otherwise the blit will not work correctly.
This uses the FastGfx shape's mask to merge with the bitmap's contents.


CpuBlock{FastShape,X,Y}

This routine blocks the FastGfx shape number FastShape, onto the currently
used bitmap (set by using SetCpuBitmap) at x,y. There is no clipping, and
it can only be blocked to x positions that are a multiple of 16, whereas
y can be any number. The bitmap must have the same (or bigger) depth,
otherwise the block will not work correctly. This doesn't use the FastGfx
shape's mask and therefore replaces any graphics that were under this shape
on the bitmap.


To Include this set of routines into your program you need to add two lines
to your program and add a resident file (if it's not there already) in
compiler options.

1) Add the following line to your program (somewhere near the top)

#FGFX_COMPACT=0

2) Add the following line to your program (somewhere near the top)

Include "FastGfx.bb2"

3) Go to Compiler Options, and in the resident box, enter

BlitzLibs:bb2objtypes.res


You should know be able to call the above routines, and use the FastGfx
system. If that didn't work, try looking for the file bb2objtypes.res, and
if you haven't got it..find someone that does. If that's not the problem,
have you copied the include to your current source directory??? Or just
simply put the path where this readme and the FastGfx.bb2 file is infront
of the filename in the include statement. If all else fails try emailing
me :). Good Luck

The #GFX_COMPACT constant is actually a flag to tell the include to
compile certain routines instead of others. If this equals 0, then the
compiler will compile all the slightly faster hardcoded depth routines,
which take up more memory, and if this equals 1, then the compiler
will compile all the non hardcoded slightly slower routines, that take up
less memory and space.

There are some constants in the include file, and these allow you to turn
off whole sections of the FastGfx includes. Say your program wanted the
drawing routines only, then you could turn off the shapes, and it won't
compile those routines, and take up less memory......and vice versa, so
you can make your program as compact as possible.


EXAMPLE:

> Assumes you have included the FastGfx file above here, and set the
> constant #FGFX_COMPACT before that, and setup the resident file as above.

If InitFastShape{20}=false then end		;this quits if the shape setup
									;wasn't successful.

If MakeBitmap{0,320,256,5,0}=false then end	;this quits if the make bitmap
             							;wasn't successful.

SetCpuBitmap{0}						;now set the bitmap to use
									;for the FastGfx routines.

GetFastShape{0,0,0,16,16}				;Get FastGfx shape 0. It will
									;be grabbed from the current
									;bitmap (SetCpuBitmap) starting
                                             ;at 0,0 and make it 16 pixels 
                   						;wide, and 16 lines high.

CpuBlit{0,100,100}						;Now blit that same shape
									;back to the current bitmap
									;(SetCpuBitmap) starting at
 									;100,100

End									;now end, and free all the
									;Fast Gfx data automatically!


NOTES:

This will only work on planar bitmaps at the moment (ie, non chunky). It
will also not work correctly on interleaved bitmaps (though that's planned).

All bitmap MUST be allocate continuosly.....Use MakeBitmap to create
a bitmap that can be used by these functions (or use cludgebitmap). If
you make a bitmap in chipmemory, it can be accessed by normal blitz
commands as well as the cpu functions. If you use screensbitmap, I'd
advise checking that it is useable with the cpu functions, by using the
TestCpuBitmap function. AFAIK, most screens in newer amigas are continuous
but some can be interleaved. The test will not be able to tell if the
screens bitmap is chunky, but then you shouldn't be using screensbitmap
on chunky screens (gfx card screens) as they are not the same as normal
amiga screens/bitmaps.

All the save and load routines use blitz's file 0. So don't have any files
open using file 0, when you call a save or load routine.

You have a maximum of 32767 shapes available, and the limit for bitmaps and
shape sizes are 32000x32000 (pixels by lines). You can have a depth of 1
to 8, and you should always output your shapes to a similar (or bigger)
depth bitmap. The Scroll command takes the lowest depth bitmap and only
copies those number of bitplanes.

This isn't supposed to be a complete gfx answer, but it should be usefull
for 90% of the things you want to do.

I could have made a user library of these...but I didnt...for a few reasons,

1) I can change things easier, and include it directly in the program
2) I think there are enough bad user librarys about already
3) I have some clever space saving stuff which couldn't be done
   using a library
4) The user can modify things, and create their own specific routines


TO-DO:

Chunky compatible bitmaps and shapes and routines
Interleaved bitmaps
Text outputing
Examples of my routines in action