Map System Functions
[Map System]

Data Structures

Defines

Functions


Define Documentation

#define HEL_SUBSYSTEM_MAP_REQUIREDMEMORY

Required memory for the Map System.

This define represents the amount of memory, specified in bytes, the Map System from HEL requires to manage its internal states. When you initialize the Map System, you must pass a buffer which equals the size of HEL_SUBSYSTEM_MAP_REQUIREDMEMORY.

See also:
hel_MapInit


Function Documentation

void hel_MapConvertPositionToTiles ( u32  BgNo,
sfp32  X,
sfp32  Y,
int *  pOutX,
int *  pOutY 
)

Get position in tiles.

The hel_MapConvertPositionToTiles can be used to get the position in tiles of a specific point on the screen.

Parameters:
[in] BgNo Background Number
[in] X X coordinate in fixed point format to get the tile position from.
[in] Y Y coordinate in fixed point format to get the tile position from.
[out] pOutX Pointer to an integer which receives the horizontal tile position.
[out] pOutY Pointer to an integer which receives the vertical tile position.
The following code demonstrates how to get the position in tiles from the screen coordinate X=114, Y=104 of the current map position:
    sfp32 MapPosX;  // Receives the x map position
    sfp32 MapPosY;  // Receives the y map position
    int TilePosX;   // Receives the x position in tiles
    int TilePosY;   // Receives the y position in tiles

    hel_MapGetPosition(BgNo, &MapPosX, &MapPosY);

    hel_MapConvertPositionToTiles
        (
            BgNo,                           // Background Number
            MapPosX + FIXED_FROMINT(114),   // X
            MapPosY + FIXED_FROMINT(104),   // Y
            &TilePosX,                      // pOutX
            &TilePosY                       // pOutY
        );

    // Output the positions
    HEL_DEBUG_MSG("Position in tiles on X: %d\n", TilePosX);
    HEL_DEBUG_MSG("Position in tiles on Y: %d\n", TilePosY);

See also:
hel_MapGetTilePtrAt, Fixed Point macros

void hel_MapCreate ( u32  BgNo,
u32  Width,
u32  Height,
const void *  pData,
u32  DataTypeSize,
u32  Flags 
)

Create a Map.

Parameters:
[in] BgNo Destination Background-Number of the Map or BG_VIRTUAL if you want to create a Virtual-Map. A VirtualMap in HEL is a data-layer only, such as a collision- or event-map. Only one VirtualMap can be created.
[in] Width Width of Map in Tiles
[in] Height Height of Map in Tiles
[in] pData Pointer to Map-Data
[in] DataTypeSize Size in bytes of one element in pData.
Specify sizeof(u16) for regular Map-Systems.
Specify sizeof(u8) for rotation/scaling Map-Systems.
If BgNo is BG_VIRTUAL, set DataTypeSize to the size one element of the Virtual-Map is using.
[in] Flags Flags to control the map behavior, see Map System Flags.
See also:
hel_MapCreateIndirect, hel_MapInit, hel_MapDelete

void hel_MapCreateIndirect ( const TMapCreateIndirectDesc pDesc  ) 

Create a Map.

The hel_MapCreateIndirect function creates a Map-System using the information stored in pDesc.

