GI.Gtk.Objects.GLArea

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.

In order to draw, you have to connect to the GLArea::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 GLArea::render signal:

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

c code

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 Widget::realize signal; you can use the Widget::unrealize signal to clean up. Since the GdkGLContext creation and initialization may fail, you will need to check for errors, using gLAreaGetError.

An example of how to safely initialize the GL state is:

c code

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 GLArea::createContext signal.

Exported types

newtype GLArea

Memory-managed wrapper type.

Constructors

GLArea (ManagedPtr GLArea)

Instances

Eq GLArea

Defined in GI.Gtk.Objects.GLArea

Methods

(==) :: GLArea -> GLArea -> Bool

(/=) :: GLArea -> GLArea -> Bool

GObject GLArea

Defined in GI.Gtk.Objects.GLArea

ManagedPtrNewtype GLArea

Defined in GI.Gtk.Objects.GLArea

Methods

toManagedPtr :: GLArea -> ManagedPtr GLArea

TypedObject GLArea

Defined in GI.Gtk.Objects.GLArea

Methods

glibType :: IO GType

HasParentTypes GLArea

Defined in GI.Gtk.Objects.GLArea

IsGValue (Maybe GLArea)

Convert GLArea to and from GValue. See toGValue and fromGValue.

Defined in GI.Gtk.Objects.GLArea

Methods

gvalueGType_ :: IO GType

gvalueSet_ :: Ptr GValue -> Maybe GLArea -> IO ()

gvalueGet_ :: Ptr GValue -> IO (Maybe GLArea)

type ParentTypes GLArea

Defined in GI.Gtk.Objects.GLArea

type ParentTypes GLArea = '[Widget, Object, Accessible, Buildable, ConstraintTarget]

class (GObject o, IsDescendantOf GLArea o) => IsGLArea o

Type class for types which can be safely cast to GLArea, for instance with toGLArea.

Instances

(GObject o, IsDescendantOf GLArea o) => IsGLArea o

Defined in GI.Gtk.Objects.GLArea

toGLArea :: (MonadIO m, IsGLArea o) => o -> m GLArea

Cast to GLArea, for types for which this is known to be safe. For general casts, use castTo.

Methods

Click to display all available methods, including inherited ones

Methods

actionSetEnabled, activate, activateAction, activateDefault, addController, addCssClass, addMnemonicLabel, addTickCallback, allocate, attachBuffers, bindProperty, bindPropertyFull, childFocus, computeBounds, computeExpand, computePoint, computeTransform, contains, createPangoContext, createPangoLayout, disposeTemplate, dragCheckThreshold, errorBell, forceFloating, freezeNotify, getv, grabFocus, hasCssClass, hasDefault, hasFocus, hasVisibleFocus, hide, inDestruction, initTemplate, insertActionGroup, insertAfter, insertBefore, isAncestor, isDrawable, isFloating, isFocus, isSensitive, isVisible, keynavFailed, listMnemonicLabels, makeCurrent, map, measure, mnemonicActivate, notify, notifyByPspec, observeChildren, observeControllers, pick, queueAllocate, queueDraw, queueRender, queueResize, realize, ref, refSink, removeController, removeCssClass, removeMnemonicLabel, removeTickCallback, resetProperty, resetRelation, resetState, runDispose, shouldLayout, show, sizeAllocate, snapshotChild, stealData, stealQdata, thawNotify, translateCoordinates, triggerTooltipQuery, unmap, unparent, unrealize, unref, unsetStateFlags, updateNextAccessibleSibling, updateProperty, updateRelation, updateState, watchClosure.

Getters

getAccessibleParent, getAccessibleRole, getAllocatedBaseline, getAllocatedHeight, getAllocatedWidth, getAllocation, getAncestor, getAtContext, getAutoRender, getBounds, getBuildableId, getCanFocus, getCanTarget, getChildVisible, getClipboard, getColor, getContext, getCssClasses, getCssName, getCursor, getData, getDirection, getDisplay, getError, getFirstAccessibleChild, getFirstChild, getFocusChild, getFocusOnClick, getFocusable, getFontMap, getFontOptions, getFrameClock, getHalign, getHasDepthBuffer, getHasStencilBuffer, getHasTooltip, getHeight, getHexpand, getHexpandSet, getLastChild, getLayoutManager, getMapped, getMarginBottom, getMarginEnd, getMarginStart, getMarginTop, getName, getNative, getNextAccessibleSibling, getNextSibling, getOpacity, getOverflow, getPangoContext, getParent, getPlatformState, getPreferredSize, getPrevSibling, getPrimaryClipboard, getProperty, getQdata, getRealized, getReceivesDefault, getRequestMode, getRequiredVersion, getRoot, getScaleFactor, getSensitive, getSettings, getSize, getSizeRequest, getStateFlags, getStyleContext, getTemplateChild, getTooltipMarkup, getTooltipText, getUseEs, getValign, getVexpand, getVexpandSet, getVisible, getWidth.

