#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.
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.
[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. |
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);
void hel_MapCreate | ( | u32 | BgNo, | |
u32 | Width, | |||
u32 | Height, | |||
const void * | pData, | |||
u32 | DataTypeSize, | |||
u32 | Flags | |||
) |
Create a Map.
[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. |
void hel_MapCreateIndirect | ( | const TMapCreateIndirectDesc * | pDesc | ) |
Create a Map.
The hel_MapCreateIndirect function creates a Map-System using the information stored in pDesc
.
[in] | pDesc | Pointer to a TMapCreateIndirectDesc structure |
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); }
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!void hel_MapDelete | ( | u32 | BgNo | ) |
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.
[in] | BgNo | Background Number |
TRUE
if a Map-System exists for the specified background, otherwise FALSE
. u32 hel_MapGetFlags | ( | u32 | BgNo | ) |
Get Flags.
[in] | BgNo | Background Number |
BgNo
. Please see Map System Flags for a listing of available flags.void hel_MapGetPosition | ( | u32 | BgNo, | |
sfp32 * | pX, | |||
sfp32 * | pY | |||
) |
Get the current Map position.
[in] | BgNo | Background Number |
[out] | pX | Destination address to store the X position |
[out] | pY | Destination address to store the Y position |
const void* hel_MapGetTilePtrAt | ( | u32 | BgNo, | |
sfp32 | X, | |||
sfp32 | Y | |||
) |
Get a pointer to a tile.
[in] | BgNo | Background Number |
[in] | X | X coordinate in fixed point format. |
[in] | Y | Y coordinate in fixed point format. |
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;
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.
[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); // ... }
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.
[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
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);
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.
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.
[in] | BgNo | Background Number |
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.
[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. |
FALSE
when the Map scrolled not at all, otherwise it is a combination these bits: // Scroll map 1.5 pixels to the right and 2 pixels up. hel_MapScroll(0, FIXED_FROMFLOAT(1.5f), FIXED_FROMINT(-2));
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.
[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_NONE
To restore the default behavior, use:
MAP_BOUNDS_DEFAULT
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.
[in] | BgNo | Background Number |
[in] | Flags | Flags to control the map behavior, see Map System Flags. |
// 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);
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.
[in] | BgNo | Background Number |
[in] | X | Destination X position in fixed point format. |
[in] | Y | Destination Y position in fixed point format. |
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);
void hel_MapTransmit | ( | void | ) |
Transmit attributes to hardware.
The hel_MapTransmit function must be called during VBL to transmits the map position to hardware.