Parameters:
[in] pDesc Pointer to a TMapCreateIndirectDesc structure
Example:
void MapCreateIndirectExampleFunction()
{
    TMapCreateIndirectDesc  desc;

    desc.BgNo = 0; // use background 0

    // Set map size
    desc.Size.X = 100; // 100 tiles wide
    desc.Size.Y = 75;  // 75 tiles high
    desc.Size.Flags = MAP_FLAGS_SIZE0; // Use the smallest hardware map size

    // Pointer to actual map data
    desc.pData = ResData(RES_LEVEL1_MAP);
    desc.DataTypeSize = sizeof(u16); // size of one element in pData

    // Default flags, but we also want dynamic tile reloading
    desc.Flags = MAP_FLAGS_DEFAULT | MAP_FLAGS_DYNAMICTILERELOADING;

    // Set initial position
    desc.Position.X = FIXED_FROMINT(384); // move 384 pixels to the right
    desc.Position.Y = FIXED_FROMINT(40);  // move 40 pixels downwards

    // No custom made map drawing routines
    // If you want to use custom made drawers,
    // you must additionally include 
    // MAP_FLAGS_CUSTOMMAPDRAWER in desc.Flags
    desc.pColumnDrawer = NULL;
    desc.pRowDrawer = NULL;

    // Set the map boundaries (in pixels)
    desc.Bounds.Left = FIXED_FROMINT(0);
    desc.Bounds.Top = FIXED_FROMINT(0);
    desc.Bounds.Right = FIXED_FROMINT(desc.Size.X*8);
    desc.Bounds.Bottom = FIXED_FROMINT(desc.Size.Y*8);
    desc.Bounds.Flags = MAP_BOUNDS_DEFAULT;

    // Finally create the map
    hel_MapCreateIndirect(&desc);
}

Note:
Most of the time it's not enough to just create the map. Usually the map must be also set to a specific position, maybe even different bounds. You can of course do this with hel_MapCreate, then call hel_MapSetPosition and so on. However, this is not really efficient. The hel_MapCreateIndirect use the values stored in pDesc instead. It directly sets the map position to the coordinates in pDesc without calling further routines. This is about twice as fast compared to first creating the map and then call setposition!
See also:
hel_MapCreate, hel_MapInit, hel_MapDelete

void hel_MapDelete ( u32  BgNo  ) 

Delete a map.

Parameters:
[in] BgNo Background Number
See also:
hel_MapCreate

u32 hel_MapExists ( u32  BgNo  ) 

Check if a map exists.

The hel_MapExists checks if a Map-System for the background specified by BgNo exists. A Map-System exists in HEL, when it has been created by hel_MapCreate.

Parameters:
[in] BgNo Background Number
Returns:
Returns TRUE if a Map-System exists for the specified background, otherwise FALSE.

u32 hel_MapGetFlags ( u32  BgNo  ) 

Get Flags.

Parameters:
[in] BgNo Background Number
Returns:
Returns the Flags used by the map system specified by BgNo. Please see Map System Flags for a listing of available flags.
See also:
hel_MapSetFlags

void hel_MapGetPosition ( u32  BgNo,
sfp32 *  pX,
sfp32 *  pY 
)

Get the current Map position.

Parameters:
[in] BgNo Background Number
[out] pX Destination address to store the X position
[out] pY Destination address to store the Y position
Note:
The positions are in fixed point format. See (Fixed Point macros)

const void* hel_MapGetTilePtrAt ( u32  BgNo,
sfp32  X,
sfp32  Y 
)

Get a pointer to a tile.

Parameters:
[in] BgNo Background Number
[in] X X coordinate in fixed point format.
[in] Y Y coordinate in fixed point format.
Returns:
Returns a pointer to the tile at X and Y.
   u16 Tile = *(u16*)hel_MapGetTilePtrAt(0, FIXED_FROMINT(98), FIXED_FROMINT(64));

     // Extract the tile number. Lower 10 bits
     // represent the tile number. If you use
     // the dynamic tile reloading feature from
     // HEL Library, the lower 13 bits hold the
     // tile number. Keep that in mind!
     u32 TileNumber = Tile & 1023;

See also:
hel_MapConvertPositionToTiles, Fixed Point macros

void hel_MapInit ( void *  pBuffer  ) 

Initialize Map-System.

The hel_MapInit function must be called before using any Map-Function, otherwise the program behaviour is undefined.

Parameters:
[in] pBuffer Must point to a buffer of at least HEL_SUBSYSTEM_MAP_REQUIREDMEMORY allocated bytes. The buffer must be word-aligned and should be located in EWRAM.It must not be changed after initialization as long as the Map System is running!
// Allocate memory for Map-System
u8 ATTR_EWRAM ATTR_ALIGNED(4) g_MapSystemBuffer[HEL_SUBSYSTEM_MAP_REQUIREDMEMORY];

