SpaceForce/Assignment3Project/Assignment3Project

A5 Allegro, version 1



DISCLAIMER:



 This software and associated files are provided 'as is'

with no warranty or guarantees of any kind, you use them

at your own risk and in doing so agree that the author is

in no way liable and cannot be held responsible for any

loss of time/data/hair or anything else that may occur

either directly or indirectly from the use of this

software or associated files.



==============================================

http://www.tilemap.co.uk



Allegro 5 converted by Neil Walker



C++ notes: MappyAL will work fine with C++, but the file 'mappyal.c'

must be compiled as 'C'. With MSVC there is no problem as it uses

the filename extension (.c/.cpp) to determine how to compile, but

IDE's like DevC++ and VIDE don't do this with C++ projects, so 

instead of adding mappyal.c to your list of sourcefiles (like with 

MSVC) be sure you have mappyal.o by manually compiling with:



gcc mappy_A5.c -O2 -Wall -c -o mappy_A5.o



then adding mappy_A5.o to the compiler



Please report any bugs!





Function reference:

-------------------------------------------------

IMPORTANT: You must have initialised allegro first. See the demo.



Quick list:

MAPS

  MapLoad : load a map from file

  MapDecode : load a map from memory

  MapFreeMem : frees up all memory. must be called on exit

  MapMakeParallaxBitmap : make a parallax bitmap for the map

  MapChangeLayer : change map layer. mappy supports 8 different layers

  MapUpdateAnims: update map animations

  

DRAWING:

  MapDrawBG : draw the background tile from the current map layer

  MapDrawFG : draw foreground tiles (layer 1,2,3) from the current map layer

  MapDrawParallax: draw the parallax layer (call this first before BG and FG!)

  

BLOCKS/TILES:

  MapGetBlock/MapGetBlockInPixels: get a block/tile from a given location

  MapSetBlock/MapSetBlockInPixels: set a block at a given position to be a new block type

  

OTHER STUFF

  MapRestore: regenerate bitmaps (in case of loss through video switching in windows)

  MapLoadMAR: load a .mar file (cut-down map file)

  MapDrawRow: row by row drawing, needed for isometric

  MapGetXOffset/MapGetYOffset: handy for translating pixel to block co-ordinates



-------------------------------------------------



int MapLoad (char * mapname, int converttoalpha);



mapname: filename, e.g. "test.fmp"

converttoalpha: if 8bpp then 'magic pink' or index 0 will be converted to alpha

                if any other resolution then black or 'magic pink' will be converted to alpha

                

Uses allegro file functions so physfs is supported.



Default uses default allegro bitmaps, i.e. video. If the call fails you need to set new bitmaps to MEMORY then load



The array abmTiles is available and points to each tile graphic, 

eg. if you want to get at the third BITMAP, use abmTiles[2]. 



-------------------------------------------------

int MapDecode (unsigned char * mapmempt,int converttoalpha);



Same as MapLoad, but loads from an area of memory containing an FMP file.

(Useful if your maps are stored compressed, just uncompress to memory and

call MapDecode).



-------------------------------------------------

void MapRestore (void);



Restores the graphics to video bitmaps in hardware rendering.

Useful in Windows that loses video memory on app switching.

However A5 attempts to recover these for you so the function may not be that useful



-------------------------------------------------

void MapFreeMem (void);



When you've had enough of the map, this frees all the memory mappypb

has used.MapLoad and MapDecode call this so no need if loading a new map.



-------------------------------------------------

int MapLoadMAR (char * filename, int layer);

int MapDecodeMAR (unsigned char * marmemory, int layer);



Loads a .MAR file into a specified layer. Decode does it from memory, 

you can dealloc that memory afterwards. If you called MapGenerateYLookup,

call it again after this function. Returns -1 on error, 0 on success.



MAR files are like FMP map files but without the graphics, animation, etc.

i.e. they are simple boxed arrays storing tile numbers



-------------------------------------------------

void MapDrawBG (int mapxo, int mapyo, int mapx, int mapy,

	int mapw, int maph);



Draws the blocks referenced in bgoff. Will clip the map to the specified area.

Note: the normal clipping on the bitmap is ignored, so trying to draw off the

edges of a bitmap will crash your programme.



Draws to the current target bitmap, i.e. you need to set this, or just leave it alone

if using standard backbuffer



Refer to mapload for drawing of transparent areas (i.e. alpha channels)



int mapxo           offset, in pixels, from left edge of map, this is

                    the first visible column of pixels you are drawing

int mapyo           offset, in pixels, from top edge of map, this is

                    the first visible row of pixels you are drawing

