.\" .\" Copyright (c) 2001-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt MAP 3 .Os Agar 1.7 .Sh NAME .Nm MAP .Nd agar feature-based tile map .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION The Agar .Nm library implements a map of fixed-size tiles which allow different elements to be stacked. Built-in element types include: .Pp .Bl -tag -width "MAP_ITEM_TILE " -compact .It MAP_ITEM_TILE Graphical surface (rendered .Xr RG_Tile 3 element). .It MAP_ITEM_IMG Graphical surface (image file reference). .It MAP_ITEM_LINK Reference to some other node, possibly on another map. .El .Pp In addition to the built-in (static) elements, dynamic map objects (instances of .Xr MAP_Object 3 or subclasses thereof) may be attached to the .Nm and in the case of graphical elements, rendered either in 2D or 3D. .Sh GRAPHICAL TILES For 3D purposes, graphical tiles define a height .Va h and a .Va z coordinate (where z = 0 is referred to as the .Em standard plane of the map). .Pp Graphical tiles also define two 2D displacements (in pixels) of the image from the tile's origin, a .Em centering offset typically set by the developer as part of the design (although usable programmatically to produce effects), and the .Em 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. .Pp A chain of graphical transformations can be applied per tile. The rendering engine (i.e., the .Xr MAP_View 3 widget) will maintain a cache of transformed tiles in graphics memory for best efficiency. .Sh INHERITANCE HIERARCHY .Xr AG_Object 3 -> .Nm . .Sh INITIALIZATION .nr nS 1 .Ft "MAP *" .Fn MAP_New "void *parent" "const char *name" .Pp .Ft int .Fn MAP_AllocNodes "MAP *map" "Uint w" "Uint h" .Pp .Ft void .Fn MAP_FreeNodes "MAP *map" .Pp .Ft void .Fn MAP_SetZoom "MAP *map" "int camera" "Uint factor" .Pp .nr nS 0 .Fn MAP_New allocates, initializes and attaches a new map. .Pp .Fn MAP_AllocNodes allocates .Fa w x .Fa h nodes, assuming that no node is currently allocated. .Fn MAP_AllocNodes returns 0 on success or -1 on failure. The maximum allowable geometry is defined by .Dv MAP_WIDTH_MAX and .Dv MAP_HEIGHT_MAX . .Pp The .Fn MAP_FreeNodes routine releases the nodes allocated by .Fa map . The map must be locked. .Pp .Fn MAP_Resize reallocates the nodes arrays, initializing the new nodes and freeing the excess ones. .Fn MAP_Resize returns 0 on sucess or -1 on failure. .Pp .Fn MAP_SetZoom sets the zoom factor for a given map view. Actors are displayed to this scale. .Sh NODE INITIALIZATION .nr nS 1 .Ft void .Fn MAP_NodeInit "MAP_Node *node" .Pp .Ft void .Fn MAP_NodeDestroy "MAP *map" "MAP_Node *node" .Pp .Ft int .Fn MAP_NodeLoad "MAP *map" "AG_DataSource *ds" "MAP_Node *node" .Pp .Ft void .Fn MAP_NodeSave "const MAP *map" "AG_DataSource *ds" "const MAP_Node *node" .Pp .nr nS 0 .Fn MAP_NodeInit initializes the .Fa node structure. .Fn MAP_NodeDestroy frees all resources allocated by .Fa node . .Pp .Fn MAP_NodeLoad loads the contents of .Fa node (presumed initialized and empty), from data source .Fa ds . .Fn MAP_NodeSave saves the contents of .Fa node to .Fa ds . Both functions are called implicitely by the .Fn load and .Fn save operations of .Nm . .Sh MAP ITEMS .nr nS 1 .Ft void .Fn MAP_ItemInit "MAP_Item *mi" .Pp .Ft void .Fn MAP_ItemDestroy "MAP *map" "MAP_Item *mi" .Pp .nr nS 0 .Fn MAP_ItemInit initializes the .Fa mi structure. .Fn MAP_ItemDestroy frees all resources allocated for .Fa mi . .Sh NODE MANIPULATIONS .nr nS 1 .Ft void .Fn MAP_MoveItem "MAP *mapSrc" "MAP_Node *nodeSrc" "MAP_Item *miSrc" "MAP *mapDst" "MAP_Node *nodeDst" "int layerDst" .Pp .Ft "MAP_Item *" .Fn MAP_CopyItem "const MAP_Item *miSrc" "MAP *mapDst" "MAP_Node *nodeDst" "int layerDst" .Pp .Ft void .Fn MAP_DelItem "MAP *map" "MAP_Node *node" "MAP_Item *mi" .Pp .Ft "MAP_Item *" .Fn MAP_TileNew "MAP *map" "MAP_Node *node" "RG_Tileset *ts" "Uint tileID" .Pp .Ft "MAP_Link *" .Fn MAP_LinkNew "MAP *map" "MAP_Node *nodeDst" "const char *targetMap" "int x" "int y" "Uint8 dir" .Pp .nr nS 0 .Fn MAP_MoveItem moves item .Fa miSrc from .Fa nodeSrc (of .Fa mapSrc ) over to .Fa nodeDst (of .Fa mapDst ) . .Pp .Fn MAP_CopyItem inserts a copy of .Fa miSrc on top of .Fa nodeDst . The copy is associated with .Fa layerDst (or -1 = the source layer). .Pp .Fn MAP_DelItem deletes item .Fa mi from .Fa node . .Pp .Fn MAP_TileNew creates a reference to the .Xr RG_Tile 3 element identified by .Fa tileID in the given .Xr RG_Tileset 3 . .Pp .Fn MAP_LinkNew Creates a link to the node .Fa x , .Fa y of .Fa targetMap . This is the pathname of the destination map (as returned by .Fn AG_ObjectCopyName ) . .Sh SEE ALSO .Xr AG_Object 3 , .Xr MAP_Object 3 , .Xr MAP_View 3 , .Xr SG_Intro 3 .Sh HISTORY The .Nm class first appeared in Agar 1.0.