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.