<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

Agar provides a set of basic rendering operations designed for rendering GUI elements efficiently (as opposed to general-purpose graphics, as would be handled by libraries such as OpenGL or VG(3)). It is illegal to invoke these routines outside of the draw() method of an AG_Widget(3) (what we refer to as rendering context).

The x and y coordinates for the AG_Draw*() routines are given in pixels in the widget argument's local coordinate system.

PRIMITIVES

void AG_PutPixel (AG_Widget *widget, int x, int y, AG_Color c)

void AG_PutPixelRGB (AG_Widget *widget, int x, int y, AG_Component r, AG_Component g, AG_Component b)

void AG_PutPixelRGB_8 (AG_Widget *widget, int x, int y, Uint8 r, Uint8 g, Uint8 b)

void AG_PutPixelRGB_16 (AG_Widget *widget, int x, int y, Uint16 r, Uint16 g, Uint16 b)

void AG_PutPixel32 (AG_Widget *widget, int x, int y, Uint32 px)

void AG_PutPixel64 (AG_Widget *widget, int x, int y, Uint64 px)

void AG_BlendPixel (AG_Widget *widget, int x, int y, AG_Color c, AG_AlphaFn blendFn)

void AG_BlendPixel32 (AG_Widget *widget, int x, int y, Uint32 c, AG_AlphaFn blendFn)

void AG_BlendPixel64 (AG_Widget *widget, int x, int y, Uint64 c, AG_AlphaFn blendFn)

void AG_DrawCircle (AG_Widget *widget, int x, int y, int radius, AG_Color c)

void AG_DrawCircle2 (AG_Widget *widget, int x, int y, int radius, AG_Color c)

void AG_DrawLine (AG_Widget *widget, int x1, int y1, int x2, int y2, AG_Color c)

void AG_DrawLine2 (AG_Widget *widget, int x1, int y1, int x2, int y2, AG_Color c)

void AG_DrawLineBlended (AG_Widget *widget, int x1, int y1, int x2, int y2, Uint8 c[4], AG_AlphaFn blendFn)

void AG_DrawLineH (AG_Widget *widget, int x1, int x2, int y, AG_Color c)

void AG_DrawLineV (AG_Widget *widget, int x, int y1, int y2, AG_Color c)

void AG_DrawRect (AG_Widget *widget, AG_Rect r, AG_Color c)

void AG_DrawRectOutline (AG_Widget *widget, AG_Rect r, AG_Color c)

void AG_DrawRectFilled (AG_Widget *widget, AG_Rect r, AG_Color c)

void AG_DrawRectBlended (AG_Widget *widget, AG_Rect r, AG_Color c, AG_AlphaFn blendFn)

AG_PutPixel() sets the pixel at x, y to the native display color that most closely matches the given AG_Color(3). The AG_PutPixelRGB(), AG_PutPixelRGB_8(), and AG_PutPixelRGB_16() forms accept component values as separate arguments.

The AG_PutPixel32() form accept an 8- to 32-bit wide pixel already in native display format. Under AG_LARGE, the AG_PutPixel64() form also allows 48- and 64-bit wide pixel values.

The AG_BlendPixel() function blends an existing pixel against a given AG_Color(3), overwriting the pixel with the best native-display approximation of the result.

AG_BlendPixel32() and AG_BlendPixel64() accept a 32- and 64-bit pixel value.

Coordinates to AG_PutPixel*() and AG_BlendPixel*() are checked, and intersected against active clipping rectangles (see AG_Widget(3)).

AG_DrawFrame() draws a 3D-style frame. AG_DrawFrameBlended() draws a frame with alpha-blending, with the color c specified as an array of RGBA components, and the given blending mode.

AG_DrawCircle() draws a circle with the origin at x, y and a radius of radius pixels.

AG_DrawLine() scan-converts a line segment going from point x1, y1 to point x2, y2. The variants AG_DrawLineH() and AG_DrawLineV() render horizontal and vertical line segments, respectively. AG_DrawLine2() renders two line segments for a 3D-style effect.

