AG_WIDGETPRIMITIVES(3)

NAME
AG_WidgetPrimitives - agar widget rendering primitives

SYNOPSIS

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

DESCRIPTION
Agar provides a few primitive rendering routines designed specifically for the rendering of GUI elements, as opposed to general-purpose graphics (look into other libraries, such as the included VG(3) and RG(3) for this).

It is illegal to invoke the following routines outside of AG_Widget(3) rendering context (e.g., the widget draw() operation). The coordinates for all AG_Draw*() functions are given in pixels, in the widget's local coordinate system. The AG_Color and AG_BlendFn types are commonly used to specify colors and blending modes, see AG_Color(3) and AG_BlendFn(3) for details.

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

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

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

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

void AG_BlendPixelRGBA(AG_Widget *widget, int x, int y, Uint8 c[4], AG_BlendFn blendFn)

void AG_BlendPixel32(AG_Widget *widget, int x, int y, Uint32 c, AG_BlendFn 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_BlendFn 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_BlendFn blendFn)

AG_PutPixel() writes a single pixel at the specified coordinates. The AG_PutPixelRGB() variant accepts individual red, green and blue color arguments.

The AG_PutPixel32() variant accepts a 32-bit pixel value such that no conversion is necessary when writing the pixel to the framebuffer. Conversion may be achieved using AG_MapPixelRGB with the videoFmt member of the widget's associated AG_Driver(3) structure.

The AG_BlendPixel() function writes a pixel at the specified coordinates, using alpha blending with the specified blending function. The AG_BlendPixelRGBA() variant accepts an array of red, green, blue and alpha arguments.

The AG_BlendPixel32() variant accepts a 32-bit packed-pixel value such that minimal conversion is necessary when writing to the framebuffer. Conversion may be achieved using AG_MapPixelRGB with the global agSurfaceFmt.

Note that active clipping rectangles (see AG_Widget(3)) apply to AG_PutPixel*() and AG_BlendPixel*(). These operations are also safe to use when underlying graphics driver is not framebuffer-based.

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_BlendFn(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_BlendFn 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_BlendFn blendFn)

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

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

SEE ALSO
AG_BlendFn(3), AG_Color(3), AG_Intro(3), AG_Widget(3), RG(3), VG(3)

The FreeSG library: http://freesg.org/

HISTORY
Simple widget primitives first appeared in Agar 1.0. The basic rendering system was redesigned in Agar 1.4.