// HEL Library \\

 
Main Page | Modules | Related Pages

Map Functions

Description. More...

Functions


Detailed Description

Description.

HEL's map-system implementation supports large maps. The map-drawer only updates "dirty" rows and columns, instead of always redrawing the whole map!

It's quite faster than the original HAM functions. It uses DMA transfers to update the map and LookUpTables whereever possible to gain maximum speed. I actually spend a lot of time to getting it that fast!

It supports parallax scrolling, using fixed point math.

It supports Virtual Maps. A Virtual Map in HEL's sense is an invisble datalayer only, which can be used as a collision or event map. There is no limit in creating Virtual Map's!

It also has an implementation for callback notify's.

All these useful things making HEL's map-system implementation to a very powerful tool!


Function Documentation

void hel_MapBatchScrollBy TMapScrollInfo *  pMapInfos,
s32  DeltaX,
s32  DeltaY,
int  Count
 

Scroll multiply layers at the same time.

Parameters:
pMapInfos Pointer to an array of initialized TMapScrollInfo structures
DeltaX Amount in pixel to scroll on x axis
DeltaY Amount in pixel to scroll on y axis
Count The count of TMapScrollInfo structures/elements in pMapInfo
Please read hel_MapScrollBy.

See also:
hel_MapScrollBy

u8 hel_MapBatchScrollByEx TMapScrollInfo *  pMapInfos,
s32  DeltaX,
s32  DeltaY,
int  Count,
u32  PrimaryLayer
 

Scroll multiply layers at the same time.

Parameters:
pMapInfos Pointer to an array of initialized TMapScrollInfo structures
DeltaX Amount in pixel to scroll on x axis
DeltaY Amount in pixel to scroll on y axis
Count The count of TMapScrollInfo elements, passed by pMapInfo
PrimaryLayer : PrimaryLayer represents the layer-index, in pMapInfos, where you want to get the return value from. The return value is the same as in hel_MapScrollBy.
Please read hel_MapScrollBy.

See also:
hel_MapBatchScrollBy, hel_MapScrollBy

void hel_MapDeInit TMapScrollInfo *  pMapInfo  ) 
 

De-Initialize a map.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
This function deinitializes a TMapScrollInfo structure as well as the mapset in VRAM.

   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map); 

   // Lots of stuff here ...
   
   hel_MapDeInit(&MapInfo);

See also:
hel_MapInit

void* hel_MapGetCustomData TMapScrollInfo *  pMapInfo  ) 
 

Get custom data.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
Returns:
Returns the custom data what you previously assigned to the structure specified by pMapInfo
See also:
hel_MapSetCustomData

TPoint32 hel_MapGetPosition TMapScrollInfo *  pMapInfo  ) 
 

Get the currect map position in tiles.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
Returns:
Returns the X/Y Coordinates in tiles, as TPoint32 structure
   TMapScrollInfo MapInfo;
   TPoint32 Pt={0,0};
   
   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   hel_MapSetPosition(&MapInfo, 512, 0);
   
   Pt = hel_MapGetPosition(&MapInfo);
   ham_VBAText("Position in tiles X: %d \n", Pt.X);
   ham_VBAText("Position in tiles Y: %d \n", Pt.Y);

See also:
hel_MapGetPositionInPixel

TPoint32 hel_MapGetPositionInPixel TMapScrollInfo *  pMapInfo  ) 
 

Get the currect map position in pixel.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
Returns:
Returns the X/Y Coordinates in pixels, as TPoint32 structure
   TMapScrollInfo MapInfo;
   TPoint32 Pt={0,0};

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   hel_MapSetPosition(&MapInfo, 512, 0);

   Pt = hel_MapGetPositionInPixel(&MapInfo);
   ham_VBAText("Position in pixels X: %d \n", Pt.X);
   ham_VBAText("Position in pixels Y: %d \n", Pt.Y);

