NAME

MAP — agar feature-based tile map

SYNOPSIS

#include <agar/core.h>
#include <agar/map.h>

DESCRIPTION

The Agar MAP library implements a map of fixed-size tiles which allow different elements to be stacked. Built-in element types include:

MAP_ITEM_TILE: Graphical surface (rendered RG_Tile(3) element).
MAP_ITEM_IMG: Graphical surface (image file reference).
MAP_ITEM_LINK: Reference to some other node, possibly on another map.

In addition to the built-in (static) elements, dynamic map objects (instances of MAP_Object(3) or subclasses thereof) may be attached to the MAP and in the case of graphical elements, rendered either in 2D or 3D.

GRAPHICAL TILES

For 3D purposes, graphical tiles define a height h and a z coordinate (where z = 0 is referred to as the standard plane of the map).

Graphical tiles also define two 2D displacements (in pixels) of the image from the tile's origin, a centering offset typically set by the developer as part of the design (although usable programmatically to produce effects), and the motion offset for real-time animation purposes. If the map is drawn to a different scale than 1:1, the centering offset will be scaled to the new tile size, but the motion offset will not.

A chain of graphical transformations can be applied per tile. The rendering engine (i.e., the MAP_View(3) widget) will maintain a cache of transformed tiles in graphics memory for best efficiency.

INHERITANCE HIERARCHY

AG_Object(3) -> MAP.

INITIALIZATION

MAP *
MAP_New(void *parent, const char *name);

int
MAP_AllocNodes(MAP *map, Uint w, Uint h);

void
MAP_FreeNodes(MAP *map);

void
MAP_SetZoom(MAP *map, int camera, Uint factor);

MAP_New() allocates, initializes and attaches a new map.

MAP_AllocNodes() allocates w x h nodes, assuming that no node is currently allocated. MAP_AllocNodes() returns 0 on success or -1 on failure. The maximum allowable geometry is defined by MAP_WIDTH_MAX and MAP_HEIGHT_MAX.

The MAP_FreeNodes() routine releases the nodes allocated by map. The map must be locked.

MAP_Resize() reallocates the nodes arrays, initializing the new nodes and freeing the excess ones. MAP_Resize() returns 0 on sucess or -1 on failure.

MAP_SetZoom() sets the zoom factor for a given map view. Actors are displayed to this scale.

NODE INITIALIZATION

void
MAP_NodeInit(MAP_Node *node);

void
MAP_NodeDestroy(MAP *map, MAP_Node *node);

int
MAP_NodeLoad(MAP *map, AG_DataSource *ds, MAP_Node *node);

void
MAP_NodeSave(const MAP *map, AG_DataSource *ds, const MAP_Node *node);

MAP_NodeInit() initializes the node structure. MAP_NodeDestroy() frees all resources allocated by node.

MAP_NodeLoad() loads the contents of node (presumed initialized and empty), from data source ds. MAP_NodeSave() saves the contents of node to ds. Both functions are called implicitely by the load() and save() operations of MAP.

MAP ITEMS

void
MAP_ItemInit(MAP_Item *mi);

void
MAP_ItemDestroy(MAP *map, MAP_Item *mi);

MAP_ItemInit() initializes the mi structure. MAP_ItemDestroy() frees all resources allocated for mi.

NODE MANIPULATIONS

void
MAP_MoveItem(MAP *mapSrc, MAP_Node *nodeSrc, MAP_Item *miSrc, MAP *mapDst, MAP_Node *nodeDst, int layerDst);

MAP_Item *
MAP_CopyItem(const MAP_Item *miSrc, MAP *mapDst, MAP_Node *nodeDst, int layerDst);

void
MAP_DelItem(MAP *map, MAP_Node *node, MAP_Item *mi);

MAP_Item *
MAP_TileNew(MAP *map, MAP_Node *node, RG_Tileset *ts, Uint tileID);

MAP_Link *
MAP_LinkNew(MAP *map, MAP_Node *nodeDst, const char *targetMap, int x, int y, Uint8 dir);

MAP_MoveItem() moves item miSrc from nodeSrc (of mapSrc) over to nodeDst (of mapDst).

MAP_CopyItem() inserts a copy of miSrc on top of nodeDst. The copy is associated with layerDst (or -1 = the source layer).

MAP_DelItem() deletes item mi from node.

MAP_TileNew() creates a reference to the RG_Tile(3) element identified by tileID in the given RG_Tileset(3).

MAP_LinkNew() Creates a link to the node x, y of targetMap. This is the pathname of the destination map (as returned by AG_ObjectCopyName()).

HISTORY

The MAP class first appeared in Agar 1.0.