int main(void)
{
    // Initialize Map-System
    hel_MapInit((void*)g_MapSystemBuffer);

    // ...
}

See also:
hel_MapQuit

void hel_MapJumpTo ( u32  BgNo,
u32  JumpToFlag 
)

Jump to a border of the Map.

The hel_MapJumpTo jumps to a border of the map. It can jump to the left or right as well as to the top or bottom. You can combine the JumpToFlag's in order to move the map in more than one direction with only a single call to hel_MapJumpTo.

Parameters:
[in] BgNo Background Number
[in] JumpToFlag Flag(s) that specify the destination map position. JumpToFlag can be a combination or the following predefined values:
  • MAP_JUMPTO_LEFT - Jumps to the very left of the map
  • MAP_JUMPTO_RIGHT - Jumps to the very right of the map, the last column of the screen (column 30) will display the last column of the map.
  • MAP_JUMPTO_TOP - Jumps to the very top of the map
  • MAP_JUMPTO_BOTTOM - Jumps to the very bottom of the map, the last row of the screen (column 20) will display the last row of the map.
Remarks:
You cannot jump to the left and right or to the top and bottom simultaneously. Therefore has MAP_JUMPTO_LEFT higher priority than MAP_JUMPTO_RIGHT and MAP_JUMPTO_TOP has higher priority than MAP_JUMPTO_BOTTOM. When you pass MAP_JUMPTO_LEFT and MAP_JUMPTO_RIGHT, only MAP_JUMPTO_LEFT will be executed.
  // Jumps to the very right bottom position
  hel_MapJumpTo(0, MAP_JUMPTO_RIGHT | MAP_JUMPTO_BOTTOM);

See also:
hel_MapSetPosition

void hel_MapQuit ( void   ) 

Uninitialize Map-System.

The hel_MapQuit function uninitializes the Map-System.

Any existing map, which has been earlier created by a call to hel_MapCreate, will be deleted. hel_MapQuit uses hel_MapDelete to delete existing maps.

Once the Map-System is uninitialized, you can use the work buffer passed to hel_MapInit for other purposes again.

See also:
hel_MapInit

void hel_MapRedraw ( u32  BgNo  ) 

Redraw the Map.

The hel_MapRedraw function redraws the entire visible map region. Thereby it is quite slower than hel_MapScroll which only updates the edges.

Parameters:
[in] BgNo Background Number
Note:
hel_MapRedraw should not be called frequently, as in a game-loop, because it redraws the entire visible map region which is most of the time not necessary and obviously slow. If you want to scroll the map, use hel_MapScroll instead.
See also:
hel_MapScroll

u32 hel_MapScroll ( u32  BgNo,
sfp32  DeltaX,
sfp32  DeltaY 
)

Scroll the Map.

The hel_MapScroll function scrolls the map by the specified DeltaX and DeltaY values.

Parameters:
[in] BgNo Background Number
[in] DeltaX Scroll-Ratio for horizontal movement in fixed point format.
[in] DeltaY Scroll-Ratio for vertical movement in fixed point format.
Returns:
Returns FALSE when the Map scrolled not at all, otherwise it is a combination these bits:
  • BIT0 - Scrolled at least one pixel on X axis
  • BIT1 - Scrolled at least one pixel on Y axis
Note:
Be aware that you must pass fixed point values to hel_MapScroll. If you just pass 2 for example, it will probably do nothing. If you want the map to scroll by two pixels, pass FIXED_FROMINT(2) instead. To compose the delta values, use FIXED_FROMINT or FIXED_FROMFLOAT macros.
    // Scroll map 1.5 pixels to the right and 2 pixels up.
    hel_MapScroll(0, FIXED_FROMFLOAT(1.5f), FIXED_FROMINT(-2));

See also:
Fixed Point macros

