.\" Copyright (c) 2006-2007 Hypertriton, Inc. <http://hypertriton.com/>
.\" 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 April 21, 2008
.Dt AG_SURFACE 3
.Os
.ds vT Agar API Reference
.ds oS Agar 1.3
.Sh NAME
.Nm AG_Surface
.Nd agar graphic surface
.Sh SYNOPSIS
.Bd -literal
#include <agar/core.h>
#include <agar/gui.h>
.Ed
.Sh DESCRIPTION
The
.Nm
structure is a basic raster graphics surface.
It supports all
.Em packed
pixel formats which encode pixels in 32-bit or less and allow components to be
retrieved via masks.
.Em Indexed
(or
.Sq palletized )
pixel formats up to 8-bit per pixel are also supported.
.Pp
Additional features of
.Nm
include clipping tests, colorkey and alpha-blending with per-pixel and/or
per-surface alpha.
.Sh INITIALIZATION
.nr nS 1
.Ft "AG_Surface *"
.Fn AG_SurfaceNew "Uint w" "Uint h" "AG_PixelFormat *fmt" "Uint flags"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceEmpty "void"
.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_SurfaceVideoRGB "Uint w" "Uint h"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceVideoRGBA "Uint w" "Uint h"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceIndexed "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_SurfaceFromPixelsRGB "void *pixels" "Uint w" "Uint h" "int bitsPerPixel" "int pitch" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceFromPixelsRGBA "void *pixels" "Uint w" "Uint h" "int bitsPerPixel" "int pitch" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" "Uint32 Amask"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceFromBMP "const char *path"
.Pp
.Ft "AG_Surface *"
.Fn AG_SurfaceFromSDL "SDL_Surface *surface"
.Pp
.Ft void
.Fn AG_SurfaceFree "AG_Surface *surface"
.Pp
.nr nS 0
The
.Fn AG_SurfaceNew
function allocates and initializes a new
.Nm
of the specified dimensions
.Fa w ,
.Fa h
(given in pixels).
.Fa fmt
is a pointer to a
.Ft AG_PixelFormat
structure describing the way pixels are to be encoded in memory (see
.Dq PIXEL FORMATS
section below).
Acceptable
.Fa flags
include:
.Bl -tag -width "AG_SRCCOLORKEY "
.It AG_HWSURFACE
Under some platforms, it is possible to perform accelerated copies between two
surfaces in video memory.
This flag advises that the surface should be created in video memory.
.It AG_SRCCOLORKEY
Enable colorkeying.
During blit operations, colorkeying inhibits the copy of all pixels matching
the colorkey value of the source surface.
The
.Fn AG_SetColorKey
function also sets or clears this flag.
.It AG_SRCALPHA
Enable alpha blending.
During blit operations, this flag enables blending of pixels in the source
and destination surfaces based on the alpha component of the source pixel.
.Fn AG_SetAlpha
function also sets or clears this flag.
.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_SurfaceStdRGB
and
.Fn AG_SurfaceStdRGBA
create a surface in the recommended
.Sq standard
format, as determined by Agar on initialization time.
Usually, this is a packed-pixel format with an alpha component.
.Pp
.Fn AG_SurfaceVideoRGB
and
.Fn AG_SurfaceVideoRGBA
create a surface with the same depth and masks as the current video display.
If the current display mode is not raster-based, the Agar
.Sq standard
format is used instead.
.Pp
The
.Fn AG_SurfaceIndexed
function creates a new surface of
.Fa w
by
.Fa h
pixels using indexed pixel format.
This involves the allocation of a palette.
The size of this palette is determined by
.Fa 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.
.Pp
The
.Fn AG_SurfaceRGB
function 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 red, green and blue components.
The
.Fn AG_SurfaceRGBA
variant adds an alpha-channel component.
.Pp
.Fn AG_SurfaceFromPixelsRGB 
and
.Fn AG_SurfaceFromPixelsRGBA
create a new surface from existing pixel data in the specified format.
.Pp
.Fn AG_SurfaceFromBMP
loads the contents of a .bmp file into a new surface.
.Pp
If Agar was compiled with
.Dv HAVE_SDL ,
the
.Fn AG_SurfaceFromSDL
function converts a
.Xr SDL_Surface 3
to a newly-allocated
.Nm
structure.
.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" "Uint32 c"
.Pp
.Ft void
.Fn AG_SurfaceBlit "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 "AG_Surface *s" "AG_Rect *r"
.Pp
.Ft void
.Fn AG_SurfaceCopy "AG_Surface *dest" "AG_Surface *src"
.Pp
.Ft void
.Fn AG_SurfaceLock "AG_Surface *surface"
.Pp
.Ft void
.Fn AG_SurfaceUnlock "AG_Surface *surface"
.Pp
.Ft "AG_Surface *"
.Fn AG_DupSurface "AG_Surface *src"
.Pp
.Ft "int"
.Fn AG_ScaleSurface "AG_Surface *src" "Uint16 width" "Uint16 height" "AG_Surface **dst"
.Pp
.Ft "Uint32"
.Fn AG_VideoPixel "Uint32 c"
.Pp
.Ft "Uint32"
.Fn AG_SurfacePixel "Uint32 c"
.Pp
.Ft "int"
.Fn AG_SamePixelFmt "AG_Surface *s1" "AG_Surface *s2"
.Pp
.Ft "void"
.Fn AG_SetAlphaPixels "AG_Surface *surface" "Uint8 alpha"
.Pp
.Ft "int"
.Fn AG_DumpSurface "AG_Surface *su" "char *path_save"
.Pp
.nr nS 0
.Pp
The
.Fn AG_FillRect
routine fills the specified rectangle
.Fa r
with pixels
.Fa c .
.Pp
.Fn AG_SurfaceBlit
copies the contents of a surface (or a region within a surface if
.Fa rSrc
is non-NULL), to a given target position
.Fa x ,
.Fa y
within surface
.Fa dst .
The clipping rectangle of
.Fa dst
(see below) applies.
.Pp
.Fn AG_SetClipRect
sets the clipping rectangle of the surface.
The clipping rectangle will apply to surface operations such as
.Fn AG_SurfaceBlit ,
as well as pixel manipulation macros which perform clipping tests (
.Fn AG_PUT_PIXEL2_CLIPPED ,
.Fn AG_BLEND_RGBA2_CLIPPED ) .
.Fn AG_GetClipRect
returns the current clipping rectangle of a surface.
.Pp
The
.Fn AG_SurfaceCopy
function copies the contents of surface
.Fa src
onto
.Fa dst .
The raw pixel data is copied, so alpha and colorkey parameters are ignored.
.Pp
.Fn AG_SurfaceLock
and
.Fn AG_SurfaceUnlock
protect the raw pixel data against both reading and writing.
.Pp
.Fn AG_DupSurface
returns a newly allocated surface containing a copy of
.Fa src .
.Pp
.Fn AG_ScaleSurface
returns a copy of surface
.Fa src
scaled to the given size in pixels into
.Fa dst ,
which must be either NULL or a pointer to an existing surface.
If
.Fa dst
is NULL, a new surface is allocated.
.Fn AG_ScaleSurface
can fail and return -1 if there is insufficient memory to hold the
rescaled surface.
.Pp
The
.Fn AG_VideoPixel
routine converts the given pixel value
.Fa c
from reference surface format (agSurfaceFmt) to video display
format (agVideoFmt).
.Fn AG_SurfacePixel
does the opposite.
.Pp
.Fn AG_SamePixelFmt
compares the two surfaces
.Fa s1
and
.Fa s2
and return 1 if they both share the same color depth, RGBA masks and colorkey
settings.
.Pp
The
.Fn AG_SetAlphaPixels
function changes the alpha component of all pixels with a non-zero alpha
component.
.Pp
The
.Fn AG_DumpSurface
function encodes a JPEG image file from the contents of a specified surface
.Fa su
(or if
.Fa su
is NULL, it uses the contents of the current display).
The image is saved to the application's data directory, and the resulting
path is copied to the
.Fa path_save
argument (if not NULL),
which must be at least
.Dv AG_PATHNAME_MAX
bytes in size.
.Sh PIXEL FORMATS
.nr nS 1
.Ft "AG_PixelFormat *"
.Fn AG_PixelFormatRGB "Uint8 bitsPerPixel" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask"
.Pp
.Ft "AG_PixelFormat *"
.Fn AG_PixelFormatRGBA "Uint8 bitsPerPixel" "Uint32 Rmask" "Uint32 Gmask" "Uint32 Bmask" "Uint32 Amask"
.Pp
.Ft "AG_PixelFormat *"
.Fn AG_PixelFormatIndexed "Uint8 bitsPerPixel"
.Pp
.Ft "void"
.Fn AG_PixelFormatFree "AG_PixelFormat *format"
.Pp
.nr nS 0
The
.Fn AG_PixelFormatRGB
and
.Fn AG_PixelFormatRGBA
functions allocate a new structure describing packed-pixel encoding with RGB
or RGBA components.
The
.Fa [RGBA]mask
arguments specify the bitmasks used to retrieve the individual components from
memory.
.Pp
.Fn 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
.Fa 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).
.Sh PIXEL OPERATIONS
.nr nS 1
.Ft "Uint32"
.Fn AG_GET_PIXEL "AG_Surface *s" "Uint8 *p"
.Pp
.Ft "Uint32"
.Fn AG_GET_PIXEL2 "AG_Surface *s" "int x" "int y"
.Pp
.Ft "void"
.Fn AG_PUT_PIXEL "AG_Surface *s" "Uint8 *p" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_PUT_PIXEL2 "AG_Surface *s" "int x" "int y" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_BLEND_RGBA "AG_Surface *s" "Uint8 *p" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" "enum ag_blend_func func"
.Pp
.Ft "void"
.Fn AG_BLEND_RGBA2 "AG_Surface *s" "int x" "int y" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" "enum ag_blend_func func"
.Pp
.Ft "void"
.Fn AG_PUT_PIXEL2_CLIPPED "AG_Surface *s" "int x" "int y" "Uint32 c"
.Pp
.Ft "void"
.Fn AG_BLEND_RGBA2_CLIPPED "AG_Surface *s" "int x" "int y" "Uint8 r" "Uint8 g" "Uint8 b" "Uint8 a" "enum ag_blend_func func"
.Pp
.Ft void
.Fn AG_GetRGB "Uint32 pixel" "AG_PixelFormat *pf" "Uint8 *r" "Uint8 *g" "Uint8 *b"
.Pp
.Ft void
.Fn AG_GetRGBA "Uint32 pixel" "AG_PixelFormat *pf" "Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a"
.Pp
.Ft Uint32
.Fn AG_MapRGB "AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uing8 b"
.Pp
.Ft Uint32
.Fn AG_MapRGBA "AG_PixelFormat *pf" "Uint8 r" "Uint8 g" "Uing8 b" "Uint8 a"
.Pp
.nr nS 0
The
.Fn AG_GET_PIXEL
macro returns a 32-bit interpretation of the pixel at the given location
.Fa p
in the pixel data of the surface
.Fa s .
.Fn AG_GET_PIXEL2
variant locates the pixel in the surface using the specified coordinates.
.Pp
The
.Fn AG_PUT_PIXEL
and
.Fn AG_PUT_PIXEL2
write the color
.Fa c
to the pixel at the given location.
.Pp
The
.Fn AG_BLEND_RGBA
and
.Fn AG_BLEND_RGBA2
variants perform alpha-blending of the destination pixel against the
specified color, where
.Fa func
specifies the blending formula:
.Pp
.Bd -literal
enum ag_blend_func {
	AG_ALPHA_OVERLAY,		/* dA = sA+dA */
	AG_ALPHA_SRC,			/* dA = sA */
	AG_ALPHA_DST,			/* dA = dA */
	AG_ALPHA_ONE_MINUS_DST,		/* dA = 1-dA */
	AG_ALPHA_ONE_MINUS_SRC		/* dA = 1-sA */
};
.Ed
.Pp
The
.Fn AG_PUT_PIXEL2_CLIPPED
and
.Fn AG_BLEND_RGBA2_CLIPPED
variants of these macros first tests the given coordinates against the
current clipping rectangle of the surface, as previously set with
.Xr AG_SetClipRect 3 .
If the pixel lies outside of the rectangle, the operation is a no-op.
.Sh STRUCTURE DATA
For the
.Ft AG_Surface
structure:
.Pp
.Bl -tag -width "AG_PixelFormat *format "
.It Ft Uint flags
Current surface flags (read-only; see
.Dq INITIALIZATION
section).
.It Ft AG_PixelFormat *format
The surface's pixel encoding (read-only; see
.Dq PIXEL FORMATS
section).
.It Ft int w, h
Dimensions of the surface in pixels (read-only).
.It Ft void *pixels
Pointer to raw pixel data (must invoke
.Fn AG_SurfaceLock
prior to reading or writing this data, and
.Fn AG_SurfaceUnlock
when done).
.El
.Sh SEE ALSO
.Xr AG_Intro 3 ,
.Xr AG_Rect 3 ,
.Xr AG_Widget 3
.Sh HISTORY
The
.Nm
structure first appeared in Agar 1.3.3.
It is modeled after the
.Ft SDL_Surface
of SDL (http://libsdl.org/).