sgdk: map.h File Reference

sgdk

- Main Page
- Related Pages
- Classes
- Files

- File List
- File Members

Classes | Typedefs | Functions
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.

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

All Classes Files Functions Variables Typedefs Enumerations Enumerator Defines