Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>

DESCRIPTION

The AG_Anim structure describes an animation in uncompressed packed-pixel or indexed format.

INITIALIZATION

AG_Anim * AG_AnimNew (enum ag_anim_type type, Uint w, Uint h, const AG_PixelFormat *fmt, Uint flags)

AG_Anim * AG_AnimEmpty (void)

AG_Anim * AG_AnimStdRGB (Uint w, Uint h)

AG_Anim * AG_AnimStdRGBA (Uint w, Uint h)

AG_Anim * AG_AnimIndexed (Uint w, Uint h, int bitsPerPixel, Uint flags)

AG_Anim * AG_AnimRGB (Uint w, Uint h, int bitsPerPixel, Uint flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask)

AG_Anim * AG_AnimRGBA (Uint w, Uint h, int bitsPerPixel, Uint flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)

AG_Anim * AG_AnimFromPNGs (const char *path)

AG_Anim * AG_AnimFromJPEGs (const char *path)

AG_Anim * AG_AnimDup (AG_Anim *src)

void AG_AnimSetOrigFPS (AG_Anim *anim, double fps)

int AG_AnimSetPalette (AG_Anim *anim, AG_Color *colors, Uint offs, Uint count)

int AG_AnimResize (AG_Anim *anim, Uint w, Uint h)

void AG_AnimFree (AG_Anim *anim)

The AG_AnimNew() function allocates and initializes a new AG_Anim of the specified dimensions w, h (given in pixels). fmt is a pointer to a AG_PixelFormat structure describing the way pixels are to be encoded in memory (see PIXEL FORMATS section below). The pixel data is left uninitialized. Acceptable values for type include:

AG_ANIM_PACKED	Packed-pixel format (e.g., RGBA)
AG_ANIM_INDEXED	Color-index format (per-animation palette)

Acceptable flags include:

AG_SRCCOLORKEY	Enable colorkeying. In blit operations, this option inhibits the copy of all pixels matching the source animation's colorkey setting. AG_AnimSetColorKey() controls this flag.
AG_SRCALPHA	Enable alpha blending. In blit operations, this option enables blending of pixels in the source and destination animations based on the alpha component of the source pixel. AG_AnimSetAlpha() controls this flag.

The AG_AnimEmpty() function creates a new zero-sized animation.

AG_AnimStdRGB() and AG_AnimStdRGBA() create an animation in the recommended standard format, as determined by Agar on initialization time. Usually, this is a packed-pixel format with an alpha component.

The AG_AnimIndexed() function creates a new animation of w by h pixels using indexed pixel format. This involves the allocation of a palette. The size of this palette is determined by bitsPerPixel. All entries in the palette are initialized to black, except in the 2-bpp case, where color 0 is initialized to white and color 1 is initialized to black.

The AG_AnimRGB() function creates a new animation of w by h pixels using the specified packed-pixel format. In memory, pixels are encoded as contiguous blocks of bitsPerPixel bits, and the bitmasks specified in [RGB]mask are used to retrieve the individual red, green and blue components. The AG_AnimRGBA() variant adds an alpha-channel component and implicitely sets the AG_SRCALPHA flag.

The AG_AnimFromPNGs() and AG_AnimFromJPEGs() functions attempt to load the contents of a series of image files (specified as a path name with a numerical format string) into a newly-allocated animation. AG_AnimFromPNGs() and AG_AnimFromJPEGs() will return an error unless Agar was compiled with support for libpng and libjpeg, respectively.

The AG_AnimDup() function returns a duplicate of the specified animation, or NULL if insufficient memory is available.

The AG_AnimSetOrigFPS() sets the original frame rate associated with the animation. The default is 30.0. This frame rate can be overriden under playback contexts (see PLAYBACK section below).

The AG_AnimSetPalette() function copies count color entries from the colors array, to count slots (starting at offs) in the palette of indexed surface su.

AG_AnimResize() attempts to resize an animation to the specified dimensions. If insufficient memory is available, the function fails returning -1. When size is increased, the new pixels are left in an uninitialized state. The current clipping rectangle is overwritten by a rectangle covering the entire surface.

The AG_AnimFree() function releases all resources allocated by the given animation.

PER-FRAME OPERATIONS

int AG_AnimFrameNew (AG_Anim *anim, const AG_Surface *su)

AG_Surface * AG_AnimFrameToSurface (AG_Anim *anim, int frame)

The AG_AnimFrameNew() function append a new frame to the animation, using the source surface su. The dimensions of su must match the dimensions of the animation.

AG_AnimFrameToSurface() converts the contents of an animation frame to a newly-allocated surface. The function returns NULL if insufficient memory is available or the frame number is invalid.

PLAYBACK

void AG_AnimStateInit (AG_Anim *anim, AG_AnimState *ast)

void AG_AnimStateDestroy (AG_Anim *anim, AG_AnimState *ast)

int AG_AnimPlay (AG_AnimState *ast)

void AG_AnimStop (AG_AnimState *ast)

void AG_AnimSetFPS (AG_AnimState *ast, double fps)

void AG_AnimSetLoop (AG_AnimState *ast, int enable)

void AG_AnimSetPingPong (AG_AnimState *ast, int enable)

The playback state of an animation is described by a separate structure from AG_Anim, the AG_AnimState structure. This allows a same animation to be played back, for example, by different widgets. The AG_AnimState structure is as follows:

typedef struct ag_anim_state {
	AG_Mutex lock;
	AG_Anim *an;		/* Back pointer to anim */
	Uint flags;
#define AG_ANIM_LOOP	 0x01	/* Loop playback */
#define AG_ANIM_PINGPONG 0x02	/* Loop in ping-pong fashion */
#define AG_ANIM_REVERSE	 0x04	/* Playback in reverse */
	int play;		/* Animation is playing */
	int f;			/* Current frame# */
	double fps;		/* Effective frames/second */
	AG_Thread th;		/* Animation thread */
} AG_AnimState;

The AG_AnimInitState() function initializes an AG_AnimState structure. The structure should be subsequently freed by a call to AG_AnimStateDestroy().

The AG_AnimPlay() function starts playback. This is done by spawning a new thread which is responsible for incrementing the f member of AG_AnimState at a suitable rate. Unless looping is requested, the thread exits once the playback is finished.

AG_AnimStop() immediately stops playback. If the animation is not currently playing, the function is a no-op.

The AG_AnimSetFPS() function sets the frame rate for an animation playback context. The default frame rate is inherited from the AG_Anim structure (see AG_AnimSetOrigFPS()).

The AG_AnimSetLoop() and AG_AnimSetPingPong() functions enable or disable looping.

STRUCTURE DATA

For the AG_Anim structure:

Uint flags	Current animation flags (read-only; see INITIALIZATION section).
*AG_PixelFormat format**	The animation's pixel encoding (read-only; see the PIXEL FORMATS section of AG_Surface(3) for details).
int w, h	Dimensions of the surface in pixels (read-only).
*AG_AnimFrame f**	Pointer to per-frame data.

For the AG_AnimFrame structure:

*void pixels**	Raw packed pixel data for this frame.
Uint flags	Optional flags.

HISTORY

The AG_Anim structure first appeared in Agar 1.4.1.