.\"
.\" 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 November 17, 2007
.Dt RG_ANIM 3
.Os
.ds vT Agar-RG API Reference
.ds oS Agar-RG 1.0
.Sh NAME
.Nm RG_Anim
.Nd agar-rg animation element
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
#include <agar/rg.h>
.Ed
.Sh DESCRIPTION
The
.Nm
structure describes an animation (an array of frames) generated from a
set of instructions.
.Pp
Note: Unless you need to import animations, generate or manipulate animation
instructions or frames programmatically, you do not need to use this interface.
Libraries such as
.Xr MAP 3
use this interface to display animations.
.Pp
Public members of the
.Nm
structure include:
.Pp
.Bd -literal
typedef struct rg_anim {
	char name[RG_ANIMATION_NAME_MAX]; /* User identifier */
	Uint32 main_id;			  /* Default ID mapping */
	Uint flags;
#define RG_ANIM_SRCALPHA	0x01
#define RG_ANIM_SRCCOLORKEY	0x02
	Uint w, h;			/* Sprite geometry */
	RG_AnimFrame *frames;		/* Generated frames */
	Uint	     nframes;
	Uint	     gframe;		   /* Current frame (global) */
	SLIST_HEAD(,rg_anim_variant) vars; /* Transformed variants */
};

typedef struct rg_anim_frame {
	Uint name;
	Uint delay;
	AG_Surface *su;
#ifdef HAVE_OPENGL
	Uint texture;
#endif
} RG_AnimFrame;

typedef struct rg_anim_variant {
	RG_TransformChain transforms;		/* Applied transforms */
	RG_Anim *anim;				/* Transformed anim */
} RG_AnimVariant;
.Ed
.Sh INTERFACE
.nr nS 1
.Ft "RG_Anim *"
.Fn RG_AnimInit "RG_Anim *anim" "RG_Tileset *ts" "const char *name" "Uint flags"
.Pp
.Ft "void"
.Fn RG_AnimDestroy "RG_Anim *anim"
.Pp
.Ft void
.Fn RG_AnimScale "RG_Anim *anim" "Uint width" "Uint height"
.Pp
.Ft void
.Fn RG_AnimGenerate "RG_Anim *anim"
.Pp
.Ft "Uint"
.Fn RG_AnimInsertInsn "RG_Anim *anim" "enum rg_anim_insn_type type"
.Pp
.Ft "void"
.Fn RG_AnimRemoveInsn "RG_Anim *anim" "Uint insn"
.Pp
.Ft "Uint"
.Fn RG_AnimInsertFrame "RG_Anim *anim" "AG_Surface *s"
.Pp
.Ft "void"
.Fn RG_AnimRemoveFrame "RG_Anim *anim" "Uint frame"
.Pp
.Ft "RG_AnimFrame *"
.Fn RG_ANIM_FRAME "RG_Anim *anim" "Uint frame"
.Pp
.nr nS 0
The
.Fn RG_AnimInit
initializes a
.Nm
attached to the given
.Xr RG_Tileset 3 ,
identified by
.Fa name .
The
.Fa flags
may include:
.Pp
.Bl -tag -compact -width "RG_ANIM_SRCCOLORKEY "
.It RG_ANIM_SRCCOLORKEY
Use colorkeying with the animation surfaces.
.It RG_ANIM_SRCALPHA
Use alpha blending with the animation surfaces.
.El
.Pp
.Fn RG_AnimScale
resizes the canvas of the animation to
.Fa width
by
.Fa height
pixels.
.Pp
The
.Fn RG_AnimGenerate
function compiles the array of frames for the animation, from the
instructions.
.Pp
The
.Fn RG_AnimInsertInsn
function inserts a new instruction, and returns its new index.
.Fa type
is one of:
.Bd -literal
	enum rg_anim_insn_type {
		RG_ANIM_TILE,		/* Replace/blend with prev tile */
		RG_ANIM_DISPX,		/* Pixmap translation */
		RG_ANIM_ROTPX		/* Pixmap rotation */
	};
.Ed
.Pp
The
.Fn RG_AnimRemoveInsn
removes the given instruction.
.Pp
.Fn RG_AnimInsertFrame
manually inserts a frame containing the given surface into the animation
array, and returns the index of the frame.
.Fn RG_AnimRemoveFrame
removes the frame of the given index.
These functions are useful to manipulate the frames directly when the
animation is imported from some external source, for example.
.Pp
The
.Fn RG_ANIM_FRAME
macro returns a pointer to the
.Ft RG_AnimFrame
structure for the given frame index.
.Sh SEE ALSO
.Xr RG_Tileset 3 ,
.Xr RG_Tile 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.