.\" Copyright (c) 2006-2023 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd February 5, 2023 .Dt AG_SURFACE 3 .Os Agar 1.7 .Sh NAME .Nm AG_Surface .Nd agar graphics surface .Sh SYNOPSIS .Bd -literal #include #include .Ed .Sh DESCRIPTION The .Nm structure describes a graphics surface in one of: .Pp .Bl -tag -width "Grayscale Mode " .It Packed Mode .\" SYNC packed 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. .It Indexed Mode .\" SYNC indexed 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. .It Grayscale Mode .\" SYNC grayscale 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. .El .Pp Image transfers (blits) are supported between all modes, and should work consistently across surfaces in different formats. .Pp If an alpha channel is defined (or the per-surface .Va alpha of the source surface is not .Dv AG_OPAQUE ) then the blit operation performs alpha blending. Colorkey is also supported. If the source surface in a blit has a .Va colorkey then all pixels matching it will be treated as transparent. .Pp 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. .Pp Fast cropping can be performed by modifying .Va w , .Va h , .Va Lpadding and .Va padding and incrementing the .Va pixels pointer (leaving the pixel data untouched). .Pp Surfaces may also define up to 4 general-purpose 16-bit guides (for typography and other application-specific purposes). .Sh INITIALIZATION .nr nS 1 .Ft "AG_Surface *" .Fn AG_SurfaceNew "const AG_PixelFormat *pf" "Uint w" "Uint h" "Uint flags" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceEmpty "void" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceIndexed "Uint w" "Uint h" "int BitsPerPixel" "Uint flags" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceGrayscale "Uint w" "Uint h" "int BitsPerPixel" "Uint flags" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceRGB "Uint w" "Uint h" "int BitsPerPixel" "Uint flags" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceRGBA "Uint w" "Uint h" "int BitsPerPixel" "Uint flags" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" "Uint32 Amask" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceStdRGB "Uint w" "Uint h" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceStdRGBA "Uint w" "Uint h" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromPixelsRGB "void *pixels" "Uint w" "Uint h" "int BitsPerPixel" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromPixelsRGBA "void *pixels" "Uint w" "Uint h" "int BitsPerPixel" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" "Uint32 Amask" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromFile "const char *path" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromPNG "const char *path" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromJPEG "const char *path" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromBMP "const char *path" .Pp .Ft "AG_Surface *" .Fn AG_ReadSurface "AG_DataSource *ds" .Pp .Ft "AG_Surface *" .Fn AG_ReadSurfaceFromPNG "AG_DataSource *ds" .Pp .Ft "AG_Surface *" .Fn AG_ReadSurfaceFromJPEG "AG_DataSource *ds" .Pp .Ft "AG_Surface *" .Fn AG_ReadSurfaceFromBMP "AG_DataSource *ds" .Pp .Ft "int" .Fn AG_WriteSurface "AG_DataSource *ds" "AG_Surface *surface" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceFromSDL "SDL_Surface *surface" .Pp .Ft "void" .Fn AG_SurfaceSetAddress "AG_Surface *surface" "Uint8 *p" .Pp .Ft "void" .Fn AG_SurfaceSetColors "AG_Surface *surface" "AG_Color *colors" "Uint offs" "Uint count" .Pp .Ft "void" .Fn AG_SurfaceSetPalette "AG_Surface *surface" "const AG_Palette *palette" .Pp .Ft "int" .Fn AG_SurfaceResize "AG_Surface *surface" "Uint w" "Uint h" .Pp .Ft void .Fn AG_SurfaceFree "AG_Surface *surface" .Pp .nr nS 0 .Fn AG_SurfaceNew allocates and initializes a new graphics surface of size .Fa w , .Fa h in pixels. The .Fa pf argument is the .Ft AG_PixelFormat describing the type of surface (Packed / Palettized / Grayscale), and the way pixels are to be encoded in memory (see .Sx PIXEL FORMATS ) . If .Fa pf is NULL, the .Va format field is left uninitialized (the caller can later use .Fn AG_PixelFormat* to initialize it). If the global variable .Va agSurfaceFmt is passed as .Va format then the "best" available mode (the one closest to the native display) will be selected. Acceptable values for .Fa type include: .Pp .Bl -tag -width "AG_SURFACE_GRAYSCALE " .It AG_SURFACE_PACKED .\" SYNC packed 8- or 16-bit RGBA components packed into 8-, 16-, 24-, 32-, 40-, 48- or 64-bit wide pixels. .It AG_SURFACE_INDEXED .\" SYNC indexed 1-, 2-, 4- or 8-bit per pixel palettized mode. .It AG_SURFACE_GRAYSCALE .\" SYNC grayscale 16- or 32-bit grayscale with alpha packed into 32- or 64-bit wide pixels. .El .Pp Acceptable .Fa flags include: .Bl -tag -width "AG_SURFACE_GL_TEXTURE " .It AG_SURFACE_COLORKEY Enable colorkeying. In .Fn AG_SurfaceBlit , inhibit the copy of all pixels matching the source surface's colorkey. .Fn AG_SurfaceSetColorKey controls this flag. .It 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 .Xr AG_GL_UploadTexture 3 , .Xr AG_GL_UpdateTexture 3 . .It AG_SURFACE_MAPPED Surface is attached to an .Xr AG_Widget 3 . Calls to .Xr AG_SurfaceFree 3 will result in a fatal assertion (Debug mode only). .El .Pp The .Fn AG_SurfaceEmpty function creates a new 0x0 pixel surface. Blitting such an empty surface is a no-op. .Pp .Fn AG_SurfaceIndexed creates a new surface of .Fa w by .Fa h pixels using an indexed pixel format with palette. The size of this palette is determined by .Fa 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. .Pp .Fn AG_SurfaceGrayscale creates a new surface of .Fa w by .Fa h pixels in a grayscale format with alpha channel. .Pp .Fn AG_SurfaceRGB and .Fn AG_SurfaceRGBA creates a new surface of .Fa w by .Fa h pixels using the specified packed-pixel format. In memory, pixels are encoded as contiguous blocks of .Fa BitsPerPixel bits, and the bitmasks specified in .Fa [RGB]mask are used to retrieve the individual 8-bit red, green, blue and alpha components. .Pp .Fn AG_SurfaceStdRGB and .Fn 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). .Pp .Fn AG_SurfaceFromPixelsRGB and .Fn AG_SurfaceFromPixelsRGBA create and initialize a new surface by copying existing pixel data in the given format. .Pp The .Fn AG_SurfaceFromFile routine loads the contents of an image file into a newly-allocated surface. The image format is auto-detected. The .Fn AG_SurfaceFrom{BMP,PNG,JPEG} variants will load an image only in the specified format. .Pp The .Fn AG_ReadSurface function reads an uncompressed surface (in native .Nm encoding). The .Fn AG_ReadSurfaceFrom{BMP,PNG,JPEG} variants will load an image only in the specified format. .Pp The .Fn AG_WriteSurface function saves the surface to the specified data source in native .Nm encoding. .Pp The .Fn AG_SurfaceFromSDL function converts a .Xr SDL_Surface 3 to a newly-allocated .Nm structure. This function is available only if Agar was compiled with SDL support. .Pp .Fn AG_SurfaceSetAddress sets the pixel data pointer of the surface to an external address. If .Fa p is NULL then revert to internally auto-allocated pixel data. .Pp .Fn AG_SurfaceSetColors sets contiguous entries in the colormap of a palettized surface from a given array of .Xr AG_Color 3 . .Pp .Fn AG_SurfaceSetPalette sets the entire colormap of a palettized surface from the given .Ft AG_Palette . .Pp .Fn 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. .Pp The .Fn AG_SurfaceFree function releases all resources allocated by the given surface. .Sh SURFACE OPERATIONS .nr nS 1 .Ft void .Fn AG_FillRect "AG_Surface *s" "const AG_Rect *r" "const AG_Color *c" .Pp .Ft void .Fn AG_SurfaceBlit "const AG_Surface *src" "const AG_Rect *rSrc" "AG_Surface *dst" "int x" "int y" .Pp .Ft void .Fn AG_SetClipRect "AG_Surface *s" "const AG_Rect *r" .Pp .Ft void .Fn AG_GetClipRect "const AG_Surface *s" "AG_Rect *r" .Pp .Ft int .Fn AG_SurfaceClipped "const AG_Surface *s" "int x" "int y" .Pp .Ft void .Fn AG_SurfaceCopy "AG_Surface *dest" "const AG_Surface *src" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceDup "const AG_Surface *src" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceConvert "const AG_Surface *src" "const AG_PixelFormat *newFmt" .Pp .Ft "AG_Surface *" .Fn AG_SurfaceScale "const AG_Surface *src" "Uint w" "Uint h" "Uint flags" .Pp .Ft "int" .Fn AG_SurfaceExportFile "const AG_Surface *su" "char *path" .Pp .Ft "int" .Fn AG_SurfaceExportPNG "const AG_Surface *su" "char *path" "Uint flags" .Pp .Ft "int" .Fn AG_SurfaceExportJPEG "const AG_Surface *su" "char *path" "Uint quality" "Uint flags" .Pp .Ft "int" .Fn AG_SurfaceExportBMP "const AG_Surface *su" "char *path" .Pp .Ft "SDL_Surface *" .Fn AG_SurfaceExportSDL "const AG_Surface *su" .Pp .nr nS 0 The .Fn AG_FillRect routine fills the rectangle .Fa r (or rather the intersection of .Fa r with the surface's clipping rectangle) against a color .Fa c . .Fn 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 .Fa c . .Pp .Fn AG_SurfaceBlit performs an image transfer from one surface (or rectangular region of pixels in a surface) to coordinates .Fa x , .Fa y in surface .Fa 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). .Pp .Fn AG_SetClipRect sets the clipping rectangle of surface .Fa s . The default clipping rectangle is (0, 0, s->w, s->h). The clipping rectangle is used by operations such as .Fn AG_SurfaceBlit and .Fn AG_FillRect , but it is ignored by functions which accept .Em unchecked coordinates, such as .Fn AG_SurfaceGet or .Fn AG_SurfacePut . .Pp The .Fn AG_SurfaceClipped test returns 1 if the pixel at .Fa x , .Fa y should be clipped away according to the clipping rectangle of .Fa s , otherwise it returns 0. .Pp .Fn AG_GetClipRect returns the current clipping rectangle of .Fa s . .Pp .Fn AG_SurfaceCopy copies the contents of surface .Fa src onto another, existing surface .Fa 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. .Pp .Fn AG_SurfaceDup returns a newly allocated surface containing a copy of .Fa src . .Pp .Fn AG_SurfaceConvert returns a newly allocated copy of the surface, but in the given format .Fa pf . Conversion is performed if the pixel formats differ. .Pp .Fn AG_SurfaceScale returns a copy of the surface .Fa src scaled to .Fa w by .Fa h pixels (or NULL if an error occurred). The .Fa flags argument is for future expansion and should be set to 0. .Pp The .Fn AG_SurfaceExportFile routine exports a surface to a specified image file. The image format will be determined by the filename extension in .Fa path . .Pp .Fn AG_SurfaceExportPNG exports a surface to a PNG image file, preserving any transparency data. Available .Fa flags options include: .Bl -tag -width "AG_EXPORT_PNG_ADAM7 " .It AG_EXPORT_PNG_ADAM7 Enable Adam7 interlacing. .El .Pp .Fn AG_SurfaceExportJPEG exports the surface to a file in JPEG format. If the surface has an alpha-channel, it is ignored. .Fa quality is given in percent (100% = best). Available .Fa flags options include: .Pp .Bl -tag -compact -width "AG_EXPORT_JPEG_JDCT_ISLOW " .It AG_EXPORT_JPEG_JDCT_ISLOW Slow, but accurate integer DCT method. .It AG_EXPORT_JPEG_JDCT_IFAST Fast, but less accurate integer DCT method. .It AG_EXPORT_JPEG_JDCT_FLOAT Floating-point DCT method. .El .Pp .Fn AG_SurfaceExportBMP exports a BMP image file from the contents of a surface. If the surface has an alpha-channel, it is ignored. .Pp .Fn AG_SurfaceExportSDL exports an Agar surface to a newly allocated .Ft 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. .\" MANLINK(AG_SurfaceMode) .\" MANLINK(AG_PixelFormat) .Sh PIXEL FORMATS The .Ft AG_PixelFormat structure describes how pixels are encoded in memory: .Bd -literal .\" SYNTAX(c) /* 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; .Pp .Ed .nr nS 1 .Ft "int" .Fn AG_PixelFormatIsSupported "AG_SurfaceMode mode" "int BitsPerPixel" .Pp .Ft "AG_Pixel" .Fn AG_PixelFormatMaximum "const AG_PixelFormat *pf" .Pp .Ft "void" .Fn AG_PixelFormatRGB "AG_PixelFormat *pf" "int BitsPerPixel" "AG_Pixel Rmask" "AG_Pixel Gmask" "AG_Pixel Bmask" .Pp .Ft "void" .Fn AG_PixelFormatRGBA "AG_PixelFormat *pf" "int BitsPerPixel" "AG_Pixel Rmask" "AG_Pixel Gmask" "AG_Pixel Bmask" "AG_Pixel Amask" .Pp .Ft "void" .Fn AG_PixelFormatIndexed "AG_PixelFormat *pf", "int BitsPerPixel" .Pp .Ft "void" .Fn AG_PixelFormatGrayscale "AG_PixelFormat *pf" "int BitsPerPixel" .Pp .Ft "int" .Fn AG_PixelFormatCompare "const AG_PixelFormat *pf1" "const AG_PixelFormat *pf2" .Pp .Ft "void" .Fn AG_PixelFormatFree "AG_PixelFormat *format" .Pp .nr nS 0 The .Fn AG_PixelFormatIsSupported function returns 1 if the given combination of encoding and bits per pixel is supported by the present Agar build. .Pp The .Fn AG_PixelFormatMaximum function returns the maximum pixel value representible by surfaces in the given format .Fa pf . .Pp The .Fn AG_PixelFormatRGB and .Fn AG_PixelFormatRGBA routines initialize an .Ft AG_PixelFormat structure describing a surface in .Em packed-pixel format of depth .Fa BitsPerPixel . The arguments .Fa [RGBA]mask specify the bitmasks used to extract individual color components (and alpha) from the surface in memory. .Pp The .Fn AG_PixelFormatIndexed routine initializes an .Ft AG_PixelFormat structure describing a surface in .Em indexed format. Agar considers the palette to be part of the .Ft AG_PixelFormat structure so the palette itself is allocated as well. The size of this palette is determined by .Fa BitsPerPixel and palette entries are initialized to black (except in the 1bpp case, where entry 0 is also initialized to white). .Pp The .Fn AG_PixelFormatGrayscale routine initializes an .Ft AG_PixelFormat structure describing a surface in .Em 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 .Va agGrayscaleMode determines the default conversion standard to use when converting between grayscale and RGB. The default is .Dv AG_GRAYSCALE_BT709 . .Pp .Fn 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. .Pp .Fn AG_PixelFormatFree frees all resources allocated by an .Ft AG_PixelFormat . .Sh PIXEL ACCESS .nr nS 1 .Ft "AG_Pixel" .Fn AG_SurfaceGet "const AG_Surface *s" "int x" "int y" .Pp .Ft "Uint8" .Fn AG_SurfaceGet8 "const AG_Surface *s" "int x" "int y" .Pp .Ft "Uint32" .Fn AG_SurfaceGet32 "const AG_Surface *s" "int x" "int y" .Pp .Ft "Uint64" .Fn AG_SurfaceGet64 "const AG_Surface *s" "int x" "int y" .Pp .Ft "AG_Pixel" .Fn AG_SurfaceGet_At "const AG_Surface *s" "Uint8 *p" .Pp .Ft "Uint32" .Fn AG_SurfaceGet32_At "const AG_Surface *s" "const Uint8 *p" .Pp .Ft "Uint64" .Fn AG_SurfaceGet64_At "const AG_Surface *s" "const Uint8 *p" .Pp .Ft "void" .Fn AG_SurfacePut "AG_Surface *s" "int x" "int y" "AG_Pixel px" .Pp .Ft "void" .Fn AG_SurfacePut8 "AG_Surface *s" "int x" "int y" "Uint8 px" .Pp .Ft "void" .Fn AG_SurfacePut32 "AG_Surface *s" "int x" "int y" "Uint32 px" .Pp .Ft "void" .Fn AG_SurfacePut64 "AG_Surface *s" "int x" "int y" "Uint64 px" .Pp .Ft "void" .Fn AG_SurfacePut_At "AG_Surface *s" "Uint8 *p" "AG_Pixel px" .Pp .Ft "void" .Fn AG_SurfacePut32_At "AG_Surface *s" "Uint8 *p" "Uint32 px" .Pp .Ft "void" .Fn AG_SurfacePut64_At "AG_Surface *s" "Uint8 *p" "Uint64 px" .Pp .Ft "void" .Fn AG_SurfaceBlend "AG_Surface *s" "int x" "int y" "const AG_Color *c" .Pp .Ft "void" .Fn AG_SurfaceBlend_At "AG_Surface *s" "Uint8 *p" "const AG_Color *c" .Pp .Ft "void" .Fn AG_SurfaceBlendRGB8 "AG_Surface *s" "int x" "int y" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft "void" .Fn AG_SurfaceBlendRGB8_At "AG_Surface *s" "Uint8 *p" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft "void" .Fn AG_SurfaceBlendRGB16 "AG_Surface *s" "int x" "int y" "Uint16 r" "Uint16 g" "Uint16 b" "Uint16 a" .Pp .Ft "void" .Fn AG_SurfaceBlendRGB16_At "AG_Surface *s" "Uint8 *p" "Uint16 r" "Uint16 g" "Uint16 b" "Uint16 a" .Pp .Ft void .Fn AG_GetColor "AG_Color *dst" "AG_Pixel px" "const AG_PixelFormat *pf" .Pp .Ft void .Fn AG_GetColor32 "AG_Color *dst" "Uint32 px" "const AG_PixelFormat *pf" .Pp .Ft void .Fn AG_GetColor64 "AG_Color *dst" "Uint64 px" "const AG_PixelFormat *pf" .Pp .Ft void .Fn AG_GetColor_RGB8 "AG_Pixel px" "const AG_PixelFormat *pf" "Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a" .Pp .Ft void .Fn AG_GetColor_RGB16 "AG_Pixel px" "const AG_PixelFormat *pf" "Uint16 *r" "Uint16 *g" "Uint16 *b" "Uint16 *a" .Pp .Ft void .Fn AG_GetColor32_RGB8 "Uint32 px" "const AG_PixelFormat *pf" "Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a" .Pp .Ft void .Fn AG_GetColor32_RGB16 "Uint32 px" "const AG_PixelFormat *pf" "Uint16 *r" "Uint16 *g" "Uint16 *b" "Uint16 *a" .Pp .Ft void .Fn AG_GetColor64_RGB8 "Uint64 px" "const AG_PixelFormat *pf" "Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a" .Pp .Ft void .Fn AG_GetColor64_RGB16 "Uint64 px" "const AG_PixelFormat *pf" "Uint16 *r" "Uint16 *g" "Uint16 *b" "Uint16 *a" .Pp .Ft AG_Pixel .Fn AG_MapPixel "const AG_PixelFormat *pf" "const AG_Color *c" .Pp .Ft Uint32 .Fn AG_MapPixel32 "const AG_PixelFormat *pf" "const AG_Color *c" .Pp .Ft Uint64 .Fn AG_MapPixel64 "const AG_PixelFormat *pf" "const AG_Color *c" .Pp .Ft AG_Pixel .Fn AG_MapPixel_RGB8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft AG_Pixel .Fn AG_MapPixel_RGB8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft AG_Pixel .Fn AG_MapPixel_RGB16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" .Pp .Ft AG_Pixel .Fn AG_MapPixel_RGBA16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" "Uint16 a" .Pp .Ft Uint32 .Fn AG_MapPixel32_RGB8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft Uint32 .Fn AG_MapPixel32_RGBA8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft Uint32 .Fn AG_MapPixel32_RGB16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" .Pp .Ft Uint32 .Fn AG_MapPixel32_RGBA16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" "Uint16 a" .Pp .Ft Uint64 .Fn AG_MapPixel64_RGB8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" .Pp .Ft Uint64 .Fn AG_MapPixel64_RGBA8 "const AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" .Pp .Ft Uint64 .Fn AG_MapPixel64_RGB16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" .Pp .Ft Uint64 .Fn AG_MapPixel64_RGBA16 "const AG_PixelFormat *pf" "Uint16 r" "Uint16 g" "Uint16 b" "Uint16 a" .Pp .nr nS 0 .Fn AG_SurfaceGet8 returns the value (color index) of the pixel at unchecked coordinates .Fa x , .Fa y in an 1- to 8-bpp indexed surface .Fa s . .Pp .Fn AG_SurfaceGet32 returns a 32-bit representation of the pixel at unchecked coordinates .Fa x , .Fa y in a 1- to 64-bpp surface .Fa s . If the given surface is more than 32-bpp, .Fn AG_SurfaceGet32 returns a compressed 32-bit approximation. The .Fn AG_SurfaceGet32_At form returns a 32-bit representation of the pixel at address .Fa p in an 8- to 64-bpp surface .Fa s . .Pp .Fn AG_SurfaceGet64 returns a 64-bit representation of the pixel at unchecked coordinates .Fa x , .Fa y in an 1- to 64-bpp surface .Fa s . The .Fn AG_SurfaceGet64_At form returns a 64-bit representation of the pixel at address .Fa p in an 8- to 64-bpp surface .Fa s . .Pp The .Fn AG_SurfacePut8 procedure writes to the pixel at .Fa x , .Fa y in a 1- to 8-bpp indexed surface .Fa s . .Pp .Fn AG_SurfacePut32 writes to the pixel at unchecked coordinates .Fa x , .Fa y in a 1- to 64- surface .Fa s . If the given surface is more than 32-bpp, .Fn AG_SurfacePut32 writes a decompressed value. The .Fn AG_SurfacePut32_At form writes to the pixel at address .Fa p in an 8- to 64-bpp surface .Fa s . .Pp .Fn AG_SurfacePut64 writes to the pixel at unchecked coordinates .Fa x , .Fa y in a 1- to 64-bpp surface .Fa s . The .Fn AG_SurfacePut64_At form writes to the pixel at address .Fa p in an 8- to 64-bpp surface .Fa s . .Pp The .Fn AG_SurfaceBlend routine blends the color .Fa c against the pixel at unchecked coordinates .Fa x , .Fa y in a surface .Fa s . .Pp The .Fn AG_SurfaceBlend_At variant performs alpha blending of a color .Fa c against the pixel at byte address .Fa p in surface .Fa s . .Pp The .Fn AG_SurfaceBlendRGB{8,16} and .Fn AG_SurfaceBlendRGB{8,16}_At forms accept discrete 8- and 16-bit components instead of an .Xr AG_Color 3 . .Pp .Fn AG_GetColor32 extracts RGBA components from a 32-bit pixel in specified format and returns the corresponding .Xr AG_Color 3 into .Fa dst . The procedural forms .Fn AG_GetColor32_RGB{8,16} , return the color components into separate arguments. .Pp .Fn AG_GetColor64 extracts RGBA components from a 64-bit pixel in specified format and returns the corresponding .Xr AG_Color 3 . The procedural forms .Fn AG_GetColor64_RGB{8,16} return the color components into separate arguments. .Pp .Fn AG_MapPixel32 returns a 32-bit representation of the color .Fa c . The .Fn AG_MapPixel32_RGB{8,16} forms accept individual components as separate arguments. .Pp .Fn AG_MapPixel64 returns a 64-bit representation of the color .Fa c . The .Fn AG_MapPixel64_RGB{8,16} forms accept individual components as separate arguments. .Sh STRUCTURE DATA For the .Ft AG_Surface structure: .Pp .Bl -tag -compact -width "AG_PixelFormat format " .It Ft AG_PixelFormat format Pixel encoding format (see .Sx PIXEL FORMATS ) . .It Ft Uint flags Option flags (see .Sx INITIALIZATION ) . .It Ft Uint w, h Dimensions of the surface in pixels. .It Ft Uint8 *pixelsBase Base address of pixel data (read-only; modifiable by calling .Fn AG_SurfaceSetAddress ) . .It Ft Uint8 *pixels Current pointer to pixel data. Can be incremented in order to crop lines off the top. .It Ft Uint pitch Total size of a scanline in bytes. .It Ft Uint padding Scanline end padding in bytes. Increment (and also decrement .Va w ) to crop lines off the right. Used to align rows to a 32- or 64-bit boundary. .It Ft Uint Lpadding Scanline start padding in bytes. Increment (and also decrement .Va w ) to crop lines off the left. .It Ft AG_Rect clipRect Clipping rectangle (default = whole surface). .It Ft AG_Pixel colorkey Transparency color key (for .Dv AG_SURFACE_COLORKEY ) . .It Ft Uint alpha Per-surface alpha (overall; .Fa AG_Component value). .El .Sh SEE ALSO .Xr AG_Intro 3 , .Xr AG_Color 3 , .Xr AG_Rect 3 .Sh HISTORY The .Nm structure first appeared in Agar 1.3.3. It was first modeled after the .Ft 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 .Fn AG_SurfaceSetAddress , .Fn AG_SurfaceSetColors and .Fn AG_SurfaceSetPalette routines. Agar 1.7.0 added support for 40-bit color, optimized blitters, optimized rectangle fills and fast cropping. The .Va pixelsBase pointer, the .Va Lpadding member as well as the ability to modify the .Va pixels pointer appeared in Agar 1.7.0.