SYNOPSIS
|
DESCRIPTION
The
AG_Surface structure describes a graphics surface in one of:
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_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:
Acceptable flags include:
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. |
SURFACE OPERATIONS
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 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_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_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
PIXEL ACCESS
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:
|
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.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(). |