GLArea
Superclasses: Widget
, InitiallyUnowned
, Object
Implemented Interfaces: Accessible
, Buildable
, ConstraintTarget
GtkGLArea
is a widget that allows drawing with OpenGL.
GtkGLArea
sets up its own GLContext
, 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.
The completed rendering is integrated into the larger GTK scene graph as
a texture.
In order to draw, you have to connect to the 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 render
signal:
The render()
function will be called when the GtkGLArea
is ready
for you to draw its content:
The initial contents of the framebuffer are transparent.
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, e.g. buffer objects or
shaders, you should use the realize
signal;
you can use the unrealize
signal to clean up.
Since the GdkGLContext
creation and initialization may fail, you
will need to check for errors, using 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 :func:`~gi.repository.Gtk.GLArea.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 create_context
signal.
Constructors
Methods
- class GLArea
- attach_buffers() None
Binds buffers to the framebuffer.
Ensures that the
area
framebuffer object is made the current draw and read target, and that all the required buffers for thearea
are created and bound to the framebuffer.This function is automatically called before emitting the
render
signal, and doesn’t normally need to be called by application code.
- get_allowed_apis() GLAPI
Gets the allowed APIs.
See
set_allowed_apis
.Added in version 4.12.
- get_api() GLAPI
Gets the API that is currently in use.
If the GL area has not been realized yet, 0 is returned.
Added in version 4.12.
- get_required_version() tuple[int, int]
Retrieves the required version of OpenGL.
See
set_required_version
.
- get_use_es() bool
Returns whether the
GtkGLArea
should use OpenGL ES.See
set_use_es
.Deprecated since version 4.12: Use
get_api
- make_current() None
Ensures that the
GdkGLContext
used byarea
is associated with theGtkGLArea
.This function is automatically called before emitting the
render
signal, and doesn’t normally need to be called by application code.
- queue_render() None
Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget.
This ensures that the
render
signal is emitted during the draw.This is only needed when
set_auto_render
has been called with aFalse
value. The default behaviour is to emitrender
on each draw.
- set_allowed_apis(apis: GLAPI) None
Sets the allowed APIs to create a context with.
You should check
api
before drawing with either API.By default, all APIs are allowed.
Added in version 4.12.
- Parameters:
apis – the allowed APIs
- set_auto_render(auto_render: bool) None
Sets whether the
GtkGLArea
is in auto render mode.If
auto_render
isTrue
therender
signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster.If
auto_render
isFalse
the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a renderingqueue_render
must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.- Parameters:
auto_render – a boolean
- set_error(error: GError | None = None) None
Sets an error on the area which will be shown instead of the GL rendering.
This is useful in the
create_context
signal if GL context creation fails.- Parameters:
error – a new
GError
, orNone
to unset the error
- set_has_depth_buffer(has_depth_buffer: bool) None
Sets whether the
GtkGLArea
should use a depth buffer.If
has_depth_buffer
isTrue
the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none.- Parameters:
has_depth_buffer –
True
to add a depth buffer
- set_has_stencil_buffer(has_stencil_buffer: bool) None
Sets whether the
GtkGLArea
should use a stencil buffer.If
has_stencil_buffer
isTrue
the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none.- Parameters:
has_stencil_buffer –
True
to add a stencil buffer
- set_required_version(major: int, minor: int) None
Sets the required version of OpenGL to be used when creating the context for the widget.
This function must be called before the area has been realized.
- Parameters:
major – the major version
minor – the minor version
- set_use_es(use_es: bool) None
Sets whether the
area
should create an OpenGL or an OpenGL ES context.You should check the capabilities of the
GdkGLContext
before drawing with either API.Deprecated since version 4.12: Use
set_allowed_apis
- Parameters:
use_es – whether to use OpenGL or OpenGL ES
Properties
- class GLArea
-
- props.auto_render: bool
If set to
True
the ::render signal will be emitted every time the widget draws.This is the default and is useful if drawing the widget is faster.
If set to
False
the data from previous rendering is kept around and will be used for drawing the widget the next time, unless the window is resized. In order to force a renderingqueue_render
must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.
- props.context: GLContext
The
GdkGLContext
used by theGtkGLArea
widget.The
GtkGLArea
widget is responsible for creating theGdkGLContext
instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers.
- props.has_depth_buffer: bool
If set to
True
the widget will allocate and enable a depth buffer for the target framebuffer.Setting this property will enable GL’s depth testing as a side effect. If you don’t need depth testing, you should call
glDisable(GL_DEPTH_TEST)
in yourGtkGLArea::render
handler.
- props.has_stencil_buffer: bool
If set to
True
the widget will allocate and enable a stencil buffer for the target framebuffer.
- props.use_es: bool
If set to
True
the widget will try to create aGdkGLContext
using OpenGL ES instead of OpenGL.Deprecated since version 4.12: Use
allowed_apis
Signals
- class GLArea.signals
- create_context() GLContext
Emitted when the widget is being realized.
This 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
set_error
to register a more detailed error of how the construction failed.
- render(context: GLContext) bool
Emitted every time the contents of the
GtkGLArea
should be redrawn.The
context
is bound to thearea
prior to emitting this function, and the buffers are painted to the window once the emission terminates.- Parameters:
context – the
GdkGLContext
used byarea
- resize(width: int, height: int) None
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.
- Parameters:
width – the width of the viewport
height – the height of the viewport
Virtual Methods
Fields
- class GLArea
- parent_instance