gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

None

The gtk:gl-area widget is a widget that allows drawing with OpenGL.

Figure: GtkGLArea

The gtk:gl-area widget sets up its own gdk:gl-context object for the window it creates, and creates a custom GL framebuffer that the widget will do GL rendering onto. It also ensures that this framebuffer is the default GL rendering target when rendering.

In order to draw, you have to connect to the "render" signal, or subclass the gtk:gl-area widget and override the render() virtual function.

The gtk:gl-area widget ensures that the gdk:gl-context object is associated with the drawing area of the widget, and it is kept updated when the size and position of the drawing area changes.

Drawing with GtkGLArea

The simplest way to draw using OpenGL commands in a gtk:gl-area widget is to create a widget instance and connect to the "render" signal.

The render() function will be called when the gtk:gl-area widget is ready for you to draw its content:

static gboolean
render (GtkGLArea *area, GdkGLContext *context)
{
  // inside this function it's safe to use GL; the given
  // GdkGLContext has been made current to the drawable
  // surface used by the `GtkGLArea` and the viewport has
  // already been set to be the size of the allocation


  // we can start by clearing the buffer
  glClearColor (0, 0, 0, 0);
  glClear (GL_COLOR_BUFFER_BIT);


  // draw your object
  // draw_an_object ();


  // we completed our drawing; the draw commands will be
  // flushed at the end of the signal emission chain, and
  // the buffers will be drawn on the window
  return TRUE;
}


void setup_glarea (void)
{
  // create a GtkGLArea instance
  GtkWidget *gl_area = gtk_gl_area_new ();


  // connect to the "render" signal
  g_signal_connect (gl_area, "render", G_CALLBACK (render), NULL);
}  

If you need to initialize OpenGL state, for example buffer objects or shaders, you should use the "realize" signal. You can use the "unrealize" signal to clean up. Since the gdk:gl-context object creation and initialization may fail, you will need to check for errors, using the gtk:gl-area-error function. An example of how to safely initialize the GL state is:

static void
on_realize (GtkGLarea *area)
{
  // We need to make the context current if we want to
  // call GL API
  gtk_gl_area_make_current (area);


  // If there were errors during the initialization or
  // when trying to make the context current, this
  // function will return a GError for you to catch
  if (gtk_gl_area_get_error (area) != NULL)
    return;


  // You can also use gtk_gl_area_set_error() in order
  // to show eventual initialization errors on the
  // GtkGLArea widget itself
  GError *internal_error = NULL;
  init_buffer_objects (&error);
  if (error != NULL)
    {
      gtk_gl_area_set_error (area, error);
      g_error_free (error);
      return;
    }


  init_shaders (&error);
  if (error != NULL)
    {
      gtk_gl_area_set_error (area, error);
      g_error_free (error);
      return;
    }
}  

If you need to change the options for creating the gdk:gl-context object you should use the "create-context" signal.

The "create-context" signal

lambda (area)    :run-last      

area

The gtk:gl-area widget that emitted the signal.

Returns

The newly created gdk:gl-context object. The gtk:gl-area widget will take ownership of the returned value.

The signal is emitted when the widget is being realized, and allows you to override how the GL context is created. This is useful when you want to reuse an existing GL context, or if you want to try creating different kinds of GL options. If context creation fails then the signal handler can use the gtk:gl-area-error function to register a more detailed error of how the construction failed.

The "render" signal

lambda (area context)    :run-last      

area

The gtk:gl-area widget that emitted the signal.

context

The gdk:gl-context object used by area.

Returns

True to stop other handlers from being invoked for the event. False to propagate the event further.

The signal is emitted every time the contents of the gtk:gl-area widget should be redrawn. The context is bound to the area prior to emitting this function, and the buffers are painted to the window once the emission terminates.

The "resize" signal

lambda (area width height)    :run-last      

area

The gtk:gl-area widget that emitted the signal.

width

The integer with the width of the viewport.

height

The integer with the height of the viewport.

The signal is emitted once when the widget is realized, and then each time the widget is changed while realized. This is useful in order to keep GL state up to date with the widget size, like for instance camera properties which may depend on the width/height ratio. The GL context for the area is guaranteed to be current when this signal is emitted. The default handler sets up the GL viewport.