Main Page   Modules   Related Pages  

Map Functions

HEL's map-system supports large maps! It only updates the "dirty" rows and/or columns which really needs to get redrawn, instead of always redrawing the whole map! More...

Functions


Detailed Description

HEL's map-system supports large maps! It only updates the "dirty" rows and/or columns which really needs to get redrawn, instead of always redrawing the whole map!


Function Documentation

void hel_MapDeInit TMapScrollInfo *    pMapInfo
 

De-Initialize a map.

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

See also:
hel_MapInit()
   TMapScrollInfo MapInfo;

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

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

TPoint32 hel_MapGetPosition TMapScrollInfo *    pMapInfo
 

Get the currect map position in tiles.

Parameters:
pMapInfo : Pointer to an initialized TMapScrollInfo structure
Returns:
TPoint32.X : X in tiles
TPoint32.Y : Y in tiles
See also:
hel_MapGetPositionInPixel()
   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);

TPoint32 hel_MapGetPositionInPixel TMapScrollInfo *    pMapInfo
 

Get the currect map position in pixel.

Parameters:
pMapInfo : Pointer to an initialized TMapScrollInfo structure
Returns:
TPoint32.X : X in pixel
TPoint32.Y : Y in pixel
See also:
hel_MapGetPosition()
   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);

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, which is used by most of the hel mapfunctions. The hardwaremap-size is set to 32x32 tiles.

See also:
hel_MapInitEx(), hel_MapDeInit()
   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

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 on of the following defines, depending if it's 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

See also:
hel_MapDeInit(), hel_MapInit()
   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

u8 hel_MapIsBoundsCheckEnabled TMapScrollInfo *    pMapInfo
 

Check if a map uses boundschecking.

Parameters:
pMapInfo : Pointer to an initialized TMapScrollInfo structure
Returns:
1 : Map uses boundschecking
0 : Map does not use boundschecking
See also:
hel_MapSetBoundsCheck()
   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");

void hel_MapRedraw TMapScrollInfo *    pMapInfo
 

Redraw the map.

Parameters:
pMapInfo : Pointer to an initialized TMapScrollInfo structure
It's not required to call this function though. It's internally used when you set the position using hel_MapSetPosition(). However, it could be handy sometimes.

   TMapScrollInfo MapInfo;

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

   hel_MapRedraw(&MapInfo);

u8 hel_MapScrollBy TMapScrollInfo *    pMapInfo,
s32    DeltaX,
s32    DeltaY
 

Scroll the map.

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 true if it was able to scroll the background, otherwise it will return 0. It will always return true, if the the map does not use bounds-checking!

Furthermore you can also check on which axis it scrolled the background. Check bit1 against 1 to see if it was able to scroll on X-axis and check Bit2 agains 1 to see if it wa able to scroll on Y-axis.
This scrolls the map and redraws the "dirty" columns/rows. You can use negative values to scroll to the map to the left and/or up. If a callback-function using hel_MapSetCallbacks() was specified, it is called whenever a new column or row (block) has been drawn.

See also:
hel_MapSetCallbacks(), hel_MapSetBoundsCheck(), hel_MapIsBoundsCheckEnabled()
   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);

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/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 ends in tile-curruption when you do not make an own "is currect position still in map" check routine.

See also:
hel_MapInit()
   TMapScrollInfo MapInfo;

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

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's called whenever a new row has been drawn.
pOnLeftColumnChanged : Pointer to function. It's called whenever a new column has been drawn.
See also:
hel_MapScrollBy()
Note:
Hold the callbacks as small and fast as possible or it could happen that the map is updated very weird. Maybe just put flags in callback-function and progress the flags in mainloop then.
   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);

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,Y must be specified in tiles.

Note:
This function sets the left/top position of a map. For example, if you do 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.
See also:
hel_MapSetPositionInPixel()
   TMapScrollInfo MapInfo;

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

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,Y must be specified in pixels.

Note:
Please read hel_MapSetPosition() aswell
See also:
hel_MapSetPosition()
   TMapScrollInfo MapInfo;

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


Generated on Mon Jan 26 17:07:28 2004 by DoxyGen 1.3-rc1