map.h File Reference

MAP (large background map) management unit. More...

#include "vdp.h"
#include "vdp_tile.h"
#include "pal.h"

Include dependency graph for map.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	MapDefinition
	MapDefinition structure which contains data for large level background. It's optimized to encode large map using 128x128 block chunk (block chunk are organized in metatile). More...
struct	Map
	Map structure containing information for large background/plane update based on MapDefinition. More...

Typedefs
typedef struct Map	Map
	Map structure containing information for large background/plane update based on MapDefinition.
typedef void	MapDataPatchCallback(Map *map, u16 *buf, u16 x, u16 y, MapUpdateType updateType, u16 size)
	Map data patch callback. It's used to modify/patch map data (for destructible blocks for instance) before sending it to VRAM.

Enumerations
enum	MapUpdateType { ROW_UPDATE , COLUMN_UPDATE }
	Map data update type. More...

Functions
Map *	MAP_create (const MapDefinition *mapDef, VDPPlane plane, u16 baseTile)
	Create and return a Map structure required to use all MAP_xxx functions from a given MapDefinition. When you're done with the map you shall use MAP_release(map) to release it.
void	MAP_release (Map *map)
	Release the map and its resources (same as MEM_free(map))
void	MAP_scrollTo (Map *map, u32 x, u32 y)
	Scroll map to specified position. The fonction takes care of updating the VDP tilemap which will be transfered by DMA queue then VDP background scrolling is automatically set on VBlank (into the SYS_doVBlankProcess() tasks). WARNING: first MAP_scrollTo(..) call will do a full plane update, for a 64x32 sized plane this represents 4KB of data. That means you can't initialize 2 MAPs in the same frame (limited to 7.2 KB of data per frame) so take care of calling SYS_doVBlankProcess() in between.
void	MAP_scrollToEx (Map *map, u32 x, u32 y, bool forceRedraw)
	Exactly as MAP_scrollTo(..) except we can force complete map drawing.
u16	MAP_getMetaTile (Map *map, u16 x, u16 y)
	Returns given metatile attribute (a metatile is a block of 2x2 tiles = 16x16 pixels)
