The AG_Surface structure describes a graphics surface in one of:

Packed Mode	8- or 16-bit RGBA components packed into 8-, 16-, 24-, 32-, 40-, 48- or 64-bit wide pixels. Components may be packed in any order (RGBA, BGRA, etc). The extraction bitmasks and shifts are part of the surface format.
Indexed Mode	1-, 2-, 4- or 8-bit per pixel palettized access mode. The minimum pitch is 1 byte. The palette is part of the surface format.
Grayscale Mode	16- or 32-bit grayscale (with alpha) packed into 32- or 64-bit wide pixels. The choice of standard for conversion to RGB is part of the surface format.

Image transfers (blits) are supported between all modes, and should work consistently across surfaces in different formats.

If an alpha channel is defined (or the per-surface alpha of the source surface is not AG_OPAQUE) then the blit operation performs alpha blending. Colorkey is also supported. If the source surface in a blit has a colorkey then all pixels matching it will be treated as transparent.

Blit operations honor a per-surface clipping rectangle (which spans the entire surface by default). In an image transfer, the effective block of pixels transferred will be the intersection of the source rectangle and the destination surface's clipping rectangle.

Fast cropping can be performed by modifying w, h, Lpadding and padding and incrementing the pixels pointer (leaving the pixel data untouched).

Surfaces may also define up to 4 general-purpose 16-bit guides (for typography and other application-specific purposes).

AG_SurfaceNew() allocates and initializes a new graphics surface of size w, h in pixels. The pf argument is the AG_PixelFormat describing the type of surface (Packed / Palettized / Grayscale), and the way pixels are to be encoded in memory (see PIXEL FORMATS). If pf is NULL, the format field is left uninitialized (the caller can later use AG_PixelFormat*() to initialize it). If the global variable agSurfaceFmt is passed as format then the "best" available mode (the one closest to the native display) will be selected. Acceptable values for type include:

AG_SURFACE_PACKED	8- or 16-bit RGBA components packed into 8-, 16-, 24-, 32-, 40-, 48- or 64-bit wide pixels.
AG_SURFACE_INDEXED	1-, 2-, 4- or 8-bit per pixel palettized mode.
AG_SURFACE_GRAYSCALE	16- or 32-bit grayscale with alpha packed into 32- or 64-bit wide pixels.

Acceptable flags include:

AG_SURFACE_COLORKEY	Enable colorkeying. In AG_SurfaceBlit(), inhibit the copy of all pixels matching the source surface's colorkey. AG_SurfaceSetColorKey() controls this flag.
AG_SURFACE_GL_TEXTURE	Surface can be uploaded as an OpenGL texture directly (without the need for conversion). This flag is set automatically if the depth and RGBA masks are compatible. See AG_GL_UploadTexture(3), AG_GL_UpdateTexture(3).
AG_SURFACE_MAPPED	Surface is attached to an AG_Widget(3). Calls to AG_SurfaceFree(3) will result in a fatal assertion (Debug mode only).

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

AG_SurfaceIndexed() creates a new surface of w by h pixels using an indexed pixel format with palette. The size of this palette is determined by BitsPerPixel. The palette is initialized to a standard palette for 1/2/4-bpp modes. For 8-bpp mode, the initial palette is left uninitialized.

AG_SurfaceGrayscale() creates a new surface of w by h pixels in a grayscale format with alpha channel.

AG_SurfaceRGB() and AG_SurfaceRGBA() 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 8-bit red, green, blue and alpha components.

AG_SurfaceStdRGB() and AG_SurfaceStdRGBA() create a new packed-pixel surface in the "best" format for blitting directly to the display (for framebuffer based drivers) or for transferring to a texture unit (for OpenGL based drivers).

AG_SurfaceFromPixelsRGB() and AG_SurfaceFromPixelsRGBA() create and initialize a new surface by copying existing pixel data in the given format.

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.

