GLArea

class GLArea(**properties: Any)

Superclasses: Widget, InitiallyUnowned, Object

Implemented Interfaces: Accessible, Buildable, ConstraintTarget

Constructors:

GLArea(**properties)
new() -> Gtk.Widget

Constructors

class GLArea

classmethod new() → Widget

Creates a new GtkGLArea widget.

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 the area 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_auto_render() → bool

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

get_context() → GLContext | None

Retrieves the GdkGLContext used by area.

get_error() → GError | None

Gets the current error set on the area.

get_has_depth_buffer() → bool

Returns whether the area has a depth buffer.

get_has_stencil_buffer() → bool

Returns whether the area has a stencil buffer.

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 by area is associated with the GtkGLArea.

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 a False value. The default behaviour is to emit render 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 is 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 auto_render is 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 queue_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, or None 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 is True 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 is True 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.allowed_apis: GLAPI

The allowed APIs.

Added in version 4.12.

props.api: GLAPI

The API currently in use.

Added in version 4.12.

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 rendering queue_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 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.

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 your GtkGLArea::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 a GdkGLContext 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 the area prior to emitting this function, and the buffers are painted to the window once the emission terminates.

Parameters:

context – the GdkGLContext used by area

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

class GLArea

do_render(context: GLContext) → bool

class closure for the GtkGLArea::render signal

Parameters:

context

do_resize(width: int, height: int) → None

class closeure for the GtkGLArea::resize signal

Parameters:

• width

• height

Fields

class GLArea

parent_instance