See also:
hel_MapGetPosition

TPoint32 hel_MapGetPositionInPixelFrom TMapScrollInfo *  pMapInfo,
u32  TileX,
u32  TileY
 

Get position of a tile.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
TileX The horizontal index of the tile you want to get the position from
TileY The vertical index of the tile you want to get the position from
Returns:
Returns the position in pixels of the tile in question.
Note:
Imagine the following scenario. You have a layer whose (top/left) position is xy=0,0. Now you want to get the position of the tile at xy=2,3. The result value will be xy=16,24 (2*8,3*8). Now lets say you scroll the layer by 2 pixels on x and 6 pixels on y. The result value in this case is xy=14,18 (2*8-2,3*8-6). This only works with tiles whose tilesize is 8*8 pixels.
   TPoint32 Pt = hel_MapGetPositionInPixelFrom(&g_MapInfo, 2, 3);

See also:
hel_MapGetPosition, hel_MapGetPositionInPixel

u16 hel_MapGetTileAt TMapScrollInfo *  pMapInfo,
u32  ScreenX,
u32  ScreenY
 

Get a maptile.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
ScreenX The horizontal screen-coordinate in pixels from where you want the tile from
ScreenY The vertical screen-coordinate in pixels from where you want the tile from
Returns:
Returns the maptile requested.
Note:
This function does not support VirtualMaps, use hel_MapGetTilePtrAt for VirtualMaps!
   u16 Index = hel_MapGetTileAt(&g_MapInfo, 98, 56);

See also:
hel_MapGetTilePtrAt

void* hel_MapGetTilePtrAt TMapScrollInfo *  pMapInfo,
u32  ScreenX,
u32  ScreenY
 

Get a pointer to a maptile.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
ScreenX The horizontal screen-coordinate in pixels from where you want the tile from
ScreenY The vertical screen-coordinate in pixels from where you want the tile from
Returns:
Returns a pointer to the requested maptile.
Note:
You have to cast the pointer to the correct type. For normal maps it is usually an u16, while rotation maps use u8 instead. If you specified a VirtualMap, cast it to the type your VirtualMap items use.
   u16 Index = *(u16*)hel_MapGetTilePtrAt(&g_MapInfo, 98, 56);

See also:
hel_MapGetTileAt

TMapScrollInfo hel_MapInit u8  BgNo,
u16  TilesX,
u16  TilesY,
u8  Rotation,
void *  pMapData
 

Initialize a map.

Parameters:
BgNo Background you want to initialize the map for
TilesX Map-width in tiles
TilesY Map-height in tiles
Rotation Indicates the map as a rotation map. Can be TRUE or FALSE
pMapData Pointer to mapdata
Returns:
A TMapScrollInfo structure. This structure is used by almost every hel_*Map* function.
This function returns an initialized TMapScrollInfo structure, what is used by most of the hel mapfunctions. The hardwaremap-size is set to 32x32 tiles.

   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0,            // BgNo
                         4096,         // Map-width in tiles
                         32,           // Map-height in tiles
                         FALSE,        // Is it a rotation map?
                         Layer0_Map);  // Pointer to map-data

See also:
hel_MapInitEx, hel_MapDeInit

TMapScrollInfo hel_MapInitEx u8  BgNo,
u16  TilesX,
u16  TilesY,
u8  Rotation,
u8  MapSize,
void *  pMapData
 

Initialize a map.

Parameters:
BgNo Background you want to initialize the map for
TilesX Map-width in tiles
TilesY Map-height in tiles
Rotation Indicates the map as a rotation map. Can be TRUE or FALSE
MapSize Specifies the hardware-mapsize. See below for a list with available values.
pMapData Pointer to mapdata
Returns:
A TMapScrollInfo structure. This structure is used by almost every hel_*Map* function.
This function returns an initialized TMapScrollInfo structure, which is used by most of the hel mapfunctions. The hardwaremap is set to 32x32 tiles.

