CDXMappy - documentation (Release 10B)

CDXMappy handles .FMP files (including FMP1.0) created by Mappy Win32 Editor, (C) Robin Burrows. The current official Mappy Homepage is: http://www.tilemap.co.uk with mirrors at http://www.geocities.com/SiliconValley/Vista/7336/robmpy.htm and (if all else fails) http://surf.to/mappy

CDXMappy is based on original sources from Robin Burrows and was ported and modified for CDX by Ioannis Karagiorgos. Bug fixes and documentation updates provided by the CDX community.

Tutorial

---

Here is a little code tutorial on how to use CDXMappy in your projects:

Initializing

First of all you have to create your CDXMappy object:

    CDXMappy * Map = new CDXMappy;

Next, load your map:

    if( Map->LoadMap( Screen ,"Map.fmp" , 0 , 0 , 320 , 200 )  == -1 )
        CDXError( Screen , "Could not load map.fmp!" );

If the map loading fails, it returns -1. LoadMap wants to have a Screen object, the filename of the map, the x/y coordinates of the map on the screen (where drawing will start, upper-left hand corner -- usually 0,0) and the visible map dimensions.


If your screen is in 8bit (256 colour) resolution set the palette:

    Map->SetPalette( Screen );

If you want a parallax surface, call

   if( Map->CreateParallax( "parallax.bmp" ) == FALSE )
        CDXError( Screen , "Could not load parallax bitmap parallax.bmp" );

caution: the parallax surface size must be a multiple of the map block size!!!

If your Map is using animated tiles then you have to initialize the animations:

    Map->MapInitAnims( );

Thats all there has to be done for initialization.

Drawing

Here are the functions needed to draw the map.

If you are using animated tiles, first call Map->MapUpdateAnims( ); This should be done at a set rate, so usually called from your game logic loop.

    Then, call Map->MapMoveTo( x , y ) to move the map at the desired pixel position.

If you are using a parallax surface, you have to draw it first, for example:

    if( Map->DrawParallax( CDXSurface * Surface ) == -1 )
        Map->RestoreParallax();

    Map->MapDrawBG( CDXSurface * Surface ) draws the background layer or
    Map->MapDrawBGT( CDXSurface * Surface ) draws the background layer transparently (using the color key)

    Map->MapDrawFG( CDXSurface * Surface , int GFXLayer ) draws one of the three foreground layers (0-2)
    If you have more than one foreground gfx layer, you must call DrawFG for every foreground layer.

Each of the draw functions returns -1 if an error occured. If this happens you must call Map->MapRestore(). Example:

    if( Map->MapDrawBG( Screen->GetBack())  == -1 )
        Map->MapRestore();

Lastly, when you shutdown your application, use SAFEDELETE( Map ) to free all memory used by the CDXMappy class


---

Map Methods

---

int LoadMap (CDXScreen * Screen , char * Filename , int x , int y , int Width , int Height);
int DecodeMap (CDXScreen * Screen , unsigned char * mempt , int x , int y , int Width , int Height);

LoadMap loads the map with the path and name specified into memory so it can be used. or DecodeMap loads the map from a memory area pointed to by mempt so it can be used.

Returns 0 on success, -1 on failure.

x/y are the output position of the map on the screen.
Width/Height are the visible size of the map on the screen
CAUTION:  loading a high/true colour map on an 8bit screen takes a painfully long time.

int SetPalette (CDXScreen * Screen);

Sets the screen palette to those in the currently loaded map. Only use this on 8bit screens.

void MapInitAnims (void);

Resets animations to their initial values.


void MapUpdateAnims (void);

Increments animations. Generally used once during an update loop before drawing.


int MapDrawBG (CDXSurface* s);

MapDrawBG draws the background layer without transparency, so it will completely overwrite the specified area.

Returns -1 if an error occurs; if this happens, a call to MapRestore() must be made.

int MapDrawBGT (CDXSurface* s);

MapDrawBGT draws the background layer with transparency. Any block whose tile is tile 0, or pixels of the transparent color in all blocks, won't be drawn. Important: you must check the transparency bit in the block properties for blocks that have transparency, see Mappy FAQ (weblink) for more details.

