Class
GtkGLArea
since: 3.16
Description [src]
class Gtk.GLArea : Gtk.Widget
implements Atk.ImplementorIface, Gtk.Buildable {
/* No available fields */
}GtkGLArea is a widget that allows drawing with OpenGL.
GtkGLArea sets up its own GdkGLContext 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 GtkGLArea::render signal,
or subclass GtkGLArea and override the GtkGLAreaClass.render() virtual function.
The GtkGLArea widget ensures that the GdkGLContext is associated with
the widget’s drawing area, 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 GtkGLArea is to
create a widget instance and connect to the GtkGLArea::render signal:
// 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);
The render() function will be called when the GtkGLArea 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;
}
If you need to initialize OpenGL state, e.g. buffer objects or
shaders, you should use the GtkWidget::realize signal; you
can use the GtkWidget::unrealize signal to clean up. Since the
GdkGLContext creation and initialization may fail, you will
need to check for errors, using gtk_gl_area_get_error(). 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 GdkGLContext
you should use the GtkGLArea::create-context signal.
Available since: 3.16
Instance methods
gtk_gl_area_attach_buffers
Ensures that the area framebuffer object is made the current draw
and read target, and that all the required buffers for the area
are created and bound to the frambuffer.
since: 3.16
gtk_gl_area_get_required_version
Retrieves the required version of OpenGL set using gtk_gl_area_set_required_version().
since: 3.16
gtk_gl_area_make_current
Ensures that the GdkGLContext used by area is associated with
the GtkGLArea.
since: 3.16
gtk_gl_area_queue_render
Marks the currently rendered data (if any) as invalid, and queues
a redraw of the widget, ensuring that the GtkGLArea::render signal
is emitted during the draw.
since: 3.16
gtk_gl_area_set_auto_render
If auto_render is TRUE the GtkGLArea::render signal will be
emitted every time the widget draws. This is the default and is
useful if drawing the widget is faster.
since: 3.16
gtk_gl_area_set_error
Sets an error on the area which will be shown instead of the
GL rendering. This is useful in the GtkGLArea::create-context
signal if GL context creation fails.
since: 3.16
gtk_gl_area_set_has_alpha
If has_alpha is TRUE the buffer allocated by the widget will have
an alpha channel component, and when rendering to the window the
result will be composited over whatever is below the widget.
since: 3.16
gtk_gl_area_set_has_depth_buffer
If has_depth_buffer is TRUE the widget will allocate and
enable a depth buffer for the target framebuffer. Otherwise
there will be none.
since: 3.16
gtk_gl_area_set_has_stencil_buffer
If has_stencil_buffer is TRUE the widget will allocate and
enable a stencil buffer for the target framebuffer. Otherwise
there will be none.
since: 3.16
gtk_gl_area_set_required_version
Sets the required version of OpenGL to be used when creating the context for the widget.
since: 3.16
gtk_gl_area_set_use_es
Sets whether the area should create an OpenGL or an OpenGL ES context.
since: 3.22
Methods inherited from GtkBuildable (10)
Properties
Gtk.GLArea:auto-render
If set to TRUE the GtkGLArea::render signal will be emitted every time
the widget draws. This is the default and is useful if drawing the widget
is faster.
since: 3.16
Gtk.GLArea:has-alpha
If set to TRUE the buffer allocated by the widget will have an alpha channel
component, and when rendering to the window the result will be composited over
whatever is below the widget.
since: 3.16
Gtk.GLArea:has-depth-buffer
If set to TRUE the widget will allocate and enable a depth buffer for the
target framebuffer.
since: 3.16
Gtk.GLArea:has-stencil-buffer
If set to TRUE the widget will allocate and enable a stencil buffer for the
target framebuffer.
since: 3.16
Gtk.GLArea:use-es
If set to TRUE the widget will try to create a GdkGLContext using
OpenGL ES instead of OpenGL.
since: 3.22
Signals
Gtk.GLArea::create-context
The ::create-context 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.
since: 3.16
Gtk.GLArea::render
The ::render signal is emitted every time the contents
of the GtkGLArea should be redrawn.
since: 3.16
Gtk.GLArea::resize
The ::resize 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.
since: 3.16