Agar

<-- Back to AG_Intro.3

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 in any order into 8-, 16-, 24-, 32- or 64-bit wide pixels.
Indexed Mode 1-, 2-, 4- or 8-bit per pixel palettized mode.
Grayscale Mode 16- or 32-bit grayscale with alpha packed into 32- or 64-bit wide pixels.

Image transfers work across all modes and support alpha blending according to an alpha channel (if one is defined) and/or a per-surface overall alpha. Simple colorkey based transparency is also supported. Image transfers honor a settable per-surface clipping rectangle.

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_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_SurfaceSetColors (AG_Surface *surface, AG_Color *colors, Uint offs, Uint count)

int 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 agSurfaceFmt is passed under format, then Agar will select the "best" available mode closest to the native display. Acceptable values for type include:
AG_SURFACE_PACKED 8- or 16-bit RGBA components packed into 8-, 16-, 24-, 32- 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_COLORKEYEnable colorkey. In AG_SurfaceBlit(), this option inhibits the copy of all pixels matching the source surface's colorkey setting. AG_SurfaceSetColorKey() controls this flag.
AG_SURFACE_ALPHAEnable 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 (and the per-surface alpha). See AG_SetAlpha().
AG_SURFACE_GL_TEXTURESurface can be uploaded as an OpenGL texture without the need for pixel format conversion. See AG_GL_UploadTexture(3), AG_GL_UpdateTexture(3).
AG_SURFACE_MAPPEDSurface is attached to an AG_Widget(3) (so any calls to AG_SurfaceFree(3) are disallowed).

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. Entries in the palette are initialized to black except in monochrome (1-bpp) mode where colors (0,1) are initialized to (white,black).

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_SurfaceRGBA() implicitely sets the AG_SURFACE_ALPHA flag by default.

The AG_SurfaceStdRGB() and AG_SurfaceStdRGBA() macros are shorthands for AG_SurfaceRGB() or AG_SurfaceRGBA() with flags of 0 and bitsPerPixel/ [RGBA]mask set according to the reference format (agSurfaceFmt).

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

The AG_SurfaceStdGL() function creates a surface in an optimal format for OpenGL textures (packed, 32 bits per pixel with native-endian RGB masks). It also sets the AG_SURFACE_GL_TEXTURE 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.

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)

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)



AG_FillRect() 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 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_ADAM7Enable 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_ISLOWSlow, but accurate integer DCT method.
AG_EXPORT_JPEG_JDCT_IFASTFast, but less accurate integer DCT method.
AG_EXPORT_JPEG_JDCT_FLOATFloating-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

The AG_PixelFormat structure describes how pixels are encoded in memory: 
                               /* Bits per pixel: | 1 2 4 8 16 24 32 64 |*/
typedef enum ag_surface_mode { /* --------------- |---------------------|*/
	AG_SURFACE_PACKED,     /* Packed RGB(A)   |     S   S  M  M  L  |*/
	AG_SURFACE_INDEXED,    /* Palettized      | S S S S             |*/
	AG_SURFACE_GRAYSCALE   /* Grayscale+Alpha |            M  M  L  |*/
} 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 PixelsPerByte;       /* Pixels per byte (or 0 if >8bpp) */
	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_PixelFormat * AG_PixelFormatRGB (Uint8 bitsPerPixel, AG_Pixel Rmask, AG_Pixel Gmask, AG_Pixel Bmask)

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

AG_PixelFormat * AG_PixelFormatIndexed (Uint8 bitsPerPixel)

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

void AG_PixelFormatFree (AG_PixelFormat *format)




AG_PixelFormatIsSupported() returns 1 if the given combination of encoding and bits per pixel is supported by the present Agar build.

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 palette entry is initialized to white and the second entry is initialized to black.

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, AG_AlphaFn fn)

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

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

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

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

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

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, Uint8 a)

AG_Pixel AG_MapPixel_RGB16 (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, Uint8 a)

Uint32 AG_MapPixel32_RGB16 (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, Uint8 a)

Uint64 AG_MapPixel64_RGB16 (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 surface is 48- or 64-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 surface is 48- or 64-bpp, AG_SurfacePut32() writes a decompressed approximation. 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() function performs alpha blending of a color c against the pixel at unchecked coordinates x, y in a surface s. The alpha component of the resulting pixel is determined by fn (see AG_BlendFn(3) for details).

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

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 (read-only).
Uint8 *pixels Pixel data. Packed (1- to 4-bpp), 4-byte aligned (8- to 32-bpp), or 8-byte aligned (AG_LARGE).
Uint pitch Size of a scanline in bytes.
Uint padding Scanline end padding in bytes.
AG_Rect clipRect Clipping rectangle (default to cover surface).
AG_Pixel colorkey Transparency color key (for AG_SURFACE_COLORKEY option).
AG_Component alpha Per-surface overall alpha.

SEE ALSO

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

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 introduced support for 48- and 64-bit color (16-bit per AG_Color component precision). Agar 1.6 also added support for grayscale+alpha and true 1-, 2-, and 4-bpp palettized modes.
Csoft.net ElectronTubeStore