SYNOPSIS

DESCRIPTION

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.

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:

16- or 32-bit grayscale with alpha packed into 32- or 64-bit wide pixels.

Acceptable
flags include:

AG_SURFACE_COLORKEY

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

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 (and the per-surface alpha).
See
AG_SetAlpha().

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.

AG_SurfaceStdRGB() and
AG_SurfaceStdRGBA() create a new 32-bit packed-pixel surface in an optimal format for blitting
to the display (for framebuffer drivers), or for transferring to a texture
(for OpenGL drivers).

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

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_SurfaceCopyPixels() copies pixel data from
src to the surface.
The pixel data is copied as-is without any conversion and is assumed
to be in a format compatible with that of
surface.

AG_SurfaceSetPixels() clears the surface with pixels of the given
color.

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.

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

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.

SEE ALSO

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 modes (under LARGE),
Grayscale+Alpha and 1/2/4-bit Indexed modes.
Agar 1.6.0 introduced
AG_SurfaceSetAddress(), AG_SurfaceSetColors(), AG_SurfaceSetPalette(), AG_SurfaceCopyPixels() and
AG_SurfaceSetPixels(). AG_SurfaceStdGL() is now a deprecated alias for
AG_SurfaceStdRGBA().