Gtk.GLArea

Gtk.GLArea — A widget for custom drawing with OpenGL

Object Hierarchy:

    GObject
    ╰── GInitiallyUnowned
        ╰── Gtk.Widget
            ╰── Gtk.GLArea

Functions:

Signals:

  • “create-context” (area, error, user_data)
  • “render” (area, context, user_data)
  • “resize” (area, width, height, user_data)

Description:

Gtk.GLArea is a widget that allows drawing with OpenGL.

Gtk.GLArea sets up its own Gdk.GLContext 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 Gtk.GLArea::“render“ signal, or subclass Gtk.GLArea and override the Gtk.GLAreaClass.render() virtual function.

The Gtk.GLArea widget ensures that the Gdk.GLContext 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 Gtk.GLArea

The simplest way to draw using OpenGL commands in a Gtk.GLArea is to create a widget instance and connect to the “render” signal:

        # create a Gtk.GLArea instance
        area = Gtk.GLArea()
        area.connect('render', self.on_render)

    def on_render(self, widget):
        print("Render GLArea")

The render() function will be called when the Gtk.GLArea is ready for you to draw its content:

        area = Gtk.GLArea()
        self.add(area)

        area.connect('render', self.on_render)
        area.connect('realize', self.on_realize)

    def on_render(self, area, context):  
        area.make_current()

        w = area.get_allocated_width()
        h = area.get_allocated_height()
        glViewport(0, 0, w, h)

        # inside this function it's safe to use GL; the given
        # Gdk.GLContext has been made current to the drawable
        # surface used by the Gtk.GLArea and the viewport has
        # already been set to be the size of the allocation
        # we can start by clearing the buffer        
        glClearColor(1, 1, 1, 0)
        glClear(GL_COLOR_BUFFER_BIT)

        # draw your object  
        glColor3f(0, 0, 0)           
        glBegin(GL_TRIANGLES)
        glVertex3f ( 0.0, 1.0, 0.0)
        glVertex3f (-1.0,-1.0, 0.0)
        glVertex3f ( 1.0,-1.0, 0.0)
        glEnd()

        # 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 Gtk.Widget “realize“ signal; you can use the Gtk.Widget “unrealize“ signal to clean up. Since the Gdk.GLContext creation and initialization may fail, you will need to check for errors, using Gtk.GLarea::get_error(). An example of how to safely initialize the GL state is:

    def on_realize(self, area):        
        # We need to make the context current if we want to
        # call GL API
        area.make_current()            

        # If there were errors during the initialization or
        # when trying to make the context current, this
        # function will return a Gio.Error for you to catch
        if (area.get_error() != None):
          return      

        self.init_buffers()
        self.init_shaders()

If you need to change the options for creating the #GdkGLContext you should use the “create-context“ signal.

Function Details:

new()

new () -> Gtk.Widget

Creates a new Gtk.GLArea widget.

  • Returns: the newly created Gtk.GLArea.

  • Since: 3.16

get_context()

get_context (self) -> Gdk.GLContext

Retrieves the GdkGLContext used by area.

  • Returns: the GdkGLContext.

  • Since: 3.16

make_current()

make_current (self)

Ensures that the GdkGLContext used by area is associated withthe Gtk.GLArea. This function is automatically called before emitting the“render” signal, and doesn't normally need to be calledby application code.

  • Since: 3.16

queue_render()

queue_render (self)

Marks the currently rendered data (if any) as invalid, and queuesa redraw of the widget, ensuring that the “render” signalis emitted during the draw. This is only needed when the Gtk.GLArea:set_auto_render() hasbeen called with a FALSE value. The default behaviour is toemit “render” on each draw.

  • Since: 3.16

attach_buffers()

attach_buffers (self)

Ensures that the area framebuffer object is made the current drawand read target, and that all the required buffers for the areaare created and bound to the frambuffer. This function is automatically called before emitting the“render” signal, and doesn't normally need to be calledby application code.

  • Since: 3.16

set_error()

set_error (self, error:error=None)

Sets an error on the area which will be shown instead of theGL rendering. This is useful in the “create-context”signal if GL context creation fails.

  • Since: 3.16

get_error()

get_error (self) -> error

Gets the current error set on the area.

  • Returns: the GError or None.

  • Since: 3.16

set_has_alpha()

set_has_alpha (self, has_alpha:bool)

If has_alpha is True the buffer allocated by the widget will havean alpha channel component, and when rendering to the window theresult will be composited over whatever is below the widget. If has_alpha is FALSE there will be no alpha channel, and thebuffer will fully replace anything below the widget.

  • Since: 3.16

get_has_alpha()

get_has_alpha (self) -> bool

Returns whether the area has an alpha component.

  • Returns: True if the areahas an alpha component, FALSE otherwise

  • Since: 3.16

set_has_depth_buffer()

set_has_depth_buffer (self, has_depth_buffer:bool)

If has_depth_buffer is True the widget will allocate andenable a depth buffer for the target framebuffer. Otherwisethere will be none.

  • Since: 3.16

get_has_depth_buffer()

get_has_depth_buffer (self) -> bool

Returns whether the area has a depth buffer.

  • Returns: True if the areahas a depth buffer, FALSE otherwise

  • Since: 3.16

set_has_stencil_buffer()

set_has_stencil_buffer (self, has_stencil_buffer:bool)

If has_stencil_buffer is True the widget will allocate andenable a stencil buffer for the target framebuffer. Otherwisethere will be none.

  • Since: 3.16

get_has_stencil_buffer()

get_has_stencil_buffer (self) -> bool

Returns whether the area has a stencil buffer.

  • Returns: True if the areahas a stencil buffer, FALSE otherwise

  • Since: 3.16

set_auto_render()

set_auto_render (self, auto_render:bool)

If auto_render is True the “render” signal will beemitted every time the widget draws. This is the default and isuseful if drawing the widget is faster. If auto_render is FALSE the data from previous rendering is keptaround and will be used for drawing the widget the next time,unless the window is resized. In order to force a renderingGtk.GLArea:queue_render() must be called. This mode is useful whenthe scene changes seldomly, but takes a long time to redraw.

  • Since: 3.16

get_auto_render()

get_auto_render (self) -> bool

Returns whether the area is in auto render mode or not.

  • Returns: True if the areais auto rendering, FALSE otherwise

  • Since: 3.16

get_required_version()

get_required_version (self) -> major:int, minor:int

Retrieves the required version of OpenGL setusing Gtk.GLArea:set_required_version().

  • Since: 3.16

set_required_version()

set_required_version (self, major:int, minor:int)

Sets the required version of OpenGL to be used when creating the contextfor the widget. This function must be called before the area has been realized.

  • Since: 3.16

results matching ""

    No results matching ""