.\"
.\" Copyright (c) 2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 October 21, 2007
.Dt RG_TILESET 3
.Os
.ds vT Agar-RG API Reference
.ds oS Agar-RG 1.0
.Sh NAME
.Nm RG_Tileset
.Nd agar-rg graphics package
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
#include <agar/rg.h>
.Ed
.Sh DESCRIPTION
The
.Nm
object manages a set of graphics resources of the following types:
.Bl -tag -width "Animations "
.It Tiles
Transparent graphic surfaces, generated from a set of instructions (or
.Sq features ) .
See
.Xr RG_Tile 3 .
.It Animations
Simple 2D animations also generated from a set of instructions.
See
.Xr RG_Anim 3 .
.It Textures
References to tiles with additional information related to texturing.
See
.Xr RG_Texture 3 .
.It Pixmaps
Transparent graphic surfaces used internally.
Pixmaps can be shared by multiple tiles.
See
.Xr RG_Pixmap 3 .
.It Sketches
Vector drawings used internally.
See
.Xr RG_Sketch 3 .
.El
.Pp
The
.Nm
structure also provides tiles, animations and textures with unique integer
names, such that items can be added or removed on the fly without invalidating
existing external references.
To take advantage of this feature, code should reference tiles and animations
using the
.Va tiletbl
and
.Va animtbl
members of the
.Nm
structure.
.Sh INHERITANCE HIERARCHY
.Xr AG_Object 3 ->
.Nm .
.Sh INITIALIZATION
.nr nS 1
.Ft "RG_Tileset *"
.Fn RG_TilesetNew "void *parent" "const char *name" "Uint flags"
.Pp
.nr nS 0
The
.Fn RG_TilesetNew
function allocates and initializes a new
.Nm
object and attaches it to
.Fa parent
if not NULL.
There are currently no
.Fa flags
defined.
.Sh ACCESSING RESOURCES
.nr nS 1
.Ft RG_Tile *
.Fn RGTILE "RG_Tileset *tileset" "Uint32 tileID"
.Pp
.Ft RG_Anim *
.Fn RGANIM "RG_Tileset *tileset" "Uint32 animID"
.Pp
.Ft int
.Fn RG_LookupTile "RG_Tileset *tileset" "Uint32 tileID" "RG_Tile **rTile"
.Pp
.Ft int
.Fn RG_LookupAnim "RG_Tileset *tileset" "Uint32 animID" "RG_Anim **rAnim"
.Pp
.Ft "RG_Tile *"
.Fn RG_TilesetFindTile "RG_Tileset *tileset" "const char *name"
.Pp
.Ft "RG_Sketch *"
.Fn RG_TilesetFindSketch "RG_Tileset *tileset" "const char *name"
.Pp
.Ft "RG_Pixmap *"
.Fn RG_TilesetFindPixmap "RG_Tileset *tileset" "const char *name"
.Pp
.Ft "RG_Tile *"
.Fn RG_TilesetResvTile "RG_Tileset *tileset" "const char *tileset_name" "const char *name"
.Pp
.Ft "RG_Pixmap *"
.Fn RG_TilesetResvPixmap "RG_Tileset *tileset" "const char *tileset_name" "const char *name"
.Pp
.nr nS 0
The
.Fn RGTILE
and
.Fn RGANIM
macros return the tile or animation of the given name.
If debugging is enabled, a non-existing resource will trigger a fatal
error.
.Pp
.Fn RG_LookupTile
and
.Fn RG_LookupAnim
search for a tile or animation with the given name.
If one is found, it is returned into
.Fa rTile
or
.Fa rAnim .
The function returns 0 on success and -1 if no such tile exists.
.Pp
.Fn RG_TilesetFindTile ,
.Fn RG_TilesetFindSketch
and
.Fn RG_TilesetFindPixmap
search for the given resource using the user-provided name string,
returning a pointer to the element on success and NULL on failure.
The
.Fn RG_TilesetResv*
variants use the VFS path name for the
.Nm
object itself.
.Sh SEE ALSO
.Xr RG_Tile 3 ,
.Xr RG_Anim 3 ,
.Xr RG_Pixmap 3 ,
.Xr RG_Sketch 3 ,
.Xr RG_Feature 3 ,
.Xr RG_Texture 3 ,
.Xr RG_Tileview 3
.Sh HISTORY
The
.Nm
object first appeared in Agar-RG 1.0.