AG_GLVIEW(3)

NAME
AG_GLView - low-level OpenGL context widget

SYNOPSIS

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

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

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