Setters

setAccessibleParent, setAutoRender, setCanFocus, setCanTarget, setChildVisible, setCssClasses, setCursor, setCursorFromName, setData, setDataFull, setDirection, setError, setFocusChild, setFocusOnClick, setFocusable, setFontMap, setFontOptions, setHalign, setHasDepthBuffer, setHasStencilBuffer, setHasTooltip, setHexpand, setHexpandSet, setLayoutManager, setMarginBottom, setMarginEnd, setMarginStart, setMarginTop, setName, setOpacity, setOverflow, setParent, setProperty, setReceivesDefault, setRequiredVersion, setSensitive, setSizeRequest, setStateFlags, setTooltipMarkup, setTooltipText, setUseEs, setValign, setVexpand, setVexpandSet, setVisible.

attachBuffers

gLAreaAttachBuffers

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m ()

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 GLArea::render signal, and doesn't normally need to be called by application code.

getAutoRender

gLAreaGetAutoRender

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m Bool

Returns: True if the area is auto rendering, False otherwise

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

getContext

gLAreaGetContext

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m (Maybe GLContext)

Returns: the GdkGLContext

Retrieves the GdkGLContext used by area.

getError

gLAreaGetError

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m (Maybe GError)

Returns: the GError

Gets the current error set on the area.

getHasDepthBuffer

gLAreaGetHasDepthBuffer

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m Bool

Returns: True if the area has a depth buffer, False otherwise

Returns whether the area has a depth buffer.

getHasStencilBuffer

gLAreaGetHasStencilBuffer

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m Bool

Returns: True if the area has a stencil buffer, False otherwise

Returns whether the area has a stencil buffer.

getRequiredVersion

gLAreaGetRequiredVersion

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m (Int32, Int32)

Retrieves the required version of OpenGL.

See gLAreaSetRequiredVersion.

getUseEs

gLAreaGetUseEs

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m Bool

Returns: True if the GtkGLArea should create an OpenGL ES context and False otherwise

Returns whether the GtkGLArea should use OpenGL ES.

See gLAreaSetUseEs.

makeCurrent

gLAreaMakeCurrent

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m ()

Ensures that the GdkGLContext used by area is associated with the GtkGLArea.

This function is automatically called before emitting the GLArea::render signal, and doesn't normally need to be called by application code.

new

gLAreaNew

Arguments

:: (HasCallStack, MonadIO m)

=> m GLArea

Returns: a new GtkGLArea

Creates a new GtkGLArea widget.

queueRender

gLAreaQueueRender

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> m ()

Marks the currently rendered data (if any) as invalid, and queues a redraw of the widget.

This ensures that the GLArea::render signal is emitted during the draw.

This is only needed when gLAreaSetAutoRender has been called with a False value. The default behaviour is to emit GLArea::render on each draw.

setAutoRender

gLAreaSetAutoRender

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Bool

autoRender: a boolean

-> m ()

Sets whether the GtkGLArea is in auto render mode.

If autoRender is True the GLArea::render signal will be emitted every time the widget draws. This is the default and is useful if drawing the widget is faster.

If autoRender 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 gLAreaQueueRender must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.

setError

gLAreaSetError

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Maybe GError

error: a new GError, or Nothing to unset the error

-> m ()

Sets an error on the area which will be shown instead of the GL rendering.

This is useful in the GLArea::createContext signal if GL context creation fails.

setHasDepthBuffer

gLAreaSetHasDepthBuffer

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Bool

hasDepthBuffer: True to add a depth buffer

-> m ()

Sets whether the GtkGLArea should use a depth buffer.

If hasDepthBuffer is True the widget will allocate and enable a depth buffer for the target framebuffer. Otherwise there will be none.

setHasStencilBuffer

gLAreaSetHasStencilBuffer

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Bool

hasStencilBuffer: True to add a stencil buffer

-> m ()

