NAME

AG_WidgetPrimitives — agar widget rendering primitives

SYNOPSIS

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

DESCRIPTION

Agar provides a set of graphical primitives that may be called from the draw() method of an AG_Widget(3) ("rendering context").

Although these functions draw directly to the display, they take x and y coordinates in the local coordinate system of the widget.

LOW-LEVEL PRIMITIVES

The following routines render directly to the display, converting relative x, y coordinates to display coordinates implicitely.

void
AG_PutPixel(AG_Widget *widget, int x, int y, const 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, const 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, const AG_Color *c);

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

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

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

void
AG_DrawLineW(AG_Widget *widget, int x1, int y1, int x2, int y2, const AG_Color *c, float width);

void
AG_DrawLineW_Sti16(AG_Widget *widget, int x1, int y1, int x2, int y2, const AG_Color *c, float width, Uint16 stipple);

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

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

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

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

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

void
AG_DrawRectBlended(AG_Widget *widget, const AG_Rect *r, const AG_Color *c, AG_AlphaFn fnSrc, AG_AlphaFn fnDst);

void
AG_DrawArrowLine(AG_Widget *widget, int x1, int y1, int x2, int y2, AG_ArrowLineType t, int length, double theta, const AG_Color *c);

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. The AG_BlendPixel32() and AG_BlendPixel64() variants take a 32- and a 64-bit pixel value respectively.

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

AG_DrawFrame() draws a 3D raised box (if z>0) or a 3D well (if z<0).

AG_DrawCircle() draws a circle around x, y of radius pixels.

AG_DrawLine() draws a line segment from point x1, y1 to x2, y2.

AG_DrawLineH() draws a horizontal line from point x, y1 to x, y2.

AG_DrawLineV() draws a vertical line from point x1, y to x2, y.

AG_DrawLineW() draws a line of specified width (where 1.0f = 1 pixel) between x1, y1 and x2, y2.

AG_DrawLineW_Sti16() draws a line of specified width (where 1.0f = 1 pixel) and 16-bit stipple pattern between x1, y1 and x2, y2.

The AG_DrawLineBlended() variant performs alpha blending if the alpha component of c is not fully opaque.

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. fnSrc specifies the source factor (e.g., AG_ALPHA_SRC) and fnDst the destination factor (e.g., AG_ALPHA_ONE_MINUS_SRC). For the list of available functions, refer to AG_AlphaFn(3).

AG_DrawArrowLine() is a wrapper around AG_DrawLine() and AG_DrawArrowhead() which can draw a line along with, depending on the value of t:

AG_ARROWLINE_NONE

No arrowheads.

AG_ARROWLINE_FORWARD

A forward-pointing arrow.

AG_ARROWLINE_REVERSE

A reverse-pointing arrow.

AG_ARROWLINE_BOTH

Forward and reverse arrows.

For the purposes of determining "forward" and "reverse", a forward arrow would be taken to point to ( x2, y2 ).

HIGH-LEVEL PRIMITIVES

The following functions call low-level primitives in order to produce 3D-style features. Unlike low-level primitives (which are stateless), these functions allow the state of widget to influence the appearance (for example, adding dither patterns if the widget is in #disabled state).

void
AG_DrawBoxRaised(AG_Widget *widget, const AG_Rect *r, const AG_Color *c);

void
AG_DrawBoxSunk(AG_Widget *widget, const AG_Rect *r, const AG_Color *c);

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

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

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

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

The AG_DrawBoxRaised() routine renders a 3D-style raised box over the area of r. AG_DrawBoxSunk() renders a 3D-style well.

AG_DrawBox() invokes AG_DrawBoxRaised() or AG_DrawBoxSunk() based on the z argument. The magnitude of z determines the depth of the box.

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

SYMBOLS

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

void
AG_DrawPolygon(AG_Widget *widget, const AG_Pt *pts, Uint nPts, const AG_Color *c);

void
AG_DrawPolygon_Sti32(AG_Widget *widget, const AG_Pt *pts, Uint nPts, const AG_Color *c, const Uint8 *stipplePattern);

void
AG_DrawVector(AG_Widget *widget, int dim, const AG_Rect *r, const AG_VectorElement *elements, int elemFirst, int elemLast);

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

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

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

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

void
AG_DrawArrowhead(void *obj, int x1, int y1, int x2, int y2, int length, double theta, const AG_Color *c);

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

AG_DrawPolygon() draws a convex polygon of color c from an array of vertices pts. AG_DrawPolygonSti32() renders a convex polygon of color c from an array of vertices pts and a 32x32 bitmask (or 1-bpp image). stipplePattern must point to a 128-byte (32 x 4 byte) array.

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.

AG_DrawArrowhead() draws an arrowhead aligned to a line. x2 and y2 Define the tip of the arrowhead, and x1 and y1 define the originating point of the "line" (i.e. the arrowhead faces away from this point). length defines the length from tip to base of the arrowhead. theta defines the angle of the lines which converge at the tip of the arrowhead. The arrowhead is always drawn in a solid / fully filled style.

UTILITY ROUTINES

int
AG_GetLineIntersection(long x1, long y1, long x2, long y2, long x3, long y3, long x4, long y4, long *xi, long *yi);

void
AG_ClipLine(int ax, int ay, int aw, int ah, int x1, int y1, int *x2, int *y2);

void
AG_ClipLineCircle(int xc, int yc, int r, int x1, int y1, int x2, int y2, int *xi, int *yi);

The AG_GetLineIntersection() function considers two line segments ( x1, y1 ), ( x2, y2 ) and ( x3, y3 ) and ( x4, y4 ). If the lines do not intersect, then the function returns 0. If they do intersect, then it returns 1 and xi and yi will be updated to the coordinates at which the intersection occurs.

AG_ClipLine() considers the bounding box defined by it's top left corner: ax, ay and its width and height: aw, ah and the line segment defined by ( x1, y1, ), ( x2, y2, ). If the line intersects with the provided bounding box, then x2 and y2 will be updated such that they are the closest point to ( x1, y1 ) at which the line segment intersects with the given bounding box.

AG_ClipLine() If the circle centered at ( xc, yc ) with radius r intersects with the line segment ( x1, y1 ), ( x2, y2 ), then xi and yi are updated to reflect the intersection point which is closest to ( x1, y1 ).

SEE ALSO

AG_AlphaFn(3), AG_Color(3), AG_Intro(3), AG_Widget(3), RG(3), VG(3)

HISTORY

Simple widget primitives first appeared in Agar 1.0. The basic rendering system was redesigned in Agar 1.4.0. 64-bit pixel access routines, line intersection/clipping tests and the Arrowhead primitive were added in Agar 1.6.0.