AG_DrawLineBlended() renders an alpha-blended line, where the RGBA components are passed as the c array, and the blending function is specified in blendFn.

The AG_DrawRect() function fills a destination rectangle with the specified color. If the color is non-opaque, blending is performed.

AG_DrawRectOutline() draws the outline of a rectangle.

AG_DrawRectFilled() fills an opaque rectangle with the specified color, ignoring any alpha component.

AG_DrawRectBlended() draws a blended rectangle of the color c, specified as an array or RGBA components. AG_DrawRectBlended() differs from AG_DrawRect() in that it accepts an explicit blending mode blendFn (see AG_AlphaFn(3) for details).

SIMPLE GRAPHICAL ELEMENTS

void AG_DrawBox (AG_Widget *widget, AG_Rect r, int z, AG_Color c)

void AG_DrawBoxDisabled (AG_Widget *widget, AG_Rect r, int z, AG_Color c1, AG_Color c2)

void AG_DrawBoxRounded (AG_Widget *widget, AG_Rect r, int z, int radius, AG_Color c)

void AG_DrawBoxRoundedTop (AG_Widget *widget, AG_Rect r, int z, int radius, AG_Color c)

void AG_DrawTiling (AG_Widget *widget, AG_Rect r, int tileSz, int offset, AG_Color c1, AG_Color c2)

void AG_DrawFrame (AG_Widget *widget, AG_Rect r, int z, AG_Color c)

void AG_DrawFrameBlended (AG_Widget *widget, AG_Rect r, Uint8 c[4], AG_AlphaFn blendFn)

The AG_DrawBox() routine draws a simple 3D-style box. z specifies the apparent 3D depth, in pixels.

The AG_DrawBoxDisabled() variant uses a stipple pattern of c1 against c2. AG_DrawBoxDisabled() is traditionally used to indicate a GUI element that is not responsive to user input.

AG_DrawBoxRounded() renders a box with the edges rounded to the given radius. The AG_DrawBoxRoundedTop() variant only rounds the top two corners.

AG_DrawTiling() fills the rectangle r with a two-color tiling pattern. tileSz is the size of the tiles in pixels, offset is an offset in pixels and c1, c2 specify the colors of the tiles.

SYMBOLS

void AG_DrawPlus (AG_Widget *widget, AG_Rect r, Uint8 c[4], AG_AlphaFn blendFn)

void AG_DrawMinus (AG_Widget *widget, AG_Rect r, Uint8 c[4], AG_AlphaFn blendFn)

void AG_DrawTriangle (AG_Widget *widget, AG_Pt v1, AG_Pt v2, AG_Pt v3, AG_Color c)

void AG_DrawArrowUp (AG_Widget *widget, int x, int y, int h, AG_Color c1, AG_Color c2)

void AG_DrawArrowDown (AG_Widget *widget, int x, int y, int h, AG_Color c1, AG_Color c2)

void AG_DrawArrowLeft (AG_Widget *widget, int x, int y, int w, AG_Color c1, AG_Color c2)

void AG_DrawArrowRight (AG_Widget *widget, int x, int y, int w, AG_Color c1, AG_Color c2)

The AG_DrawPlus() and AG_DrawMinus() routines render plus ("+") or minus ("-") signs spanning rectangle r using the specified color and blending function.

AG_DrawTriangle() renders a triangle of color c given three unordered vertices v1, v2, and v3.

AG_DrawArrowUp(), AG_DrawArrowDown(), AG_DrawArrowLeft() and AG_DrawArrowRight() draw an arrow at the specified coordinates. h and w specify the size of the arrow in pixels.

HISTORY

Simple widget primitives first appeared in Agar 1.0. The basic rendering system was redesigned in Agar 1.4. 64-bit pixel access routines were added in Agar 1.6.