Sets whether the GtkGLArea should use a stencil buffer.

If hasStencilBuffer is True the widget will allocate and enable a stencil buffer for the target framebuffer. Otherwise there will be none.

setRequiredVersion

gLAreaSetRequiredVersion

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Int32

major: the major version

-> Int32

minor: the minor version

-> m ()

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.

setUseEs

gLAreaSetUseEs

Arguments

:: (HasCallStack, MonadIO m, IsGLArea a)

=> a

area: a GtkGLArea

-> Bool

useEs: whether to use OpenGL or OpenGL ES

-> m ()

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.

Properties

autoRender

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 gLAreaQueueRender must be called. This mode is useful when the scene changes seldom, but takes a long time to redraw.

constructGLAreaAutoRender :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “auto-render” property. This is rarely needed directly, but it is used by new.

getGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> m Bool

Get the value of the “auto-render” property. When overloading is enabled, this is equivalent to

get gLArea #autoRender

setGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()

Set the value of the “auto-render” property. When overloading is enabled, this is equivalent to

set gLArea [ #autoRender := value ]

context

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.

getGLAreaContext :: (MonadIO m, IsGLArea o) => o -> m (Maybe GLContext)

Get the value of the “context” property. When overloading is enabled, this is equivalent to

get gLArea #context

hasDepthBuffer

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.

constructGLAreaHasDepthBuffer :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “has-depth-buffer” property. This is rarely needed directly, but it is used by new.

getGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool

Get the value of the “has-depth-buffer” property. When overloading is enabled, this is equivalent to

get gLArea #hasDepthBuffer

setGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()

Set the value of the “has-depth-buffer” property. When overloading is enabled, this is equivalent to

set gLArea [ #hasDepthBuffer := value ]

hasStencilBuffer

If set to True the widget will allocate and enable a stencil buffer for the target framebuffer.

constructGLAreaHasStencilBuffer :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “has-stencil-buffer” property. This is rarely needed directly, but it is used by new.

getGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool

Get the value of the “has-stencil-buffer” property. When overloading is enabled, this is equivalent to

get gLArea #hasStencilBuffer

setGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()

Set the value of the “has-stencil-buffer” property. When overloading is enabled, this is equivalent to

set gLArea [ #hasStencilBuffer := value ]

useEs

If set to True the widget will try to create a GdkGLContext using OpenGL ES instead of OpenGL.

constructGLAreaUseEs :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)

Construct a GValueConstruct with valid value for the “use-es” property. This is rarely needed directly, but it is used by new.

getGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> m Bool

Get the value of the “use-es” property. When overloading is enabled, this is equivalent to

get gLArea #useEs

setGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()

Set the value of the “use-es” property. When overloading is enabled, this is equivalent to

set gLArea [ #useEs := value ]

Signals

createContext

type GLAreaCreateContextCallback

Arguments

 = IO GLContext

Returns: a newly created GdkGLContext; the GtkGLArea widget will take ownership of the returned value.

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 gLAreaSetError to register a more detailed error of how the construction failed.

afterGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaCreateContextCallback) -> m SignalHandlerId

Connect a signal handler for the createContext signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after gLArea #createContext callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaCreateContextCallback) -> m SignalHandlerId

Connect a signal handler for the createContext signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on gLArea #createContext callback

render

type GLAreaRenderCallback

Arguments

 = GLContext

context: the GdkGLContext used by area

-> IO Bool

Returns: True to stop other handlers from being invoked for the event. False to propagate the event further.

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.

afterGLAreaRender :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaRenderCallback) -> m SignalHandlerId

Connect a signal handler for the render signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after gLArea #render callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onGLAreaRender :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaRenderCallback) -> m SignalHandlerId

Connect a signal handler for the render signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on gLArea #render callback

resize

type GLAreaResizeCallback

Arguments

 = Int32

width: the width of the viewport

-> Int32

height: the height of the viewport

-> IO ()

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.

afterGLAreaResize :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaResizeCallback) -> m SignalHandlerId

Connect a signal handler for the resize signal, to be run after the default handler. When overloading is enabled, this is equivalent to

after gLArea #resize callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit ?self parameter. Note that this requires activating the ImplicitParams GHC extension.

onGLAreaResize :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaResizeCallback) -> m SignalHandlerId

Connect a signal handler for the resize signal, to be run before the default handler. When overloading is enabled, this is equivalent to

on gLArea #resize callback