u16	MAP_getTile (Map *map, u16 x, u16 y)
	Returns given tile attribute (note than map->baseTile isn't added to the result)
void	MAP_getMetaTilemapRect (Map *map, u16 x, u16 y, u16 w, u16 h, u16 *dest)
	Returns metatiles attribute for the specified region (a metatile is a block of 2x2 tiles = 16x16 pixels)
void	MAP_getTilemapRect (Map *map, u16 x, u16 y, u16 w, u16 h, bool column, u16 *dest)
	Returns tiles attribute data for the specified region (map->baseTile is used as base tiles attribute, see MAP_create(..))
void	MAP_setDataPatchCallback (Map *map, MapDataPatchCallback *CB)
	Set the callback function to patch tilemap data. Note that you need to set The method will be called when a new tilemap row / column is ready to be send to the VDP. You can use this callback to modify the tilemap data before sending it to VRAM. It can be useful, for instance, to implement destructibles blocks.
void	MAP_overridePlaneSize (Map *map, u16 w, u16 h)
	Override the system (VDP) plane size for this map (should be called after MAP_create(..)) Useful if you have VDP plane size set to 64x64 but you want to use 64x32 for a plane so you can use spare VRAM for something else.

Detailed Description

MAP (large background map) management unit.

Author

Stephane Dallongeville

Date

11/2020

This unit provides methods to manipulate / scroll large background MAP:

• Create / release MAP object
  
• MAP decoding functions
  
• Large MAP scrolling engine
  
  Using MAP resource you can encode large image as a MapDefinition structure which will be used to handle large background scrolling. The MapDefinition structure is optimized to encode large map efficiently (space wise), here's the encoding format:
  
• background map is encoded as a grid of 128x128 pixels blocks
  
• duplicated 128x128 blocks are optimized (keep only 1 reference)
  
• each 128x128 blocks is encoded internally as a 8x8 grid of metatile
  
• a metatile is a 16x16 pixels block (2x2 tiles block)
  
• each duplicated / flipped metatile are optimized.
  
  Knowing that you can draw your level background to optimize its space usage by trying to optimize
  the number of unique 128x128 pixels block.

Typedef Documentation

Map

typedef struct Map Map

Map structure containing information for large background/plane update based on MapDefinition.

Parameters

w	map width in block (128x128 pixels block)
h	map height in block (128x128 pixels block)
metaTiles	internal - unpacked data of MapDefinition.metaTiles
blocks	internal - unpacked data of MapDefinition.blocks
blockIndexes	internal - unpacked data of MapDefinition.blockIndexes
blockRowOffsets	internal - direct access of MapDefinition.blockRowOffsets
plane	VDP plane where MAP is draw
baseTile	Base tile attributes used to provide base tile index offset and base palette index (see TILE_ATTR_FULL() macro)
posX	current view position X set using MAP_scrollTo(..) method
posY	current view position Y set using MAP_scrollTo(..) method
wMask	internal
hMask	internal
planeWidthMask	internal
planeHeightMask	internal
lastXT	internal
lastYT	internal
hScrollTable	internal
vScrollTable	internal
prepareMapDataColumnCB	internal
prepareMapDataRowCB	internal
patchMapDataColumnCB	internal
patchMapDataRowCB	internal
getMetaTileCB	internal
getMetaTilemapRectCB	internal

MapDataPatchCallback

typedef void MapDataPatchCallback(Map *map, u16 *buf, u16 x, u16 y, MapUpdateType updateType, u16 size)

Map data patch callback.
It's used to modify/patch map data (for destructible blocks for instance) before sending it to VRAM.

Parameters

map	source Map structure containing map information.
buf	buffer containing the tilemap data to patch
x	tile X start update position
y	tile Y start update position
updateType	map data update type: ROW_UPDATE (tilemap row update) COLUMN_UPDATE (tilemap column update)
size	size of the buffer (tilemap width or height depending we are on a row or column update type)

Enumeration Type Documentation

MapUpdateType

enum MapUpdateType

Map data update type.

Enumerator
COLUMN_UPDATE	tilemap row update tilemap column update

Function Documentation

MAP_create()

Map * MAP_create	(	const MapDefinition *	mapDef,
		VDPPlane	plane,
		u16	baseTile )

Create and return a Map structure required to use all MAP_xxx functions from a given MapDefinition.
When you're done with the map you shall use MAP_release(map) to release it.

Parameters

mapDef	MapDefinition structure containing background/plane data.
plane	Plane where we want to draw the Map (for MAP_scrollTo(..) method). Accepted values are: BG_A BG_B If you want to use the map for collision or special behavior (using the MAP_getTile(..) method) then you can just let this parameter to 0.
baseTile	Used to provide base tile index and base palette index (see TILE_ATTR_FULL() macro). Note that you can also use it to force HIGH priority but in that case your map should only contains LOW priority tiles otherwise the HIGH priority tiles will be set in LOW priority instead (mutually exclusive).

Returns

initialized Map structure or NULL if there is not enough memory to allocate data for given MapDefinition.

MAP_getMetaTile()

u16 MAP_getMetaTile	(	Map *	map,
		u16	x,
		u16	y )

Returns given metatile attribute (a metatile is a block of 2x2 tiles = 16x16 pixels)

Parameters

map	source Map structure containing map information.
x	metatile X position
y	metatile Y position

Returns

metatile attribute:

• b15: priority override
  
• b14-b13: free, can be used to encode collision info ?
  
• b12: combined vflip
  
• b11: combined hflip
  
• b10-b0: metatile index
  

See also

MAP_create(..)

MAP_getTile(..)

MAP_getMetaTilemapRect(..)

MAP_getMetaTilemapRect()

void MAP_getMetaTilemapRect	(	Map *	map,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		u16 *	dest )

Returns metatiles attribute for the specified region (a metatile is a block of 2x2 tiles = 16x16 pixels)

Parameters

map	source Map structure containing map information.
x	Region X start position (in metatile).
y	Region Y start position (in metatile).
w	Region Width (in metatile).
h	Region Heigh (in metatile).
dest	destination pointer receiving metatiles attribute data

Returns

metatiles attribute:

• b15: priority override
  
• b14-b13: free, can be used to encode collision info ?
  
• b12: combined vflip
  
• b11: combined hflip
  
• b10-b0: metatile index
  

See also

MAP_create(..)

MAP_getTilemapRect(..)

MAP_getTile()

u16 MAP_getTile	(	Map *	map,
		u16	x,
		u16	y )

Returns given tile attribute (note than map->baseTile isn't added to the result)

Parameters

map	source Map structure containing map information.
x	tile X position
y	tile Y position

Returns

tile attribute:

• b15: priority
  
• b14-b13: palette
  
• b12: vflip
  
• b11: hflip
  
• b10-b0: tile index

See also

MAP_create(..)

MAP_getMetaTile(..)

MAP_getTilemapRect(..)

MAP_getTilemapRect()

void MAP_getTilemapRect	(	Map *	map,
		u16	x,
		u16	y,
		u16	w,
		u16	h,
		bool	column,
		u16 *	dest )

Returns tiles attribute data for the specified region (map->baseTile is used as base tiles attribute, see MAP_create(..))

Parameters

map	source Map structure containing map information.
x	Region X start position (in metatile)
y	Region Y start position (in metatile)
w	Region Width (in metatile)
h	Region Heigh (in metatile)
column	if set to TRUE then tilemap data is stored by column order [Y,X] instead of row order [X,Y].
dest	destination pointer receiving tiles attribute data

Returns

tiles attribute:

• b15: priority
  
• b14-b13: palette
  
• b12: vflip
  
• b11: hflip
  
• b10-b0: tile index

See also

MAP_create(..)

MAP_getTile(..)

MAP_getMetaTilemapRect(..)

MAP_overridePlaneSize()

void MAP_overridePlaneSize	(	Map *	map,
		u16	w,
		u16	h )

Override the system (VDP) plane size for this map (should be called after MAP_create(..))
Useful if you have VDP plane size set to 64x64 but you want to use 64x32 for a plane so you can use spare VRAM for something else.

Parameters

map	source Map structure we want to override VDP tilemap size for.
w	tilemap width (32, 64 or 128)
h	tilemap height (32, 64 or 128)

MAP_release()

void MAP_release

(

Map *

map

)

Release the map and its resources (same as MEM_free(map))

Parameters

map	the Map structure to release

MAP_scrollTo()

void MAP_scrollTo	(	Map *	map,
		u32	x,
		u32	y )

Scroll map to specified position.
The fonction takes care of updating the VDP tilemap which will be transfered by DMA queue then VDP background scrolling is automatically set on VBlank (into the SYS_doVBlankProcess() tasks).
WARNING: first MAP_scrollTo(..) call will do a full plane update, for a 64x32 sized plane this represents 4KB of data.
That means you can't initialize 2 MAPs in the same frame (limited to 7.2 KB of data per frame) so take care of calling SYS_doVBlankProcess() in between.

Parameters

map	source Map structure containing map information.
x	view position X we want to scroll on
y	view position Y we want to scroll on

See also

MAP_create(..)

MAP_scrollToEx()

void MAP_scrollToEx	(	Map *	map,
		u32	x,
		u32	y,
		bool	forceRedraw )

Exactly as MAP_scrollTo(..) except we can force complete map drawing.

Parameters

map	source Map structure containing map information.
x	view position X we want to scroll on
y	view position Y we want to scroll on
forceRedraw	Set to TRUE to force a complete map redraw (take more time)

See also

MAP_scrollTo(..)

Here is the call graph for this function:

MAP_setDataPatchCallback()

void MAP_setDataPatchCallback	(	Map *	map,
		MapDataPatchCallback *	CB )

Set the callback function to patch tilemap data.
Note that you need to set
The method will be called when a new tilemap row / column is ready to be send to the VDP.
You can use this callback to modify the tilemap data before sending it to VRAM.
It can be useful, for instance, to implement destructibles blocks.

Parameters

map	source Map structure we want to set the patch data callback for.
CB	Callback to use to patch the new tilemap data (set to NULL by default = no callback). See declaration of MapDataPatchCallback to get information about the callback parameters.