The parameter MapSize can be one of the following defines, depending on, whether it is a rotation map or not...

For a normal map use one of these:

  • MAP_SIZE_32X32
  • MAP_SIZE_64X32
  • MAP_SIZE_32X64
  • MAP_SIZE_64X64

For a rotation map use one of these:

  • MAP_SIZE_ROT_16X16
  • MAP_SIZE_ROT_32X32
  • MAP_SIZE_ROT_64X64
  • MAP_SIZE_ROT_128X128

   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInitEx(0,                   // BgNo
                           4096,                // Map-width in tiles
                           512,                 // Map-height in tiles
                           TRUE,                // Is it a rotation map?
                           MAP_SIZE_ROT_64X64,  // hardware mapsize
                           Layer0_Map);         // Pointer to map-data

See also:
hel_MapDeInit, hel_MapInit

TMapScrollInfo hel_MapInitVirtual u16  TilesX,
u16  TilesY,
u8  DataTypeSize,
void *  pMapData
 

Initialize a VirtualMap.

Parameters:
TilesX Map-width in tiles
TilesY Map-height in tiles
DataTypeSize The size of one element in bytes, from the map specified by pMapData
pMapData Pointer to mapdata
Returns:
A TMapScrollInfo structure. This structure is used by almost every hel_Map* function.
Note:
A VirtualMap in HEL, can be any kind of mapdata, but it cannot be displayed! VirtualMap's can be used for collision or event layers for example and must also have a 'tilesize' of 8x8 pixels!
   TMapScrollInfo MapInfo;
   
   MapInfo = hel_MapInitVirtual(128, 32, sizeof(u16), (void*)sample_Collision);

See also:
hel_MapInit, hel_MapInitEx, hel_MapGetTilePtrAt

u8 hel_MapIsBoundsCheckEnabled TMapScrollInfo *  pMapInfo  ) 
 

Check if a map uses boundschecking.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
Returns:
Returns TRUE when boundschecking is enabled, otherwise FALSE.
   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   if (hel_MapIsBoundsCheckEnabled(&MapInfo))
      ham_VBAText("Boundscheck enabled\n");
   else
      ham_VBAText("Boundscheck disabled\n");

See also:
hel_MapSetBoundsCheck

u8 hel_MapIsParallaxEnabled TMapScrollInfo *  pMapInfo  ) 
 

Check if parallax is enabled.

Parameters:
pMapInfo Pointer to an array of initialized TMapScrollInfo structures
Returns:
Returns true when parallax support is enabled in pMapInfo, otherwise false.
See also:
hel_MapSetParallax

void hel_MapRedraw TMapScrollInfo *  pMapInfo  ) 
 

Redraw the map.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
It's not neccessary to call this function directly, though. It's internally used when you set the position using hel_MapSetPosition and hel_MapSetPositionInPixel. However, it could be handy sometimes, so here it is.

Note:
This function is (extremely) slower than hel_MapScrollBy
   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);

   hel_MapRedraw(&MapInfo);

See also:
hel_MapScrollBy

u8 hel_MapScrollBy TMapScrollInfo *  pMapInfo,
s32  DeltaX,
s32  DeltaY
 

Scroll the map.

