NAME

AG_GLView — low-level OpenGL context widget

SYNOPSIS

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

DESCRIPTION

DEPRECATED: Since Agar 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.

SEE ALSO

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

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