NAME

SYNOPSIS

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

DESCRIPTION

INITIALIZATION

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(const 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 source animation must be locked (src->lock).

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

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_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

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.

SEE ALSO

HISTORY