<-- Back to AG_Intro.3

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/rg.h>

DESCRIPTION

The RG_Pixmap element defines a two-dimensional array of pixels. A RG_Pixmap may be referenced by one or more RG_Tile(3), RG_Anim(3), RG_Texture(3) and RG_Feature(3) elements. When a RG_Pixmap is modified, the change is automatically applied to every resource that references it. Pixmaps can also be resized on the fly, so resources that make use of RG_Pixmap need to take that possibility into account.

The following members of the RG_Pixmap structure are public:

typedef struct rg_pixmap {
	char name[RG_PIXMAP_NAME_MAX];  /* Name of pixmap (unique) */
	int xorig, yorig;               /* Origin point */
	AG_Surface *su;                 /* Pixmap surface */
	Uint nrefs;                     /* Number of tile references */
} RG_Pixmap;

INITIALIZATION

RG_Pixmap * RG_PixmapNew (RG_Tileset *set, const char *name, int flags)

void RG_PixmapScale (RG_Pixmap *pixmap, int width, int height)

The RG_PixmapNew() function allocates, initializes and attaches a RG_Pixmap structure. name is a string identifier for the pixmap (if a pixmap of the same name exists, a unique name will be generated automatically). There are currently no flags defined. The RG_PixmapScale() function resizes the pixmap canvas size to width by height pixels. Existing pixmap data is preserved.

UNDO OPERATIONS

A structure of undo levels is defined for each RG_Pixmap. When implementing new tools, it is important to use RG_PixmapBeginUndoBlk() prior to making modifications to the pixmap surface.

void RG_PixmapBeginUndoBlk (RG_Pixmap *pixmap)

void RG_PixmapUndo (RG_Tileview *view, RG_TileElement *pixmapElement)

void RG_PixmapRedo (RG_Tileview *view, RG_TileElement *pixmapElement)

RG_PixmapBeginUndoBlk() marks the beginning of one or more modifications that will be undone/redone together. RG_PixmapUndo() executes an undo command. RG_PixmapRedo() executes a redo command.

PIXEL OPERATIONS

void RG_PixmapSetBlendingMode (RG_Pixmap *pixmap, enum rg_pixel_blend_mode bmode)

int RG_PixmapPutPixel (RG_Tileview *view, RG_TileElement *pixmapElement, int x, int y, Uint32 pixel, int onceFlag)

void RG_PixmapApplyBrush (RG_Tileview *view, RG_TileElement *pixmapElement "int x, int y, Uint32 color)

Uint32 RG_PixmapSourcePixel (RG_Tileview *view, RG_TileElement *pixmapElement, int x, int y)

void RG_PixmapSourceRGBA (RG_Tileview *view, RG_TileElement *pixmapElement, int x, int y, Uint8 *r" "Uint8 *g" "Uint8 *b" "Uint8 *a)

RG_PixmapSetBlendingMode() selects the alpha blending function to use for subsequent pixel operations. Currently implemented are:

enum rg_pixmap_blend_mode {
	RG_PIXMAP_OVERLAY_ALPHA,        /* dA = sA+dA */
	RG_PIXMAP_AVERAGE_ALPHA,        /* dA = (sA+dA)/2 */
	RG_PIXMAP_DEST_ALPHA,           /* dA = dA */
	RG_PIXMAP_NO_BLENDING           /* No blending done */
};

The RG_PixmapPutPixel() function writes the pixel value pixel (specified in agSurfaceFmt format) at coordinates x, y. If onceFlag is 1, the function will check if any other modifications were made to this pixel in the current undo block. If the pixel was modified since the last Nm RG_PixmapBeginUndoBlkcall, the function is a no-op.

RG_PixmapApplyBrush() operates in a similar way, except that instead of a single pixel, a group of pixel are modified according to the current brush (as set by RG_PixmapSetBrush()). See BRUSHES section below for more information.

RG_PixmapSourcePixel() and RG_PixmapSourceRGBA() return the pixel at given coordinates x, y in 32-bit agSurfaceFmt format and component (RGBA) format, respectively.

BRUSHES

RG_Brush * RG_PixmapAddBrush (RG_Pixmap *pixmap "enum rg_brush_type type, RG_Pixmap *pixmap)

void RG_PixmapDelBrush (RG_Pixmap *pixmap, RG_Brush *brush)

void RG_PixmapSetBrush (RG_Pixmap *pixmap, RG_Brush *brush)

The RG_PixmapAddBrush() function creates and attaches a new brush to the pixmap. The type argument is one of:

enum rg_brush_type {
	RG_PIXMAP_BRUSH_MONO,  /* Monochromatic (use current color) */
	RG_PIXMAP_BRUSH_RGB    /* Replace by brush color */
};