CDXMappy - documentation (Release 10B) |
This is the documentation for the CDXMappy class, designed for CDX3.0 and later (cdx.sourceforge.net). 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. TutorialHere is a little code tutorial on how to use CDXMappy in your projects: InitializingFirst 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 ) 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 ) 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. DrawingHere 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->MapDrawBG( CDXSurface * Surface ) draws the
background layer or Map->MapDrawFG( CDXSurface * Surface , int GFXLayer )
draws one of the three foreground layers (0-2) 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
) Lastly, when you shutdown your application, use SAFEDELETE( Map ) to free
all memory used by the CDXMappy class Map Methodsint LoadMap (CDXScreen * Screen , char * Filename , 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.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.
Increments animations. Generally used once during an update loop before drawing.
MapDrawBG draws the background layer without transparency, so it will completely overwrite the specified area.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.
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:
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.
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.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:
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.BOOL CreateParallax( void ); This call creates and load a parallax surface from bitmap file Filename 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.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 August 1999 , Ioannis Karagiorgos November 2001 , Robin Burrows
|