NAME

AG_Surface — agar graphics surface

SYNOPSIS

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

DESCRIPTION

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

INITIALIZATION

AG_Surface *
AG_SurfaceNew(const AG_PixelFormat *pf, Uint w, Uint h, Uint flags);

AG_Surface *
AG_SurfaceEmpty(void);

AG_Surface *
AG_SurfaceIndexed(Uint w, Uint h, int BitsPerPixel, Uint flags);

AG_Surface *
AG_SurfaceGrayscale(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_SurfaceStdRGB(Uint w, Uint h);

AG_Surface *
AG_SurfaceStdRGBA(Uint w, Uint h);

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_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);

void
AG_SurfaceSetAddress(AG_Surface *surface, Uint8 *p);

void
AG_SurfaceSetColors(AG_Surface *surface, AG_Color *colors, Uint offs, Uint count);

void
AG_SurfaceSetPalette(AG_Surface *surface, const AG_Palette *palette);

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

void
AG_SurfaceFree(AG_Surface *surface);

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.

SURFACE OPERATIONS

void
AG_FillRect(AG_Surface *s, const AG_Rect *r, const 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);

int
AG_SurfaceClipped(const AG_Surface *s, int x, int y);

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);

AG_Surface *
AG_SurfaceScale(const AG_Surface *src, Uint w, Uint h, Uint flags);

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

PIXEL FORMATS

The AG_PixelFormat structure describes how pixels are encoded in memory:

/*                     Bits/Pixel
 *      Mode | 1 2 4 8 16 24 32 40 48 64 |
 *     ----- |---------------------------|
 *    PACKED |         M  M  M  L  L  L  |
 *   INDEXED | M M M M                   |
 * GRAYSCALE |         M  M  M        L  |
 */
typedef enum ag_surface_mode {
	AG_SURFACE_PACKED,
	AG_SURFACE_INDEXED,
	AG_SURFACE_GRAYSCALE
} AG_SurfaceMode;

typedef struct ag_pixel_format {
	AG_SurfaceMode mode;     /* Image type */
	int BitsPerPixel;        /* Depth (in bits/pixel) */
	int BytesPerPixel;       /* Depth (in bytes/pixel) */
	int PixelsPerByteShift;  /* Shift to divide by pixels/byte */
	union {
		AG_Palette *palette;       /* Colormap for Indexed */
		AG_GrayscaleMode graymode; /* Grayscale-RGB method */
		struct {
			/*
			 * Number of bits lost by packing each component
			 * into our native representation.
			 */
			Uint8 Rloss, Gloss, Bloss, Aloss;
			/*
			 * Number of bits at the right of each component.
			 */
			Uint8 Rshift, Gshift, Bshift, Ashift;
			/*
			 * Pixel-wide mask over each component.
			 */
			AG_Pixel Rmask, Gmask, Bmask, Amask;
		};
	};
} AG_PixelFormat;

int
AG_PixelFormatIsSupported(AG_SurfaceMode mode, int BitsPerPixel);

AG_Pixel
AG_PixelFormatMaximum(const AG_PixelFormat *pf);

void
AG_PixelFormatRGB(AG_PixelFormat *pf, int BitsPerPixel, AG_Pixel Rmask, AG_Pixel Gmask, AG_Pixel Bmask);

void
AG_PixelFormatRGBA(AG_PixelFormat *pf, int BitsPerPixel, AG_Pixel Rmask, AG_Pixel Gmask, AG_Pixel Bmask, AG_Pixel Amask);

void
AG_PixelFormatIndexed(AG_PixelFormat *pf);, int BitsPerPixel

void
AG_PixelFormatGrayscale(AG_PixelFormat *pf, int BitsPerPixel);

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

void
AG_PixelFormatFree(AG_PixelFormat *format);

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.

PIXEL ACCESS

AG_Pixel
AG_SurfaceGet(const AG_Surface *s, int x, int y);

Uint8
AG_SurfaceGet8(const AG_Surface *s, int x, int y);

Uint32
AG_SurfaceGet32(const AG_Surface *s, int x, int y);