int mapx            offset, in pixels, from left edge of bitmap

int mapy            offset, in pixels, from top edge of bitmap

int mapw            width of area you want to draw

int maph            height of area you want to draw



-------------------------------------------------

void MapDrawFG (int mapxo, int mapyo, int mapx, int mapy,

	int mapw, int maph, int mapfg);



Same as MapDrawBG, except:



int mapfg           The foreground layer you want to draw, 0, 1, or 2



-------------------------------------------------

void MapDrawRow (int mapxo, int mapyo, int mapx, int mapy,

	int mapw, int maph, int maprw, void (*cellcall) (int cx, int cy, int dx, int dy))



Same as MapDrawBG, except:



int maprw is the row to draw

cellcall is a callback function for each cell, pass NULL if you are doing your

own depth sorting, or using another system

see demo for an example of this in ISOMETRIC test



-------------------------------------------------

BITMAP * MapMakeParallaxBitmap (BITMAP * sourcebm);



Only on regular rectangular maps.

Pass a bitmap you would like to use for the parallax bitmap. 



You must use this function to make the bitmap you pass to MapDrawParallax.

The source bitmap MUST be a multiple of your block size (ie if you are

using 32*32 blocks, 128*128 and 96*64 are valid, but 100*100 is not).



-------------------------------------------------

void MapDrawParallax (BITMAP * parbm, int mapxo, int mapyo, int mapx, int mapy,

	int mapw, int maph);



This behaves like MapDrawBG etc, except the 'parbm' bitmap is created

with 'MapMakeParallaxBitmap' and this is tiled in the transparent

regions of the map. 



This is more efficient than drawing the whole screen as it only draws

in areas not obscured by higher layers, there is minimal overdraw

(pixels aren't overwritten by higher layers where possible).



-------------------------------------------------

int MapChangeLayer (int)



This changes to a different map layer, returns -1 if failed, or the new

layer number if success. See mpgame.c



-------------------------------------------------

int MapGetXOffset (int x, int y)

int MapGetYOffset (int x, int y)



These functions are handy for translating a pixel coordinate to block

coordinates, especially for non-rectangular blocks (see mousecrd.c).



-------------------------------------------------

BLKSTR * MapGetBlockInPixels (int x, int y)



Returns a BLKSTR pointer, useful for collision detection and examining a

blockstructure. This is more useful on non-rectangular maps as it is pixel

perfect.



-------------------------------------------------

BLKSTR * MapGetBlock (int x, int y);



Returns a BLKSTR pointer, useful for collision detection and examining a

blockstructure. Note: the x and y paramaters are the offset from the left

and top of the map in _BLOCKS_ NOT pixels. See mpgame.c for an example.



-------------------------------------------------

void MapSetBlockInPixels (int x, int y, int strvalue)



The x and y paramaters are the offset from the left and top of the map

in pixels. If strvalue is positive, the cell is set to that block structure.

If strvalue is negative the cell is set to that anim structure-1 (ie if

you want to put anim 3 in, strvalue would be -4).



-------------------------------------------------

void MapSetBlock (int x, int y, int strvalue);



The x and y paramaters are the offset from the left and top of the map

in _BLOCKS_ NOT pixels. See mpgame.c for an example. If strvalue is

positive, the cell is set to that block structure. If strvalue is

negative the cell is set to that anim structure-1 (ie if you want to

put anim 3 in, strvalue would be -4).

-------------------------------------------------

int MapGenerateYLookup (void);



This is now called for you on MapLoad and is not required, however for an explanation:



It will generate a lookup table that _may_ slightly speed up the functions

MapGetBlock and MapSetBlock, and allows you to use the maparraypt. If you

use this, you _must_ use MapChangeLayer if you want to swap between layers.

Another advantage is you can access block or anim offsets simply with:

maparraypt[y][x];

Where x is the offset from the left in _BLOCKS_, and y is the offset from

the top in _BLOCKS_. Note you can get the actual block structure with the

functions MapGetBlock and MapSetBlock.

The memory allocated is freed when either MapFreeMem is called, or another

map is loaded.



-------------------------------------------------

int MapGetBlockID (int blid, int usernum)



returns the number of the first block that matches 'blid' in the field 

specified with usernum (1 to 7, user1 to user7). If no match, returns -1







-------------------------------------------------

void MapInitAnims (void);



Call to reset the animated blocks to their defaults

Called on loading of a map for you



-------------------------------------------------

void MapUpdateAnims (void);



Animation control. Call from your game loop, moves blocks to next anim

Animations are set up in the map editor





Don't forget to look at the example source code, I've documented them.





Version Changes:

================



version 1.