Agar


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_Surface structure describes a raster-based software graphics surface. It supports all packed pixel formats which encode pixels in 32-bit or less and allow components to be retrieved by bitmasks. Indexed (or palletized) pixel formats up to 8-bit per pixel are also supported.

AG_Surface supports colorkey and alpha-blending (with an alpha channel or per-surface alpha setting). Surfaces may define destination clipping rectangles for operations such as AG_SurfaceBlit().

INITIALIZATION


AG_Surface * AG_SurfaceNew (enum ag_surface_type type, Uint w, Uint h, const AG_PixelFormat *fmt, Uint flags)

AG_Surface * AG_SurfaceEmpty (void)

AG_Surface * AG_SurfaceStdRGB (Uint w, Uint h)

AG_Surface * AG_SurfaceStdRGBA (Uint w, Uint h)

AG_Surface * AG_SurfaceIndexed (Uint w, Uint h, int bitsPerPixel, Uint flags)

AG_Surface * AG_SurfaceRGB (Uint w, Uint h, int bitsPerPixel, Uint flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask)

AG_Surface * AG_SurfaceRGBA (Uint w, Uint h, int bitsPerPixel, Uint flags, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)

AG_Surface * AG_SurfaceFromPixelsRGB (void *pixels, Uint w, Uint h, int bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask)

AG_Surface * AG_SurfaceFromPixelsRGBA (void *pixels, Uint w, Uint h, int bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)

AG_Surface * AG_SurfaceStdGL (Uint w, Uint h)

AG_Surface * AG_SurfaceFromPNG (const char *path)

AG_Surface * AG_SurfaceFromJPEG (const char *path)

AG_Surface * AG_SurfaceFromBMP (const char *path)

/* Requires Agar compiled --with-sdl */
AG_Surface * AG_SurfaceFromSDL (SDL_Surface *surface)

int AG_SurfaceSetPalette (AG_Surface *su, AG_Color *colors, Uint offs, Uint count)

int AG_SurfaceResize (AG_Surface *surface, Uint w, Uint h)

void AG_SurfaceFree (AG_Surface *surface)


The AG_SurfaceNew() function allocates and initializes a new AG_Surface 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_SURFACE_PACKEDPacked-pixel format (e.g., RGBA)
AG_SURFACE_INDEXEDColor-index format (per-surface palette)

Acceptable flags include:
AG_SRCCOLORKEYEnable colorkeying. In AG_SurfaceBlit(), this option inhibits the copy of all pixels matching the source surface's colorkey setting. AG_SurfaceSetColorKey() controls this flag.
AG_SRCALPHAEnable alpha blending. In AG_SurfaceBlit(), this option enables blending of pixels in the source and destination surfaces based on the alpha component of the source pixel. AG_SetAlpha() controls this flag.
AG_SURFACE_GLTEXTURESurface is suitable to be uploaded directly as an OpenGL texture without format conversion. This flag is recognized by AG_GL_UploadTexture(3) and AG_GL_UpdateTexture(3).

The AG_SurfaceEmpty() function creates a new 0x0 pixel surface. Blitting such an empty surface is a no-op.

AG_SurfaceStdRGB() and AG_SurfaceStdRGBA() create a surface 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_SurfaceIndexed() function creates a new surface 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_SurfaceRGB() function creates a new surface 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_SurfaceRGBA() variant adds an alpha-channel component and implicitely sets the AG_SRCALPHA flag (see AG_SurfaceBlit 3()).

AG_SurfaceFromPixelsRGB() and AG_SurfaceFromPixelsRGBA() create a new surface from existing pixel data in the specified format. The AG_SurfaceFromPixelsRGBA() function also sets the AG_SRCALPHA flag.

The AG_SurfaceStdGL() function creates a surface in an optimal format for OpenGL textures (packed, 32 bits per pixel with native RGB masks). It also sets the AG_SURFACE_GLTEXTURE flag on the new surface. The function does not use OpenGL itself and is available regardless of whether Agar was compiled with OpenGL support.

The AG_SurfaceFromPNG(), AG_SurfaceFromJPEG() and AG_SurfaceFromBMP() functions attempt to load the contents of an image file into a newly-allocated surface. AG_SurfaceFromPNG() and AG_SurfaceFromJPEG() will return an error unless Agar was compiled with support for libpng and libjpeg, respectively.

The AG_SurfaceFromSDL() function converts a SDL_Surface(3) to a newly-allocated AG_Surface structure. This function is only available if Agar was compiled with SDL support.

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

AG_SurfaceResize() attempts to resize a surface 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 surface's current clipping rectangle is overwritten by a rectangle covering the entire surface.

The AG_SurfaceFree() function releases all resources allocated by the given surface.

SURFACE OPERATIONS


