:right-sidebar: True GLArea =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: GLArea(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gtk.Widget`, :class:`~gi.repository.GObject.InitiallyUnowned`, :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget` ``GtkGLArea`` is a widget that allows drawing with OpenGL. .. image:: https://docs.gtk.org/gtk4/glarea.png ``GtkGLArea`` sets up its own :obj:`~gi.repository.Gdk.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 :obj:`~gi.repository.Gtk.GLArea.signals.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 :obj:`~gi.repository.Gtk.GLArea.signals.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. .. code-block:: :dedent: 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 :obj:`~gi.repository.Gtk.Widget.signals.realize` signal; you can use the :obj:`~gi.repository.Gtk.Widget.signals.unrealize` signal to clean up. Since the ``GdkGLContext`` creation and initialization may fail, you will need to check for errors, using :obj:`~gi.repository.Gtk.GLArea.get_error`. An example of how to safely initialize the GL state is: .. code-block:: :dedent: 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 :obj:`~gi.repository.Gtk.GLArea.signals.create_context` signal. Constructors ------------ .. rst-class:: interim-class .. class:: GLArea :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Widget Creates a new ``GtkGLArea`` widget. Methods ------- .. rst-class:: interim-class .. class:: GLArea :no-index: .. method:: 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 the ``area`` are created and bound to the framebuffer. This function is automatically called before emitting the :obj:`~gi.repository.Gtk.GLArea.signals.render` signal, and doesn't normally need to be called by application code. .. method:: get_allowed_apis() -> ~gi.repository.Gdk.GLAPI Gets the allowed APIs. See :obj:`~gi.repository.Gtk.GLArea.set_allowed_apis`. .. versionadded:: 4.12 .. method:: get_api() -> ~gi.repository.Gdk.GLAPI Gets the API that is currently in use. If the GL area has not been realized yet, 0 is returned. .. versionadded:: 4.12 .. method:: get_auto_render() -> bool Returns whether the area is in auto render mode or not. .. method:: get_context() -> ~gi.repository.Gdk.GLContext | None Retrieves the ``GdkGLContext`` used by ``area``. .. method:: get_error() -> ~gi.repository.GLib.GError | None Gets the current error set on the ``area``. .. method:: get_has_depth_buffer() -> bool Returns whether the area has a depth buffer. .. method:: get_has_stencil_buffer() -> bool Returns whether the area has a stencil buffer. .. method:: get_required_version() -> tuple[int, int] Retrieves the required version of OpenGL. See :obj:`~gi.repository.Gtk.GLArea.set_required_version`. .. method:: get_use_es() -> bool Returns whether the ``GtkGLArea`` should use OpenGL ES. See :obj:`~gi.repository.Gtk.GLArea.set_use_es`. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.GLArea.get_api` .. method:: make_current() -> None Ensures that the ``GdkGLContext`` used by ``area`` is associated with the ``GtkGLArea``. This function is automatically called before emitting the :obj:`~gi.repository.Gtk.GLArea.signals.render` signal, and doesn't normally need to be called by application code. .. method:: queue_render() -> None Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget. This ensures that the :obj:`~gi.repository.Gtk.GLArea.signals.render` signal is emitted during the draw. This is only needed when :obj:`~gi.repository.Gtk.GLArea.set_auto_render` has been called with a :const:`False` value. The default behaviour is to emit :obj:`~gi.repository.Gtk.GLArea.signals.render` on each draw. .. method:: set_allowed_apis(apis: ~gi.repository.Gdk.GLAPI) -> None Sets the allowed APIs to create a context with. You should check :obj:`~gi.repository.Gtk.GLArea.props.api` before drawing with either API. By default, all APIs are allowed. .. versionadded:: 4.12 :param apis: the allowed APIs .. method:: set_auto_render(auto_render: bool) -> None Sets whether the ``GtkGLArea`` is in auto render mode. If ``auto_render`` is :const:`True` the :obj:`~gi.repository.Gtk.GLArea.signals.render` 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`` is :const:`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 rendering :obj:`~gi.repository.Gtk.GLArea.queue_render` must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. :param auto_render: a boolean .. method:: set_error(error: ~gi.repository.GLib.GError | None = None) -> None Sets an error on the area which will be shown instead of the GL rendering. This is useful in the :obj:`~gi.repository.Gtk.GLArea.signals.create_context` signal if GL context creation fails. :param error: a new ``GError``, or :const:`None` to unset the error .. method:: set_has_depth_buffer(has_depth_buffer: bool) -> None Sets whether the ``GtkGLArea`` should use a depth buffer. If ``has_depth_buffer`` is :const:`True` the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none. :param has_depth_buffer: :const:`True` to add a depth buffer .. method:: set_has_stencil_buffer(has_stencil_buffer: bool) -> None Sets whether the ``GtkGLArea`` should use a stencil buffer. If ``has_stencil_buffer`` is :const:`True` the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none. :param has_stencil_buffer: :const:`True` to add a stencil buffer .. method:: 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. :param major: the major version :param minor: the minor version .. method:: 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:: 4.12 Use :obj:`~gi.repository.Gtk.GLArea.set_allowed_apis` :param use_es: whether to use OpenGL or OpenGL ES Properties ---------- .. rst-class:: interim-class .. class:: GLArea :no-index: .. attribute:: props.allowed_apis :type: ~gi.repository.Gdk.GLAPI The allowed APIs. .. versionadded:: 4.12 .. attribute:: props.api :type: ~gi.repository.Gdk.GLAPI The API currently in use. .. versionadded:: 4.12 .. attribute:: props.auto_render :type: bool If set to :const:`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 :const:`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 rendering :obj:`~gi.repository.Gtk.GLArea.queue_render` must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw. .. attribute:: props.context :type: ~gi.repository.Gdk.GLContext The ``GdkGLContext`` used by the ``GtkGLArea`` widget. The ``GtkGLArea`` widget is responsible for creating the ``GdkGLContext`` instance. If you need to render with other kinds of buffers (stencil, depth, etc), use render buffers. .. attribute:: props.has_depth_buffer :type: bool If set to :const:`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 your ``GtkGLArea::render`` handler. .. attribute:: props.has_stencil_buffer :type: bool If set to :const:`True` the widget will allocate and enable a stencil buffer for the target framebuffer. .. attribute:: props.use_es :type: bool If set to :const:`True` the widget will try to create a ``GdkGLContext`` using OpenGL ES instead of OpenGL. .. deprecated:: 4.12 Use :obj:`~gi.repository.Gtk.GLArea.props.allowed_apis` Signals ------- .. rst-class:: interim-class .. class:: GLArea.signals :no-index: .. method:: create_context() -> ~gi.repository.Gdk.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 :obj:`~gi.repository.Gtk.GLArea.set_error` to register a more detailed error of how the construction failed. .. method:: render(context: ~gi.repository.Gdk.GLContext) -> bool Emitted every time the contents of the ``GtkGLArea`` 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. :param context: the ``GdkGLContext`` used by ``area`` .. method:: 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. :param width: the width of the viewport :param height: the height of the viewport Virtual Methods --------------- .. rst-class:: interim-class .. class:: GLArea :no-index: .. method:: do_render(context: ~gi.repository.Gdk.GLContext) -> bool class closure for the ``GtkGLArea::render`` signal :param context: .. method:: do_resize(width: int, height: int) -> None class closeure for the ``GtkGLArea::resize`` signal :param width: :param height: Fields ------ .. rst-class:: interim-class .. class:: GLArea :no-index: .. attribute:: parent_instance