AG_ANIM(3)

NAME
AG_Anim - agar animated surface

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(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
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.

SEE ALSO
AG_Intro(3), AG_Rect(3), AG_Surface(3)

HISTORY
The AG_Anim structure first appeared in Agar 1.4.1.