FreeBSD Manual Pages
AG_SURFACE(3) BSD Library Functions Manual AG_SURFACE(3) NAME AG_Surface -- agar graphics surface SYNOPSIS #include <agar/core.h> #include <agar/gui.h> DESCRIPTION The AG_Surface structure describes a raster-based software graphics sur- face. It supports all packed pixel formats which encode pixels in 32-bit or less and allow components to be retrieved by bitmasks. Indexed (or `palletized') pixel formats up to 8-bit per pixel are also supported. AG_Surface supports colorkey and alpha-blending (with an alpha channel or per-surface alpha setting). Surfaces may define destination clipping rectangles for operations such as AG_SurfaceBlit(). INITIALIZATION AG_Surface * AG_SurfaceNew(enum ag_surface_type type, Uint w, Uint h, const AG_PixelFormat *fmt, Uint flags) AG_Surface * AG_SurfaceEmpty(void) AG_Surface * AG_SurfaceStdRGB(Uint w, Uint h) AG_Surface * AG_SurfaceStdRGBA(Uint w, Uint h) AG_Surface * AG_SurfaceIndexed(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_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_SurfaceSetPalette(AG_Surface *su, AG_Color *colors, Uint offs, Uint count) int AG_SurfaceResize(AG_Surface *surface, Uint w, Uint h) void AG_SurfaceFree(AG_Surface *surface) The AG_SurfaceNew() function allocates and initializes a new AG_Surface of the specified dimensions w, h (given in pixels). fmt is a pointer to a AG_PixelFormat structure describing the way pixels are to be encoded in memory (see PIXEL FORMATS section below). The pixel data is left unini- tialized. Acceptable values for type include: AG_SURFACE_PACKED Packed-pixel format (e.g., RGBA) AG_SURFACE_INDEXED Color-index format (per-surface palette) Acceptable flags include: AG_SRCCOLORKEY Enable colorkeying. In AG_SurfaceBlit(), this op- tion inhibits the copy of all pixels matching the source surface's colorkey setting. AG_SurfaceSetColorKey() controls this flag. AG_SRCALPHA Enable alpha blending. In AG_SurfaceBlit(), this option enables blending of pixels in the source and destination surfaces based on the alpha compo- nent of the source pixel. AG_SetAlpha() controls this flag. AG_SURFACE_GLTEXTURE Surface is suitable to be uploaded directly as an OpenGL texture without format conversion. This flag is recognized by AG_GL_UploadTexture(3) and AG_GL_UpdateTexture(3). The AG_SurfaceEmpty() function creates a new 0x0 pixel surface. Blitting such an empty surface is a no-op. AG_SurfaceStdRGB() and AG_SurfaceStdRGBA() create a surface in the recom- mended `standard' format, as determined by Agar on initialization time. Usually, this is a packed-pixel format with an alpha component. The AG_SurfaceIndexed() function creates a new surface of w by h pixels using indexed pixel format. This involves the allocation of a palette. The size of this palette is determined by bitsPerPixel. All entries in the palette are initialized to black, except in the 2-bpp case, where color 0 is initialized to white and color 1 is initialized to black. The AG_SurfaceRGB() function creates a new surface of w by h pixels using the specified packed-pixel format. In memory, pixels are encoded as con- tiguous blocks of bitsPerPixel bits, and the bitmasks specified in [RGB]mask are used to retrieve the individual red, green and blue compo- nents. The AG_SurfaceRGBA() variant adds an alpha-channel component and implicitely sets the AG_SRCALPHA flag (see AG_SurfaceBlit(3)). AG_SurfaceFromPixelsRGB() and AG_SurfaceFromPixelsRGBA() create a new surface from existing pixel data in the specified format. The AG_SurfaceFromPixelsRGBA() function also sets the AG_SRCALPHA flag. The AG_SurfaceStdGL() function creates a surface in an optimal format for OpenGL textures (packed, 32 bits per pixel with native RGB masks). It also sets the AG_SURFACE_GLTEXTURE 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-al- located AG_Surface structure. This function is available only if Agar was compiled with SDL support. The AG_SurfaceSetPalette() function copies count color entries from the colors array, to count slots (starting at offs) in the palette of indexed surface su. AG_SurfaceResize() attempts to resize a surface to the specified dimen- sions. 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 rec- tangle 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, 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) 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) int AG_ScaleSurface(const AG_Surface *src, Uint16 width, Uint16 height, AG_Surface **dst) void AG_SetAlphaPixels(AG_Surface *surface, Uint8 alpha) 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 with the specified color. If the target surface has an alpha channel, the alpha component is copied as-is. If the rectangle lies outside of the surface's clipping rectan- gle, it is clipped accordingly. AG_SurfaceBlit() copies the contents of a surface (or a region within a surface if rSrc is non-NULL), to a given target position x, y within sur- face dst. The clipping rectangle of dst (see below) applies. AG_SetClipRect() sets the clipping rectangle of the surface. The clip- ping rectangle will apply to surface operations such as AG_SurfaceBlit(), as well as pixel manipulation macros which perform clipping tests ( AG_PUT_PIXEL2_CLIPPED(), AG_BLEND_RGBA2_CLIPPED()). AG_GetClipRect() re- turns the current clipping rectangle of a surface. If the source or des- tination rectangles lie outside of the surface area, they are clipped ac- cordingly. The AG_SurfaceCopy() function copies the contents of surface src onto an- other, existing surface dst. The raw pixel data is copied, so alpha and colorkey parameters are ignored. Clipping is done if the surfaces have different sizes. AG_SurfaceDup() returns a newly allocated surface containing a copy of src. If there is insufficient memory, AG_SurfaceDup() will fail return- ing NULL. The source surface must be locked (src->lock). AG_SurfaceConvert() is similar to AG_SurfaceDup(), except that the sur- face is converted to the specified pixel format newFmt. AG_ScaleSurface() returns a copy of surface src scaled to the given size in pixels into dst, which must be either NULL or a pointer to an existing surface. If dst is NULL, a new surface is allocated. If there is insuf- ficient memory for the rescaled surface, AG_ScaleSurface() will fail re- turning -1. The AG_SetAlphaPixels() function changes the alpha component of all pix- els with a non-zero alpha component. 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(3). This function is available only if Agar was compiled with SDL support. PIXEL FORMATS AG_PixelFormat * AG_PixelFormatRGB(Uint8 bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask) AG_PixelFormat * AG_PixelFormatRGBA(Uint8 bitsPerPixel, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask) AG_PixelFormat * AG_PixelFormatIndexed(Uint8 bitsPerPixel) int AG_PixelFormatCompare(const AG_PixelFormat *pf1, const AG_PixelFormat *pf2) void AG_PixelFormatFree(AG_PixelFormat *format) The AG_PixelFormat structure describes a general indexed or packed-pixel surface format. It is defined as follows: typedef struct ag_pixel_format { AG_Palette *palette; /* For indexed formats */ Uint8 BitsPerPixel; /* Depth (bits/pixel) */ Uint8 BytesPerPixel; /* Depth (bytes/pixel) */ Uint8 Rloss, Gloss, Bloss, Aloss; Uint8 Rshift, Gshift, Bshift, Ashift; Uint32 Rmask, Gmask, Bmask, Amask; Uint32 colorkey; /* Color key pixel */ Uint8 alpha; /* Per-surface alpha value */ } AG_PixelFormat; 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 indi- vidual 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 entry is initialized to white (255,255,255) and the second entry to black (0,0,0). If no memory is available, AG_PixelFormat*() fail returning NULL. 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() releases all resources allocated by an AG_PixelFormat structure. PACKED-PIXEL SURFACE OPERATIONS The following routines operate on surfaces in packed-pixel format exclu- sively. Uint32 AG_GET_PIXEL(const AG_Surface *s, const Uint8 *p) Uint32 AG_GET_PIXEL2(const AG_Surface *s, int x, int y) void AG_PUT_PIXEL(AG_Surface *s, Uint8 *p, Uint32 c) void AG_PUT_PIXEL2(AG_Surface *s, int x, int y, Uint32 c) void AG_BLEND_RGBA(AG_Surface *s, Uint8 *p, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func) void AG_BLEND_RGBA2(AG_Surface *s, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func) void AG_SurfaceBlendPixel(AG_Surface *s, Uint8 *p, AG_Color C, AG_BlendFn fn) void AG_PUT_PIXEL2_CLIPPED(AG_Surface *s, int x, int y, Uint32 c) void AG_BLEND_RGBA2_CLIPPED(AG_Surface *s, int x, int y, Uint8 r, Uint8 g, Uint8 b, Uint8 a, enum ag_blend_func func) void AG_GetPixelRGB(Uint32 pixel, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b) void AG_GetPixelRGBA(Uint32 pixel, const AG_PixelFormat *pf, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a) Uint32 AG_MapPixelRGB(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uing8 b) Uint32 AG_MapPixelRGBA(const AG_PixelFormat *pf, Uint8 r, Uint8 g, Uing8 b, Uint8 a) AG_Color AG_GetColorRGB(Uint32 pixel, const AG_PixelFormat *pf) AG_Color AG_GetColorRGBA(Uint32 pixel, const AG_PixelFormat *pf) Uint32 AG_MapColorRGB(const AG_PixelFormat *pf, AG_Color color) Uint32 AG_MapColorRGBA(const AG_PixelFormat *pf, AG_Color color) The AG_GET_PIXEL() macro returns a packed 32-bit representation of the pixel at the given location p in the surface s. AG_GET_PIXEL2() variant locates the pixel in the surface using x,y coordinates. The AG_PUT_PIXEL() and AG_PUT_PIXEL2() write the color c to the pixel at the given location. The AG_BLEND_RGBA() and AG_BLEND_RGBA2() routines perform alpha-blending of the destination pixel against the specified color, where func speci- fies the blending formula (see AG_BlendFn(3)). The AG_SurfaceBlendPixel() function accepts an AG_Color(3) argument and per- forms no clipping tests. The AG_PUT_PIXEL2_CLIPPED() and AG_BLEND_RGBA2_CLIPPED() variants of these macros first tests the given coordinates against the clipping rec- tangle of the surface (see AG_SetClipRect(3)). If the pixel lies outside of the rectangle, the operation is a no-op. The AG_GetPixelRGB() and AG_GetPixelRGBA() functions extract the RGB / RGBA components of a pixel value pixel, in pixel format pf. The AG_MapPixelRGB() and AG_MapPixelRGBA() functions perform the inverse op- eration, returning the pixel value (in pixel format pf) for the specified RGB / RGBA component values. The AG_GetColor*() and AG_MapColor*() functions are equivalent to AG_GetPixel*() and AG_MapPixel*() except that they accept AG_Color(3) ar- guments instead of separate component values. Note that the preceding routines are only for use against surfaces in packed RGB/RGBA pixel formats. Passing a color-index format to AG_GetPixel*(), AG_GetColor*(), AG_MapPixel*() or AG_MapColor*() is an illegal operation. STRUCTURE DATA For the AG_Surface structure: Uint flags Current surface flags (read-only; see INITIALIZATION section). AG_PixelFormat *format The surface's pixel encoding (read-only; see PIXEL FORMATS section). int w, h Dimensions of the surface in pixels (read-only). void *pixels Pointer to raw pixel data (4-byte aligned) Uint pitch Size of a scanline in bytes. Uint padding Scanline padding in bytes. SEE ALSO AG_Anim(3), AG_Intro(3), AG_Rect(3) HISTORY The AG_Surface structure first appeared in Agar 1.3.3. It is modeled af- ter the SDL_Surface of SDL: http://libsdl.org/ BSD April 21, 2008 BSD
NAME | SYNOPSIS | DESCRIPTION | INITIALIZATION | SURFACE OPERATIONS | PIXEL FORMATS | PACKED-PIXEL SURFACE OPERATIONS | STRUCTURE DATA | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Surface&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>