AG_SurfaceSetAddress() sets the pixel data pointer of the surface to an external address. If p is NULL then revert to internally auto-allocated pixel data.

AG_SurfaceSetColors() sets contiguous entries in the colormap of a palettized surface from a given array of AG_Color(3).

AG_SurfaceSetPalette() sets the entire colormap of a palettized surface from the given AG_Palette.

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.

The AG_FillRect() routine fills the rectangle r (or rather the intersection of r with the surface's clipping rectangle) against a color c. AG_FillRect() does not perform alpha blending and the alpha component of target pixels (when surface has an alpha channel) are replaced by that of c.

AG_SurfaceBlit() performs an image transfer from one surface (or rectangular region of pixels in a surface) to coordinates x, y in surface dst. Honors the target surface's clipping rectangle. If a colorkey is set, matching transparent pixels are skipped. If the source surface has an alpha channel then blend the source pixel against the destination (if destination surface has an alpha channel, sum the alpha of both pixels and clamp to maximum opacity).

AG_SetClipRect() sets the clipping rectangle of surface s. The default clipping rectangle is (0, 0, s->w, s->h). The clipping rectangle is used by operations such as AG_SurfaceBlit() and AG_FillRect(), but it is ignored by functions which accept unchecked coordinates, such as AG_SurfaceGet() or AG_SurfacePut().

The AG_SurfaceClipped() test returns 1 if the pixel at x, y should be clipped away according to the clipping rectangle of s, otherwise it returns 0.

AG_GetClipRect() returns the current clipping rectangle of s.

AG_SurfaceCopy() copies the contents of surface src onto another, existing surface dst. Colorkey and alpha parameters are ignored. Pixel data is block copied (if the formats allow it), simply copied, or otherwise converted if the formats differ. If the two surfaces have different sizes then padding and/or clipping is done.

AG_SurfaceDup() returns a newly allocated surface containing a copy of src.

AG_SurfaceConvert() returns a newly allocated copy of the surface, but in the given format pf. Conversion is performed if the pixel formats differ.

AG_SurfaceScale() returns a copy of the surface src scaled to w by h pixels (or NULL if an error occurred). The flags argument is for future expansion and should be set to 0.

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 structure for SDL 1.x. Inherit per-surface alpha and colorkey. This function is available only if Agar was compiled with SDL1 support.

The AG_PixelFormat structure describes how pixels are encoded in memory:
The AG_PixelFormatIsSupported() function returns 1 if the given combination of encoding and bits per pixel is supported by the present Agar build.

The AG_PixelFormatMaximum() function returns the maximum pixel value representible by surfaces in the given format pf.

The AG_PixelFormatRGB() and AG_PixelFormatRGBA() routines initialize an AG_PixelFormat structure describing a surface in packed-pixel format of depth BitsPerPixel. The arguments [RGBA]mask specify the bitmasks used to extract individual color components (and alpha) from the surface in memory.

The AG_PixelFormatIndexed() routine initializes an AG_PixelFormat structure describing a surface in indexed format. Agar considers the palette to be part of the AG_PixelFormat structure so the palette itself is allocated as well. The size of this palette is determined by BitsPerPixel and palette entries are initialized to black (except in the 1bpp case, where entry 0 is also initialized to white).

The AG_PixelFormatGrayscale() routine initializes an AG_PixelFormat structure describing a surface in grayscale format. Supported depths are 16-, 32- and 64-bpp. The grayscale format also includes an alpha channel which can be ignored if transparency is not needed. The global agGrayscaleMode determines the default conversion standard to use when converting between grayscale and RGB. The default is AG_GRAYSCALE_BT709.

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() frees all resources allocated by an AG_PixelFormat.

AG_SurfaceGet8() returns the value (color index) of the pixel at unchecked coordinates x, y in an 1- to 8-bpp indexed surface s.

AG_SurfaceGet32() returns a 32-bit representation of the pixel at unchecked coordinates x, y in a 1- to 64-bpp surface s. If the given surface is more than 32-bpp, AG_SurfaceGet32() returns a compressed 32-bit approximation. The AG_SurfaceGet32_At() form returns a 32-bit representation of the pixel at address p in an 8- to 64-bpp surface s.

AG_SurfaceGet64() returns a 64-bit representation of the pixel at unchecked coordinates x, y in an 1- to 64-bpp surface s. The AG_SurfaceGet64_At() form returns a 64-bit representation of the pixel at address p in an 8- to 64-bpp surface s.

The AG_SurfacePut8() procedure writes to the pixel at x, y in a 1- to 8-bpp indexed surface s.

AG_SurfacePut32() writes to the pixel at unchecked coordinates x, y in a 1- to 64- surface s. If the given surface is more than 32-bpp, AG_SurfacePut32() writes a decompressed value. The AG_SurfacePut32_At() form writes to the pixel at address p in an 8- to 64-bpp surface s.

AG_SurfacePut64() writes to the pixel at unchecked coordinates x, y in a 1- to 64-bpp surface s. The AG_SurfacePut64_At() form writes to the pixel at address p in an 8- to 64-bpp surface s.

The AG_SurfaceBlend() routine blends the color c against the pixel at unchecked coordinates x, y in a surface s.

The AG_SurfaceBlend_At() variant performs alpha blending of a color c against the pixel at byte address p in surface s.

The AG_SurfaceBlendRGB{8,16}() and AG_SurfaceBlendRGB{8,16}_At() forms accept discrete 8- and 16-bit components instead of an AG_Color(3).

AG_GetColor32() extracts RGBA components from a 32-bit pixel in specified format and returns the corresponding AG_Color(3) into dst. The procedural forms AG_GetColor32_RGB{8,16} ,() return the color components into separate arguments.

AG_GetColor64() extracts RGBA components from a 64-bit pixel in specified format and returns the corresponding AG_Color(3). The procedural forms AG_GetColor64_RGB{8,16}() return the color components into separate arguments.

AG_MapPixel32() returns a 32-bit representation of the color c. The AG_MapPixel32_RGB{8,16}() forms accept individual components as separate arguments.

AG_MapPixel64() returns a 64-bit representation of the color c. The AG_MapPixel64_RGB{8,16}() forms accept individual components as separate arguments.

For the AG_Surface structure:

AG_PixelFormat format	Pixel encoding format (see PIXEL FORMATS).
Uint flags	Option flags (see INITIALIZATION).
Uint w, h	Dimensions of the surface in pixels.
Uint8 *pixelsBase	Base address of pixel data (read-only; modifiable by calling AG_SurfaceSetAddress()).
Uint8 *pixels	Current pointer to pixel data. Can be incremented in order to crop lines off the top.
Uint pitch	Total size of a scanline in bytes.
Uint padding	Scanline end padding in bytes. Increment (and also decrement w) to crop lines off the right. Used to align rows to a 32- or 64-bit boundary.
Uint Lpadding	Scanline start padding in bytes. Increment (and also decrement w) to crop lines off the left.
AG_Rect clipRect	Clipping rectangle (default = whole surface).
AG_Pixel colorkey	Transparency color key (for AG_SURFACE_COLORKEY).
Uint alpha	Per-surface alpha (overall; AG_Component value).

AG_Intro(3), AG_Color(3), AG_Rect(3)

The AG_Surface structure first appeared in Agar 1.3.3. It was first modeled after the SDL_Surface of SDL. Agar 1.6.0 added support for 48- and 64-bit Packed, 32- and 64-bit Grayscale and Indexed modes. It also introduced the AG_SurfaceSetAddress(), AG_SurfaceSetColors() and AG_SurfaceSetPalette() routines. Agar 1.7.0 added support for 40-bit color, optimized blitters, optimized rectangle fills and fast cropping. The pixelsBase pointer, the Lpadding member as well as the ability to modify the pixels pointer appeared in Agar 1.7.0.