Uint64
AG_SurfaceGet64(const AG_Surface *s, int x, int y);

AG_Pixel
AG_SurfaceGet_At(const AG_Surface *s, Uint8 *p);

Uint32
AG_SurfaceGet32_At(const AG_Surface *s, const Uint8 *p);

Uint64
AG_SurfaceGet64_At(const AG_Surface *s, const Uint8 *p);

void
AG_SurfacePut(AG_Surface *s, int x, int y, AG_Pixel px);

void
AG_SurfacePut8(AG_Surface *s, int x, int y, Uint8 px);

void
AG_SurfacePut32(AG_Surface *s, int x, int y, Uint32 px);

void
AG_SurfacePut64(AG_Surface *s, int x, int y, Uint64 px);

void
AG_SurfacePut_At(AG_Surface *s, Uint8 *p, AG_Pixel px);

void
AG_SurfacePut32_At(AG_Surface *s, Uint8 *p, Uint32 px);

void
AG_SurfacePut64_At(AG_Surface *s, Uint8 *p, Uint64 px);

void
AG_SurfaceBlend(AG_Surface *s, int x, int y, const AG_Color *c);

void
AG_SurfaceBlend_At(AG_Surface *s, Uint8 *p, const AG_Color *c);

void
AG_SurfaceBlendRGB8(AG_Surface *s, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

void
AG_SurfaceBlendRGB8_At(AG_Surface *s, Uint8 *p, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

void
AG_SurfaceBlendRGB16(AG_Surface *s, int x, int y, Uint16 r, Uint16 g, Uint16 b, Uint16 a);

void
AG_SurfaceBlendRGB16_At(AG_Surface *s, Uint8 *p, Uint16 r, Uint16 g, Uint16 b, Uint16 a);

void
AG_GetColor(AG_Color *dst, AG_Pixel px, const AG_PixelFormat *pf);

void
AG_GetColor32(AG_Color *dst, Uint32 px, const AG_PixelFormat *pf);

void
AG_GetColor64(AG_Color *dst, Uint64 px, const AG_PixelFormat *pf);

void
AG_GetColor_RGB8(AG_Pixel px, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

void
AG_GetColor_RGB16(AG_Pixel px, const AG_PixelFormat *pf, Uint16 *r, Uint16 *g, Uint16 *b, Uint16 *a);

void
AG_GetColor32_RGB8(Uint32 px, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

void
AG_GetColor32_RGB16(Uint32 px, const AG_PixelFormat *pf, Uint16 *r, Uint16 *g, Uint16 *b, Uint16 *a);

void
AG_GetColor64_RGB8(Uint64 px, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);

void
AG_GetColor64_RGB16(Uint64 px, const AG_PixelFormat *pf, Uint16 *r, Uint16 *g, Uint16 *b, Uint16 *a);

AG_Pixel
AG_MapPixel(const AG_PixelFormat *pf, const AG_Color *c);

Uint32
AG_MapPixel32(const AG_PixelFormat *pf, const AG_Color *c);

Uint64
AG_MapPixel64(const AG_PixelFormat *pf, const AG_Color *c);

AG_Pixel
AG_MapPixel_RGB8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b);

AG_Pixel
AG_MapPixel_RGB8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

AG_Pixel
AG_MapPixel_RGB16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b);

AG_Pixel
AG_MapPixel_RGBA16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b, Uint16 a);

Uint32
AG_MapPixel32_RGB8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b);

Uint32
AG_MapPixel32_RGBA8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

Uint32
AG_MapPixel32_RGB16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b);

Uint32
AG_MapPixel32_RGBA16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b, Uint16 a);

Uint64
AG_MapPixel64_RGB8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b);

Uint64
AG_MapPixel64_RGBA8(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

Uint64
AG_MapPixel64_RGB16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b);

Uint64
AG_MapPixel64_RGBA16(const AG_PixelFormat *pf, Uint16 r, Uint16 g, Uint16 b, Uint16 a);

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.

STRUCTURE DATA

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

HISTORY

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.