Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
AG_SURFACE(3)	       FreeBSD 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/

FreeBSD	13.0			April 21, 2008			  FreeBSD 13.0

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://www.freebsd.org/cgi/man.cgi?query=AG_Surface&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help