MAP(3)

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

SEE ALSO
AG_Object(3), MAP_Object(3), MAP_View(3), SG_Intro(3)

HISTORY
The MAP class first appeared in Agar 1.0.