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.

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


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 ).

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).


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.

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.

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 ).

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

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.