Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
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.
Synopsis
- newtype GLArea = GLArea (ManagedPtr GLArea)
- class (GObject o, IsDescendantOf GLArea o) => IsGLArea o
- toGLArea :: (MonadIO m, IsGLArea o) => o -> m GLArea
- gLAreaAttachBuffers :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaGetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetContext :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Maybe GLContext)
- gLAreaGetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Maybe GError)
- gLAreaGetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaGetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Int32, Int32)
- gLAreaGetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- gLAreaMakeCurrent :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaNew :: (HasCallStack, MonadIO m) => m GLArea
- gLAreaQueueRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaSetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Maybe GError -> m ()
- gLAreaSetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- gLAreaSetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Int32 -> Int32 -> m ()
- gLAreaSetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- constructGLAreaAutoRender :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)
- getGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- getGLAreaContext :: (MonadIO m, IsGLArea o) => o -> m (Maybe GLContext)
- constructGLAreaHasDepthBuffer :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)
- getGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- constructGLAreaHasStencilBuffer :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)
- getGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- constructGLAreaUseEs :: (IsGLArea o, MonadIO m) => Bool -> m (GValueConstruct o)
- getGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- type GLAreaCreateContextCallback = IO GLContext
- afterGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaCreateContextCallback) -> m SignalHandlerId
- onGLAreaCreateContext :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaCreateContextCallback) -> m SignalHandlerId
- type GLAreaRenderCallback = GLContext -> IO Bool
- afterGLAreaRender :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaRenderCallback) -> m SignalHandlerId
- onGLAreaRender :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaRenderCallback) -> m SignalHandlerId
- type GLAreaResizeCallback = Int32 -> Int32 -> IO ()
- afterGLAreaResize :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaResizeCallback) -> m SignalHandlerId
- onGLAreaResize :: (IsGLArea a, MonadIO m) => a -> ((?self :: a) => GLAreaResizeCallback) -> m SignalHandlerId
Exported types
Memory-managed wrapper type.
Instances
Eq GLArea Source # | |
GObject GLArea Source # | |
Defined in GI.Gtk.Objects.GLArea | |
ManagedPtrNewtype GLArea Source # | |
Defined in GI.Gtk.Objects.GLArea toManagedPtr :: GLArea -> ManagedPtr GLArea | |
TypedObject GLArea Source # | |
Defined in GI.Gtk.Objects.GLArea | |
HasParentTypes GLArea Source # | |
Defined in GI.Gtk.Objects.GLArea | |
IsGValue (Maybe GLArea) Source # | Convert |
Defined in GI.Gtk.Objects.GLArea gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe GLArea -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe GLArea) | |
type ParentTypes GLArea Source # | |
Defined in GI.Gtk.Objects.GLArea |
class (GObject o, IsDescendantOf GLArea o) => IsGLArea o Source #
Instances
(GObject o, IsDescendantOf GLArea o) => IsGLArea o Source # | |
Defined in GI.Gtk.Objects.GLArea |
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
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area is in auto render mode or not.
getContext
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m (Maybe GLContext) | Returns: the |
Retrieves the GdkGLContext
used by area
.
getError
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m (Maybe GError) | Returns: the |
Gets the current error set on the area
.
getHasDepthBuffer
gLAreaGetHasDepthBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a depth buffer.
getHasStencilBuffer
gLAreaGetHasStencilBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a stencil buffer.
getRequiredVersion
gLAreaGetRequiredVersion Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m (Int32, Int32) |
Retrieves the required version of OpenGL.
getUseEs
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the GtkGLArea
should use OpenGL ES.
See gLAreaSetUseEs
.
makeCurrent
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m) | |
=> m GLArea | Returns: a new |
Creates a new GtkGLArea
widget.
queueRender
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> 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
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Maybe GError |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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 Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Int32 |
|
-> Int32 |
|
-> 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
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> 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) Source #
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 Source #
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 () Source #
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) Source #
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) Source #
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 Source #
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 () Source #
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) Source #
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 Source #
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 () Source #
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) Source #
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 Source #
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 () Source #
Set the value of the “use-es
” property.
When overloading is enabled, this is equivalent to
set
gLArea [ #useEs:=
value ]
Signals
createContext
type GLAreaCreateContextCallback Source #
= IO GLContext | Returns: a newly created |
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 Source #
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 Source #
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 Source #
= GLContext |
|
-> IO Bool | Returns: |
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 Source #
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 Source #
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 Source #
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 Source #
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 Source #
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