<-- Back to AG_Intro.3

SYNOPSIS

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

DESCRIPTION

The AG_GLView widget (with an OverlayFn)

NOTE: As of version 1.5.0, AG_GLView has been superceded by the AG_WIDGET_USE_OPENGL feature of the base AG_Widget(3) class.

The AG_GLView widget provides a low-level OpenGL context. In order to be useful, two callbacks should be implemented: scale() and draw(). The scale() function is expected to set the projection matrix. For example, the scale function may be a simple call to glOrtho(3).

The draw() function renders the scene to the display. Before calling draw(), 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.

The AG_GLView widget is not redrawn automatically by default. It is the responsibility of the caller to set the redraw policy either by calling AG_Redraw(3) to explicitely request a redraw, configuring a periodic update interval using AG_RedrawOnTick(3), or a conditional update using AG_RedrawOnChange(3).

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, const 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_GLViewUnderlayFn (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_BGFILL	Clear the widget background with the specified color (see AG_GLViewSetBgColor()).
AG_GLVIEW_HFILL	Expand horizontally in parent container.
AG_GLVIEW_VFILL	Expand vertically in parent container.
AG_GLVIEW_EXPAND	Shorthand 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 projection and viewing matrices. Similarly, AG_GLViewUnderlayFn() registers a function that will be invoked before rendering. Both overlay and underlay callbacks may invoke standard Agar GUI primitives such as AG_DrawRect(3) or AG_WidgetBlit(3).

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 does not generate any event.

STRUCTURE DATA

For the AG_GLView object:

float mProjection[16]	Saved Projection matrix (4x4, column-major).
float mModelview[16]	Saved Modelview matrix.
float mTexture[16]	Saved Texture matrix.

EXAMPLES

See tests/glview.c in the Agar source distribution.

HISTORY

The AG_GLView widget first appeared in Agar 1.2. As of Agar 1.5.0, it has been superceded by the AG_WIDGET_USE_OPENGL feature of AG_Widget(3).