NAME

RG_Pixmap — Agar-RG surface element

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/map/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_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 RG_PixmapBeginUndoBlk call, 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 */
};

The RG_PixmapDelBrush() function destroys the given brush.

RG_PixmapSetBrush() selects the current brush, to be used by RG_PixmapApplyBrush(), as described in the “PIXEL OPERATIONS” section.

SEE ALSO

RG(3), RG_Feature(3), RG_Sketch(3), RG_Texture(3), RG_Tile(3), RG_Tileview(3)