Returns -1 if an error occurs; if this happens, a call to MapRestore() must be made.


int MapDrawFG (CDXSurfacent *s, int gfxlayer);

MapDrawFG is the same as MapDrawBG except it draws foreground layers. You specify 0, 1 or 2 as the last paramater for the FG layer you wish to draw. Do not use for isometric maps, use MapDrawRow instead.

int MapDrawRow (CDXSurfacent *s, int row, func cellcall);

Use for isometric maps, an example:
for (i=0;i<(numberofrowstodraw);i++)
{ Map->MapDrawRow(Screen->GetBack(), i, NULL); }
numberofrowstodraw should be bigger than the number of visible rows on screen


void MapRestore (void);

If you lose your surfaces (for example if someone alt-tabs), you can call this function to restore them.

int MapChangeLayer (int layernumber);

This changes to a different map layer, returns -1 if failed, or the new layer number (0 to 7) if successful.

This refers to map layers, if you are unsure about this, please consult the Mappy FAQ (weblink) for more details.


int MapGetTile (int x, int y);

Returns the content of a block at position x,y. The x and y paramaters are the offset from the left and top of the map in BLOCKS, NOT pixels.

If return value is positive, the cell contains a block. If return value is negative, the cell contains animation.

BLKSTR * MapGetBlock (int x, int y);

Returns a BLKSTR pointer, useful for collision detection and examining a block structure. Note: the x and y paramaters are the offset from the left and top of the map in BLOCKS, NOT pixels. Example:

BLKSTR * myblkstr;
myblkstr = MapGetBlock (xoffinblocks, yoffinblocks);
if (myblkstr->tl) { top left collision is set for this block }


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. 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 DrawParallax( CDXSurface * Surface );

This call draws the parallax surface on the selected surface.
Return value = -1 if an error occured. Then you should call RestoreParallax.

BOOL CreateParallax( void );

This call creates and load a parallax surface from bitmap file Filename
Return value = TRUE if it was successful, otherwise FALSE.
caution: the parallax surface size must be a multiple of the map block size!!!

 
BOOL RestoreParallax( char * Filename );

This call restores a parallax surface if an error occured while drawing it.

The following functions are obsolete, the colourkey is taken from the FMP file, and you can get values with MapGetVal (MPY_valuetoget). See cdxmappy.h for a full list.
There are also more functions which I don't have time to document, see cdxmappy.h

SetColorKey( DWORD ColorKey );

Sets the colorkey for transparent blits. 
In 8 bit modes, it takes the index  of the transparent color, in all other modes you must supply
the RGB-Value of the color, it is internally converted to the correct color!
Example: Map->SetColorKey( RGB( 255 , 0 , 0 ) ); // set colorkey to pure red in all modes <> 8 bit

WORD GetMapBPP( void );

This call returns the color depth of the current map.

WORD GetMapWidth( void );

This call returns the width of the map in pixels.

WORD GetMapHeight( void );

This call returns the height of the map in pixels.

WORD GetMapWidthInBlocks( void );

This call returns the width of the map in blocks.

WORD GetMapHeightInBlocks( void );

This call returns the height of the map in blocks.

WORD GetMapBlockWidth( void );

Thie call returns the width of one map block, in pixels.

WORD GetMapBlockHeight( void );

Thie call returns the height of one map block, in pixels.

void MapMoveTo( int x , int y );

This call moves the map output to offset x,y. It takes into account invalid coordinates, and will modify them accordingly so as to not scroll off the edges of the map and cause a crash.

int MapGetXPosition( void );

This call returns the current X offset of the map, in pixels, from the upper-left hand corner.

int MapGetYPosition( void );

This call returns the current Y offset of the map, in pixels, from the upper-left hand corner.




---

If you have problems with CDXMappy, please e-mail me
If you have problems/questions about how Mappy works or the Mappy editor, please contact the author Robin Burrows or look at the Mappy Homepage. The current official Mappy Homepage is: http://www.geocities.com/SiliconValley/Vista/7336/robmpy.htm, with mirrors at http://www.rbsite.freeserve.co.uk/robmpy.htm and (if all else fails) http://surf.to/mappy

August 1999 , Ioannis Karagiorgos

November 2001 , Robin Burrows