map.h File Reference

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

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

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.
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 just use MEM_free(map) to release it.
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(..))

---

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

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
prepareMapDataColumnCB	internal
prepareMapDataRowCB	internal
hScrollTable	internal
vScrollTable	internal
getMetaTileCB	internal
getMetaTilemapRectCB	internal

---

Function Documentation

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 just use MEM_free(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
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.

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(..)

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(..)

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(..)

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(..)

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	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(..)

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

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

Parameters:

map	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(..)