NAME

SYNOPSIS

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

DESCRIPTION

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_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_SurfaceFromFile(const char *path);

AG_Surface *
AG_SurfaceFromPNG(const char *path);

AG_Surface *
AG_SurfaceFromJPEG(const char *path);

AG_Surface *
AG_SurfaceFromBMP(const char *path);

AG_Surface *
AG_ReadSurface(AG_DataSource *ds);

AG_Surface *
AG_ReadSurfaceFromPNG(AG_DataSource *ds);

AG_Surface *
AG_ReadSurfaceFromJPEG(AG_DataSource *ds);

AG_Surface *
AG_ReadSurfaceFromBMP(AG_DataSource *ds);

int
AG_WriteSurface(AG_DataSource *ds, AG_Surface *surface);

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_PACKED

Packed-pixel format (e.g., RGBA)

AG_SURFACE_INDEXED

Color-index format (per-surface palette)

Acceptable flags include:

AG_SRCCOLORKEY

Enable 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_SRCALPHA

Enable 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_GLTEXTURE

Surface 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_SurfaceFromFile() routine loads the contents of an image file into a newly-allocated surface. The image format is auto-detected. The AG_SurfaceFrom{BMP,PNG,JPEG}() variants will load an image only in the specified format.

The AG_ReadSurface() function reads an uncompressed surface (in native AG_Surface encoding). The AG_ReadSurfaceFrom{BMP,PNG,JPEG}() variants will load an image only in the specified format.

The AG_WriteSurface() function saves the surface to the specified data source in native AG_Surface encoding.

The AG_SurfaceFromSDL() function converts a SDL_Surface(3) to a newly-allocated AG_Surface structure. This function is available only 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_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_SurfaceExportFile(const AG_Surface *su, char *path);

int
AG_SurfaceExportPNG(const AG_Surface *su, char *path, Uint flags);

int
AG_SurfaceExportJPEG(const AG_Surface *su, char *path, Uint quality, Uint flags);

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

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

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_SurfaceExportFile() routine exports a surface to a specified image file. The image format will be determined by the filename extension in path.

AG_SurfaceExportPNG() exports a surface to a PNG image file, preserving any transparency data. Available flags options include:

AG_EXPORT_PNG_ADAM7

Enable Adam7 interlacing.

AG_SurfaceExportJPEG() exports the surface to a file in JPEG format. If the surface has an alpha-channel, it is ignored. quality is given in percent (100% = best). Available flags options include:

AG_EXPORT_JPEG_JDCT_ISLOW

Slow, but accurate integer DCT method.

AG_EXPORT_JPEG_JDCT_IFAST

Fast, but less accurate integer DCT method.

AG_EXPORT_JPEG_JDCT_FLOAT

Floating-point DCT method.

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

AG_SurfaceExportSDL() exports an Agar surface to a newly allocated SDL_Surface(3). This function is available only if Agar was compiled with SDL support.

PIXEL FORMATS

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

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

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 (4-byte aligned)

Uint pitch

Size of a scanline in bytes.

Uint padding

Scanline padding in bytes.

SEE ALSO

HISTORY