void AG_FillRect (AG_Surface *s, const AG_Rect *r, AG_Color c)

void AG_SurfaceBlit (const AG_Surface *src, const AG_Rect *rSrc, AG_Surface *dst, int x, int y)

void AG_SetClipRect (AG_Surface *s, const AG_Rect *r)

void AG_GetClipRect (const AG_Surface *s, AG_Rect *r)

void AG_SurfaceCopy (AG_Surface *dest, const AG_Surface *src)

AG_Surface * AG_SurfaceDup (const AG_Surface *src)

AG_Surface * AG_SurfaceConvert (const AG_Surface *src, const AG_PixelFormat *newFmt)

int AG_ScaleSurface (const AG_Surface *src, Uint16 width, Uint16 height, AG_Surface **dst)

void AG_SetAlphaPixels (AG_Surface *surface, Uint8 alpha)

int AG_SurfaceExportPNG (const AG_Surface *su, char *path)

void AG_SetPNGInterlacing (int enable)

int AG_SurfaceExportJPEG (const AG_Surface *su, char *path)

int AG_SetJPEGQuality (int quality)

int AG_SurfaceExportBMP (const AG_Surface *su, char *path)

/* Requires Agar compiled --with-sdl */
SDL_Surface * AG_SurfaceExportSDL (const AG_Surface *su)




The AG_FillRect() routine fills the rectangle r with the specified color. If the target surface has an alpha channel, the alpha component is copied as-is. If the rectangle lies outside of the surface's clipping rectangle, it is clipped accordingly.

AG_SurfaceBlit() copies the contents of a surface (or a region within a surface if rSrc is non-NULL), to a given target position x, y within surface dst. The clipping rectangle of dst (see below) applies.

AG_SetClipRect() sets the clipping rectangle of the surface. The clipping rectangle will apply to surface operations such as AG_SurfaceBlit(), as well as pixel manipulation macros which perform clipping tests ( AG_PUT_PIXEL2_CLIPPED(), AG_BLEND_RGBA2_CLIPPED()). AG_GetClipRect() returns the current clipping rectangle of a surface. If the source or destination rectangles lie outside of the surface area, they are clipped accordingly.

The AG_SurfaceCopy() function copies the contents of surface src onto another, existing surface dst. The raw pixel data is copied, so alpha and colorkey parameters are ignored. Clipping is done if the surfaces have different sizes.

AG_SurfaceDup() returns a newly allocated surface containing a copy of src. If there is insufficient memory, AG_SurfaceDup() will fail returning NULL.

AG_SurfaceConvert() is similar to AG_SurfaceDup(), except that the surface is converted to the specified pixel format newFmt.

AG_ScaleSurface() returns a copy of surface src scaled to the given size in pixels into dst, which must be either NULL or a pointer to an existing surface. If dst is NULL, a new surface is allocated. If there is insufficient memory for the rescaled surface, AG_ScaleSurface() will fail returning -1.

The AG_SetAlphaPixels() function changes the alpha component of all pixels with a non-zero alpha component.

The AG_SurfaceExportPNG() function exports a PNG image file from the contents of a surface. An error is returned if Agar was not compiled with libpng support. AG_SetPNGInterlacing() enables or disables interlacing (Adam7).

AG_SurfaceExportJPEG() exports a JPEG image file from the contents of a surface. If the surface has an alpha-channel, it is ignored. An error is returned if Agar was not compiled with libjpeg support. AG_SetJPEGQuality() sets the quality setting for saved JPEGs. The value is given in percent, 100% being the highest quality (the default).

AG_SurfaceExportBMP() exports a BMP image file from the contents of a surface. If the surface has an alpha-channel, it is ignored.

PIXEL FORMATS


AG_PixelFormat * AG_PixelFormatRGB (Uint8 bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask)

AG_PixelFormat * AG_PixelFormatRGBA (Uint8 bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)

AG_PixelFormat * AG_PixelFormatIndexed (Uint8 bitsPerPixel)

int AG_PixelFormatCompare (const AG_PixelFormat *pf1, const AG_PixelFormat *pf2)

void AG_PixelFormatFree (AG_PixelFormat *format)


The AG_PixelFormat structure describes a general indexed or packed-pixel surface format. It is defined as follows: 
typedef struct ag_pixel_format {
	AG_Palette *palette;                 /* For indexed formats */
	Uint8   BitsPerPixel;                /* Depth (bits/pixel) */
	Uint8   BytesPerPixel;               /* Depth (bytes/pixel) */
	Uint8   Rloss, Gloss, Bloss, Aloss;
	Uint8   Rshift, Gshift, Bshift, Ashift;
	Uint32  Rmask, Gmask, Bmask, Amask;
	Uint32  colorkey;                    /* Color key pixel */
	Uint8   alpha;                       /* Per-surface alpha value */
} AG_PixelFormat;