The hel_MapScrollBy function scrolls the map and redraws the "dirty" columns and/or rows only. It does not redraw the whole screen for some performance reasons. You can use negative values to scroll to the map to the left and/or up. If a callback-function was specified with hel_MapSetCallbacks, it triggers the assigned callback-function whenever a new column or row has been drawn.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
DeltaX Amount in pixel to scroll on x axis
DeltaY Amount in pixel to scroll on y axis
Returns:
Returns a value between 1 and 3 if it was able to scroll the background, otherwise it returns 0. It always return TRUE, if the the map does not use bounds-checking! The return-value can be used to check on which axis it was able to scroll. Check Bit1 to see if it was able to scroll on X-axis and check Bit2 for Y-axis.
Note:
When parallax-support is enabled, the Delta parameters become multiplied by the parallax ratios!
   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   
   while(GameLoopActive)
   {
      if(NewFrame)
      {
         if(UserPressedRight)
         {
            // Scroll one pixel to the right
            u8 ScrollResult = hel_MapScrollBy(&MapInfo, 1, 0);
            
            // check if it was able to scroll on x-axis
            if(ScrollResult & 1)
            {
               Print("Scrolled on X");
            }
            
            // check if it was able to scroll on y-axis
            if(ScrollResult & 2)
            {
               Print("Scrolled on Y");
            }
         }
      }
   }
   
   hel_MapDeInit(&MapInfo);

See also:
hel_MapSetCallbacks, hel_MapSetBoundsCheck, hel_MapIsBoundsCheckEnabled, hel_MapSetParallaxRatio, hel_MapSetParallax

u8 hel_MapScrollTo TMapScrollInfo *  pMapInfo,
TMapCamScrollInfo *  pMapCamInfo,
u32  SpeedX,
u32  SpeedY
 

Scroll map to a specific position automatically.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
pMapCamInfo Pointer to a TMapCamScrollInfo structure.
SpeedX Scroll speed on horizontal axis
SpeedY Scroll speed on vertical axis
Returns:
  • MAP_CAM_NEXTKEYPOINT
    Changed to the next keypoint.
  • MAP_CAM_LASTKEYREACHED
    Scrolling is done. The map has reached the position specified by the very last keypoint in pMapCamInfo

Furthermore it returns the value from hel_MapScrollBy(), when it was able to scroll. (when none of the above apply)
See also:
hel_MapScrollBy
Note:
This function scrolls the map automatically to the specified key-points specified in pMapCamInfo. The function should be called once per frame.
   TMapScrollInfo g_MapInfo;

   // X/Y Tile-Position (Camera Key-Points)
   const TPoint16 CamKeyPoints[5]=
   {
    //  X, Y Tile Positions
      {10, 5},
      {28, 5},
      {15, 5},
      {15,25},
      { 0, 0}
   };

   // Map Cinema Scrolling Information
   TMapCamScrollInfo g_MapCamInfo =
   {
      &CamKeyPoints,  // Pointer to keypoints
      5,              // Count of keypoints
      0               // Start keypoint
   };

   // Init map
   g_MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);

   u8 CamScrollWorking=1;

   while(1)
   {
      if(NewFrame)
      {

         if(CamScrollWorking)
         {
            CamScrollWorking = hel_MapScrollTo(&g_MapInfo, &g_MapCamInfo, 1, 1);
         }
         NewFrame=FALSE;
      }
   }

void hel_MapSetBoundsCheck TMapScrollInfo *  pMapInfo,
u8  Value
 

Setup map bounds checking.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
Value Boundschecking on/off. Must be 1 or 0
This function enables or disables boundschecking for the structure specified by pMapInfo. This means, you cannot scroll out of the map. It stops scrolling when it hits the "edges" of the map. It's turned on by default when you use hel_MapInit.

Disabling this feature means you can scroll out of the map and this could end up in tile-curruption when you do not code an own "is currect position still in map" routine.

   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   // Turn off boundscheck
   hel_MapIsBoundsCheckEnabled(&MapInfo, FALSE);

See also:
hel_MapInit

void hel_MapSetCallbacks TMapScrollInfo *  pMapInfo,
PMapNotifyFunc  pOnTopRowChanged,
PMapNotifyFunc  pOnLeftColumnChanged
 

