Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_ANIM(3)	       FreeBSD Library Functions Manual		    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 unini-
     tialized.	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 in-
		      hibits the copy of all pixels matching the source	anima-
		      tion'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 recom-
     mended `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 con-
     tiguous blocks of bitsPerPixel bits, and the bitmasks specified in
     [RGB]mask are used	to retrieve the	individual red,	green and blue compo-
     nents.  The AG_AnimRGBA() variant adds an alpha-channel component and im-
     plicitely 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 dimen-
     sions.  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 cov-
     ering 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 mem-
     ory 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	cur-
     rently playing, the function is a no-op.

     The AG_AnimSetFPS() function sets the frame rate for an animation play-
     back 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.

FreeBSD	13.0		       November	27, 2010		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | INITIALIZATION | PER-FRAME OPERATIONS | PLAYBACK | STRUCTURE DATA | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=AG_Anim&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help