void hel_MapSetBounds ( u32  BgNo,
sfp32  Left,
sfp32  Top,
sfp32  Right,
sfp32  Bottom,
u32  Flags 
)

Set bounds.

The hel_MapSetBounds function can be used to limit the map to a given area. The map will not scroll beyond the specified bounds.

Parameters:
[in] BgNo Background Number
[in] Left Position left side of bounds in fixed point format. See (Fixed Point macros)
[in] Top Position of top side of bounds in fixed point format. See (Fixed Point macros)
[in] Right Position of right side of bounds in fixed point format. See (Fixed Point macros)
[in] Bottom Position of bottom side of bounds in fixed point format. See (Fixed Point macros)
[in] Flags The Flags are used to control the bounds checking. It holds information about what side has to be clipped to the bounds. The following values can be used and combined:
  • MAP_BOUNDS_LEFT : Check against left side
  • MAP_BOUNDS_TOP : Check against top side
  • MAP_BOUNDS_RIGHT : Check against right side
  • MAP_BOUNDS_BOTTOM : Check against bottom side
If you want to disable bounds checking, which results that the map gets wrapped when it moves out of its size, you can specify:

To restore the default behavior, use:


Note:
If specified anything else than MAP_BOUNDS_NONE, the following rules apply: The Left value must be smaller than the Right one and the Top value must be smaller than Bottom. Also, the area created by the specified bounds, must be at least 240 pixels wide and 160 pixels high, which equals the display dimension.

void hel_MapSetFlags ( u32  BgNo,
u32  Flags 
)

Set Flags.

The hel_MapSetFlags function can be used to set the Map-System behavior flags.

For example, it can be used to prevent the map system to scroll into specific direction and to automatically update the map-position in Vram.

Parameters:
[in] BgNo Background Number
[in] Flags Flags to control the map behavior, see Map System Flags.
Note:
Several flags must not be changed after Map-System creation. You must keep these flags and pass them to hel_MapSetFlags again. Please see the example below, for a safe version:
    // Get flags and remove the ones that
    // allow the map-system to scroll up- and downwards
    u32 Flags = hel_MapGetFlags(0) & ~(MAP_FLAGS_TOP | MAP_FLAGS_BOTTOM);

    // Set the modified flags again
    hel_MapSetFlags(0,Flags);

See also:
hel_MapGetFlags, hel_MapScroll, hel_MapTransmit

void hel_MapSetPosition ( u32  BgNo,
sfp32  X,
sfp32  Y 
)

Set position.

The hel_MapSetPosition function sets the map to the specified X and Y position.

Parameters:
[in] BgNo Background Number
[in] X Destination X position in fixed point format.
[in] Y Destination Y position in fixed point format.
Note:
hel_MapSetPosition keeps track of the Scroll-Flags (hel_MapSetFlags), which can lead into trouble if you are not aware of it.
For example: The Scroll-Flags prevent the map from being able to move to the right, the current map X position equals 10 and you want to set it to 100, it needs to move to the right. But because it is not allowed to, since the necessary Scroll-Flags are missing, it does not change its X position. Please see the following example, which shows how to workaround this behaviour.

    u32 Flags;

    // Save Scroll-Flags
    Flags   = hel_MapGetFlags(0);

    // Update Scroll-Flags from map to make sure it is able to move to all directions
    hel_MapSetFlags(0, Flags | MAP_FLAGS_LEFT | MAP_FLAGS_RIGHT | 
            MAP_FLAGS_UP | MAP_FLAGS_DOWN);

    // Set the new position
    hel_MapSetPosition(0, FIXED_FROMINT(1234), FIXED_FROMINT(5678));

    // Restore Scroll-Flags again
    hel_MapSetFlags(0, Flags);

See also:
hel_MapSetPosition, Fixed Point macros

void hel_MapTransmit ( void   ) 

Transmit attributes to hardware.

The hel_MapTransmit function must be called during VBL to transmits the map position to hardware.


Generated on Fri Aug 17 12:12:38 2007 for HEL Library by  doxygen 1.5.3