The AG_PixelFormatRGB() and AG_PixelFormatRGBA() functions allocate a new structure describing packed-pixel encoding with RGB or RGBA components. The [RGBA]mask arguments specify the bitmasks used to retrieve the individual components from memory.

AG_PixelFormatIndexed() creates a new pixel-format structure for indexed pixel encoding. This involves allocating a new palette. The size of this palette is determined by bitsPerPixel, and all palette entries are initialized to black. If 2 bpp is given, the first entry is initialized to white (255,255,255) and the second entry to black (0,0,0).

If no memory is available, AG_PixelFormat*() fail returning NULL.

AG_PixelFormatCompare() compares two pixel formats. The function returns 0 if the two formats are identical, nonzero if the two formats differ. When comparing color-index formats, the two palettes are compared as well.

AG_PixelFormatFree() releases all resources allocated by an AG_PixelFormat structure.

PACKED-PIXEL SURFACE OPERATIONS

The following routines operate on surfaces in packed-pixel format exclusively.


Uint32 AG_GET_PIXEL (const AG_Surface *s, const Uint8 *p)

Uint32 AG_GET_PIXEL2 (const AG_Surface *s, int x, int y)

void AG_PUT_PIXEL (AG_Surface *s, Uint8 *p, Uint32 c)

void AG_PUT_PIXEL2 (AG_Surface *s, int x, int y, Uint32 c)

void AG_BLEND_RGBA (AG_Surface *s, Uint8 *p, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func)

void AG_BLEND_RGBA2 (AG_Surface *s, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func)

void AG_SurfaceBlendPixel (AG_Surface *s, Uint8 *p, AG_Color C, AG_BlendFn fn)

void AG_PUT_PIXEL2_CLIPPED (AG_Surface *s, int x, int y, Uint32 c)

void AG_BLEND_RGBA2_CLIPPED (AG_Surface *s, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func)

void AG_GetPixelRGB (Uint32 pixel, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b)

void AG_GetPixelRGBA (Uint32 pixel, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)

Uint32 AG_MapPixelRGB (const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uing8 b)

Uint32 AG_MapPixelRGBA (const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uing8 b, Uint8 a)

AG_Color AG_GetColorRGB (Uint32 pixel, const AG_PixelFormat *pf)

AG_Color AG_GetColorRGBA (Uint32 pixel, const AG_PixelFormat *pf)

Uint32 AG_MapColorRGB (const AG_PixelFormat *pf, AG_Color color)

Uint32 AG_MapColorRGBA (const AG_PixelFormat *pf, AG_Color color)


The AG_GET_PIXEL() macro returns a packed 32-bit representation of the pixel at the given location p in the surface s. AG_GET_PIXEL2() variant locates the pixel in the surface using x,y coordinates.

The AG_PUT_PIXEL() and AG_PUT_PIXEL2() write the color c to the pixel at the given location.

The AG_BLEND_RGBA() and AG_BLEND_RGBA2() routines perform alpha-blending of the destination pixel against the specified color, where func specifies the blending formula (see AG_BlendFn(3)). The AG_SurfaceBlendPixel() function accepts an AG_Color(3) argument and performs no clipping tests.

The AG_PUT_PIXEL2_CLIPPED() and AG_BLEND_RGBA2_CLIPPED() variants of these macros first tests the given coordinates against the clipping rectangle of the surface (see AG_SetClipRect(3)). If the pixel lies outside of the rectangle, the operation is a no-op.

The AG_GetPixelRGB() and AG_GetPixelRGBA() functions extract the RGB / RGBA components of a pixel value pixel, in pixel format pf. The AG_MapPixelRGB() and AG_MapPixelRGBA() functions perform the inverse operation, returning the pixel value (in pixel format pf) for the specified RGB / RGBA component values.

The AG_GetColor*() and AG_MapColor*() functions are equivalent to AG_GetPixel*() and AG_MapPixel*() except that they accept AG_Color(3) arguments instead of separate component values.

Note that the preceding routines are only for use against surfaces in packed RGB/RGBA pixel formats. Passing a color-index format to AG_GetPixel*(), AG_GetColor*(), AG_MapPixel*() or AG_MapColor*() is an illegal operation.

STRUCTURE DATA

For the AG_Surface structure:
Uint flags Current surface flags (read-only; see INITIALIZATION section).
AG_PixelFormat *format The surface's pixel encoding (read-only; see PIXEL FORMATS section).
int w, h Dimensions of the surface in pixels (read-only).
void *pixels Pointer to raw pixel data.

SEE ALSO

AG_Intro(3), AG_Anim(3), AG_Rect(3)

HISTORY

The AG_Surface structure first appeared in Agar 1.3.3. It is modeled after the SDL_Surface of SDL (http://libsdl.org/).