Setup map notify-callbacks.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
pOnTopRowChanged Pointer to function. It will be triggered when a new row has been drawn.
pOnLeftColumnChanged Pointer to function. It will be triggered when a new column has been drawn.
Note:
Hold the callbacks as small and fast as possible! Otherwise it can happen that the map is updated very weirdly. Think about just setting flags in a callback-function and progress the flags in mainloop, or similar.
   TMapScrollInfo MapInfo;

   // Is called whenever a new row has been drawn
   void MapOnTopRowChanged(TMapScrollInfo *pMapInfo, u32 X, u32 Y) 
   {                                                             
      ham_DrawText(1, 1, "MapOnTopRowChanged    ");            
      ham_DrawText(1, 2, "X: %d     ", X);                       
      ham_DrawText(1, 3, "Y: %d     ", Y);                     
   }                                                           

   // Init map
   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);

   // Set callback function(s)
   hel_MapSetCallbacks(&MapInfo, (PMapNotifyFunc)MapOnTopRowChanged, NULL);
   
   // Scroll the map by 32 pixels in X and Y
   hel_MapScrollBy(&MapInfo, 32, 32);

See also:
hel_MapScrollBy

void hel_MapSetCustomData TMapScrollInfo *  pMapInfo,
void *  pCustomData
 

Set custom data.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
pCustomData Pointer to the data you want to have assigned to this structure
Note:
With this function you can assign a pointer, to a custom structure of your gameengine for example, to the map-structure specified by pMapInfo. This is handy when you work with the HEL map-callback function and need to access additional information.
See also:
hel_MapGetCustomData, hel_MapSetCallbacks

void hel_MapSetParallax TMapScrollInfo *  pMapInfo,
u8  Value
 

Enable or disable Parallax support.

Parameters:
pMapInfo Pointer to an array of initialized TMapScrollInfo structures
Value Parallax support
Use this function to enable or disable parallaxing for the TMapScrollInfo structure specified by pMapInfo. Specify TRUE to enable, or FALSE to disable.

See also:
hel_MapScrollBy, hel_MapIsParallaxEnabled

void hel_MapSetParallaxRatio TMapScrollInfo *  pMapInfo,
FIXED  RatioX,
FIXED  RatioY
 

Set parallax X/Y ratio.

Parameters:
pMapInfo Pointer to an array of initialized TMapScrollInfo structures
RatioX The parallax-ratio on x-axis
RatioY The parallax-ratio on y-axis
Use this function to set the parallax ratio for the structure specified by pMapInfo. This function automatically enables parallax-support for the specified structure.

   hel_MapSetParallaxRatio(&MapInfo,
                           PARALLAX_FLOAT_TO_RATIO(0.7),  // Ratio on X
                           PARALLAX_FLOAT_TO_RATIO(0.8)); // Ratio on Y

See also:
hel_MapScrollBy, hel_MapIsParallaxEnabled

void hel_MapSetPosition TMapScrollInfo *  pMapInfo,
u32  X,
u32  Y
 

Set map position in tiles.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
X X map-position in tiles
Y Y map-position in tiles
This sets the map to the specified position. X and Y must be specified in tiles.

Note:
This function sets the left/top position of a map. For example, if you call #hel_MapSetPosition(&MapInfo, 2, 5), then is the first column on screen the 2nd column from map and the first row on screen is the 5th row from map.
   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   hel_MapSetPosition(&MapInfo, 512, 0);

See also:
hel_MapSetPositionInPixel

void hel_MapSetPositionInPixel TMapScrollInfo *  pMapInfo,
u32  X,
u32  Y
 

Set map position in pixels.

Parameters:
pMapInfo Pointer to an initialized TMapScrollInfo structure
X X map-position in pixels
Y Y map-position in pixels
This sets the map to the specified position. X and Y must be specified in pixels.

   TMapScrollInfo MapInfo;

   MapInfo = hel_MapInit(0, 4096, 32, FALSE, Layer0_Map);
   hel_MapSetPositionInPixel(&MapInfo, 512, 0);

See also:
hel_MapSetPosition


Generated on Mon Feb 28 19:20:39 2005 by DoxyGen 1.3.9.1