Agar


Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_GLView widget provides a low-level OpenGL context. In order to be useful, two important functions must be registered: The scale function and the draw function.

The scale function should set a projection matrix. For example, a minimal scale function could be a simple call to glOrtho(3). The glMatrixMode() and glLoadIdentity() functions are used before the scale function is invoked.

The draw function renders the scene to the display. Before calling the draw function, AG_GLView calls glViewport(3). It also sets the GL_TEXTURE, GL_PROJECTION, GL_MODELVIEW matrices and saves the state of the clipping planes by calling glPushAttrib(3) with GL_TRANSFORM_BIT.

In OpenGL mode, the Agar GUI elements are rendered using GL primitives, so it is the responsibility of the caller to save and restore all GL state (except for the matrices and clipping plane states), in the draw function.

Typically, AG_GLView is used as a base class to implement more specific scene-rendering widgets. For example, the SG_View(3) and SK_View(3) widgets of FreeSG (http://freesg.org/) are subclasses of AG_GLView.

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Widget(3)-> AG_GLView.

INITIALIZATION


AG_GLView * AG_GLViewNew (AG_Widget *parent, Uint flags)

void AG_GLViewSetBgColor (AG_GLView *glv, AG_Color c)

void AG_GLViewSizeHint (AG_GLView *glv, int w, int h)

void AG_GLViewDrawFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewOverlayFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewScaleFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewKeydownFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewKeyupFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewButtondownFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewButtonupFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)

void AG_GLViewMotionFn (AG_GLView *glv, void (*fn)(AG_Event *), const char *args, ...)


The AG_GLViewNew() function allocates, initializes, and attaches a new AG_GLView widget. Acceptable flags include:
AG_GLVIEW_BGFILLClear the widget background with the specified color (see AG_GLViewSetBgColor()).
AG_GLVIEW_HFILLExpand horizontally in parent (equivalent to invoking AG_ExpandHoriz(3)).
AG_GLVIEW_VFILLExpand vertically in parent (equivalent to invoking AG_ExpandVert(3)).
AG_GLVIEW_EXPANDShorthand for AG_GLVIEW_HFILL|AG_GLVIEW_VFILL.

AG_GLViewSetBgColor() specifies the background color (effective only if AG_GLVIEW_BGFILL is set).

AG_GLViewSizeHint() suggests an initial widget size in pixels.

The AG_GLViewDrawFn() registers a the rendering function (specified in AG_Event(3) format). Prior to invoking this function, the widget will set the glViewport(3) to the widget area, save the current OpenGL matrices and load the widget-specific matrices.

AG_GLViewOverlayFn() registers a function that will be invoked after rendering, after the GUI matrices and viewport have been restored. It is typically used to draw text or controls independently of the AG_GLViews projection and viewing matrices.

AG_GLViewScaleFn() registers a function to invoke whenever the widget is resized.

AG_GLViewKeydownFn(), AG_GLViewKeyupFn(), AG_GLViewButtondownFn(), AG_GLViewButtonupFn() and AG_GLViewMotionFn() register general event handler functions that will be forwarded key-down, key-up, mouse-button-down, mouse-button-up and mouse-motion events, respectively.

BINDINGS

The AG_GLView widget does not provide any binding.

EVENTS

The AG_GLView widget reacts to the following events:
widget-movedProjection matrix is recomputed and the scale operation is invoked.

The AG_GLView widget does not generate any event.

STRUCTURE DATA

For the AG_GLView object:
float mProjection[16] Projection matrix (4x4, column-major) to automatically load every time the AG_GLView is drawn. Defaults to identity.
float mModelview[16] Modelview matrix (4x4, column-major) to automatically load every time the AG_GLView is drawn. Defaults to identity.
float mTexture[16] Texture matrix (4x4, column-major) to automatically load every time the AG_GLView is drawn. Defaults to identity.

EXAMPLES

See the glview demo in the Agar demos directory.

SEE ALSO

AG_Intro(3), AG_Color(3), AG_Widget(3), AG_Window(3), SG(3), SG_View(3)

HISTORY

The AG_GLView widget first appeared in Agar 1.2.