Copyright | Will Thompson, Iñaki García Etxebarria and Jonas Platte |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria (garetxe@gmail.com) |
Safe Haskell | None |
Language | Haskell2010 |
GLArea
is a widget that allows drawing with OpenGL.
GLArea
sets up its own 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 GLArea
::render
signal,
or subclass GLArea
and override the gtkGLAreaClass
.render()
virtual
function.
The GLArea
widget ensures that the 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 GtkGLArea
The simplest way to draw using OpenGL commands in a GLArea
is to
create a widget instance and connect to the GLArea
::render
signal:
C code
// 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);
The render()
function will be called when the GLArea
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; }
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
GLContext
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 GLContext
you should use the GLArea
::create-context
signal.
- newtype GLArea = GLArea (ManagedPtr GLArea)
- class GObject o => IsGLArea o
- toGLArea :: IsGLArea o => o -> IO GLArea
- noGLArea :: Maybe GLArea
- data GLAreaAttachBuffersMethodInfo
- gLAreaAttachBuffers :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- data GLAreaGetAutoRenderMethodInfo
- gLAreaGetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- data GLAreaGetContextMethodInfo
- gLAreaGetContext :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m GLContext
- data GLAreaGetErrorMethodInfo
- gLAreaGetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Maybe GError)
- data GLAreaGetHasAlphaMethodInfo
- gLAreaGetHasAlpha :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- data GLAreaGetHasDepthBufferMethodInfo
- gLAreaGetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- data GLAreaGetHasStencilBufferMethodInfo
- gLAreaGetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- data GLAreaGetRequiredVersionMethodInfo
- gLAreaGetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m (Int32, Int32)
- data GLAreaGetUseEsMethodInfo
- gLAreaGetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m Bool
- data GLAreaMakeCurrentMethodInfo
- gLAreaMakeCurrent :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- gLAreaNew :: (HasCallStack, MonadIO m) => m GLArea
- data GLAreaQueueRenderMethodInfo
- gLAreaQueueRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> m ()
- data GLAreaSetAutoRenderMethodInfo
- gLAreaSetAutoRender :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- data GLAreaSetErrorMethodInfo
- gLAreaSetError :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Maybe GError -> m ()
- data GLAreaSetHasAlphaMethodInfo
- gLAreaSetHasAlpha :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- data GLAreaSetHasDepthBufferMethodInfo
- gLAreaSetHasDepthBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- data GLAreaSetHasStencilBufferMethodInfo
- gLAreaSetHasStencilBuffer :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- data GLAreaSetRequiredVersionMethodInfo
- gLAreaSetRequiredVersion :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Int32 -> Int32 -> m ()
- data GLAreaSetUseEsMethodInfo
- gLAreaSetUseEs :: (HasCallStack, MonadIO m, IsGLArea a) => a -> Bool -> m ()
- data GLAreaAutoRenderPropertyInfo
- constructGLAreaAutoRender :: IsGLArea o => Bool -> IO (GValueConstruct o)
- gLAreaAutoRender :: AttrLabelProxy "autoRender"
- getGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaAutoRender :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- data GLAreaContextPropertyInfo
- gLAreaContext :: AttrLabelProxy "context"
- getGLAreaContext :: (MonadIO m, IsGLArea o) => o -> m GLContext
- data GLAreaHasAlphaPropertyInfo
- constructGLAreaHasAlpha :: IsGLArea o => Bool -> IO (GValueConstruct o)
- gLAreaHasAlpha :: AttrLabelProxy "hasAlpha"
- getGLAreaHasAlpha :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasAlpha :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- data GLAreaHasDepthBufferPropertyInfo
- constructGLAreaHasDepthBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o)
- gLAreaHasDepthBuffer :: AttrLabelProxy "hasDepthBuffer"
- getGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasDepthBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- data GLAreaHasStencilBufferPropertyInfo
- constructGLAreaHasStencilBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o)
- gLAreaHasStencilBuffer :: AttrLabelProxy "hasStencilBuffer"
- getGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaHasStencilBuffer :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- data GLAreaUseEsPropertyInfo
- constructGLAreaUseEs :: IsGLArea o => Bool -> IO (GValueConstruct o)
- gLAreaUseEs :: AttrLabelProxy "useEs"
- getGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> m Bool
- setGLAreaUseEs :: (MonadIO m, IsGLArea o) => o -> Bool -> m ()
- type C_GLAreaCreateContextCallback = Ptr () -> Ptr () -> IO (Ptr GLContext)
- type GLAreaCreateContextCallback = IO GLContext
- data GLAreaCreateContextSignalInfo
- afterGLAreaCreateContext :: (GObject a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId
- genClosure_GLAreaCreateContext :: GLAreaCreateContextCallback -> IO Closure
- mk_GLAreaCreateContextCallback :: C_GLAreaCreateContextCallback -> IO (FunPtr C_GLAreaCreateContextCallback)
- noGLAreaCreateContextCallback :: Maybe GLAreaCreateContextCallback
- onGLAreaCreateContext :: (GObject a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId
- wrap_GLAreaCreateContextCallback :: GLAreaCreateContextCallback -> Ptr () -> Ptr () -> IO (Ptr GLContext)
- type C_GLAreaRenderCallback = Ptr () -> Ptr GLContext -> Ptr () -> IO CInt
- type GLAreaRenderCallback = GLContext -> IO Bool
- data GLAreaRenderSignalInfo
- afterGLAreaRender :: (GObject a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId
- genClosure_GLAreaRender :: GLAreaRenderCallback -> IO Closure
- mk_GLAreaRenderCallback :: C_GLAreaRenderCallback -> IO (FunPtr C_GLAreaRenderCallback)
- noGLAreaRenderCallback :: Maybe GLAreaRenderCallback
- onGLAreaRender :: (GObject a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId
- wrap_GLAreaRenderCallback :: GLAreaRenderCallback -> Ptr () -> Ptr GLContext -> Ptr () -> IO CInt
- type C_GLAreaResizeCallback = Ptr () -> Int32 -> Int32 -> Ptr () -> IO ()
- type GLAreaResizeCallback = Int32 -> Int32 -> IO ()
- data GLAreaResizeSignalInfo
- afterGLAreaResize :: (GObject a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId
- genClosure_GLAreaResize :: GLAreaResizeCallback -> IO Closure
- mk_GLAreaResizeCallback :: C_GLAreaResizeCallback -> IO (FunPtr C_GLAreaResizeCallback)
- noGLAreaResizeCallback :: Maybe GLAreaResizeCallback
- onGLAreaResize :: (GObject a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId
- wrap_GLAreaResizeCallback :: GLAreaResizeCallback -> Ptr () -> Int32 -> Int32 -> Ptr () -> IO ()
Exported types
GObject GLArea Source # | |
IsImplementorIface GLArea Source # | |
IsObject GLArea Source # | |
IsWidget GLArea Source # | |
IsBuildable GLArea Source # | |
IsGLArea GLArea Source # | |
((~) * info (ResolveGLAreaMethod t GLArea), MethodInfo * info GLArea p) => IsLabel t (GLArea -> p) Source # | |
((~) * info (ResolveGLAreaMethod t GLArea), MethodInfo * info GLArea p) => IsLabelProxy t (GLArea -> p) Source # | |
HasAttributeList * GLArea Source # | |
type AttributeList GLArea Source # | |
type SignalList GLArea Source # | |
Methods
attachBuffers
data GLAreaAttachBuffersMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaAttachBuffersMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m () |
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 frambuffer.
This function is automatically called before emitting the
GLArea
::render
signal, and doesn't normally need to be called
by application code.
Since: 3.16
getAutoRender
data GLAreaGetAutoRenderMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetAutoRenderMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area is in auto render mode or not.
Since: 3.16
getContext
data GLAreaGetContextMethodInfo Source #
((~) * signature (m GLContext), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetContextMethodInfo a signature Source # | |
Retrieves the GLContext
used by area
.
Since: 3.16
getError
data GLAreaGetErrorMethodInfo Source #
((~) * signature (m (Maybe GError)), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetErrorMethodInfo a signature Source # | |
Gets the current error set on the area
.
Since: 3.16
getHasAlpha
data GLAreaGetHasAlphaMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetHasAlphaMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has an alpha component.
Since: 3.16
getHasDepthBuffer
data GLAreaGetHasDepthBufferMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetHasDepthBufferMethodInfo a signature Source # | |
gLAreaGetHasDepthBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a depth buffer.
Since: 3.16
getHasStencilBuffer
data GLAreaGetHasStencilBufferMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetHasStencilBufferMethodInfo a signature Source # | |
gLAreaGetHasStencilBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Returns whether the area has a stencil buffer.
Since: 3.16
getRequiredVersion
data GLAreaGetRequiredVersionMethodInfo Source #
((~) * signature (m (Int32, Int32)), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetRequiredVersionMethodInfo a signature Source # | |
gLAreaGetRequiredVersion Source #
Retrieves the required version of OpenGL set
using gLAreaSetRequiredVersion
.
Since: 3.16
getUseEs
data GLAreaGetUseEsMethodInfo Source #
((~) * signature (m Bool), MonadIO m, IsGLArea a) => MethodInfo * GLAreaGetUseEsMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m Bool | Returns: |
Retrieves the value set by gLAreaSetUseEs
.
Since: 3.22
makeCurrent
data GLAreaMakeCurrentMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaMakeCurrentMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m () |
new
:: (HasCallStack, MonadIO m) | |
=> m GLArea | Returns: the newly created |
Creates a new GLArea
widget.
Since: 3.16
queueRender
data GLAreaQueueRenderMethodInfo Source #
((~) * signature (m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaQueueRenderMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> m () |
Marks the currently rendered data (if any) as invalid, and queues
a redraw of the widget, ensuring that the GLArea
::render
signal
is emitted during the draw.
This is only needed when the gLAreaSetAutoRender
has
been called with a False
value. The default behaviour is to
emit GLArea
::render
on each draw.
Since: 3.16
setAutoRender
data GLAreaSetAutoRenderMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetAutoRenderMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> m () |
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 seldomly, but takes a long time to redraw.
Since: 3.16
setError
data GLAreaSetErrorMethodInfo Source #
((~) * signature (Maybe GError -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetErrorMethodInfo a signature Source # | |
Sets an error on the area which will be shown instead of the
GL rendering. This is useful in the GLArea
::create-context
signal if GL context creation fails.
Since: 3.16
setHasAlpha
data GLAreaSetHasAlphaMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetHasAlphaMethodInfo a signature Source # | |
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> m () |
If hasAlpha
is True
the buffer allocated by the widget will have
an alpha channel component, and when rendering to the window the
result will be composited over whatever is below the widget.
If hasAlpha
is False
there will be no alpha channel, and the
buffer will fully replace anything below the widget.
Since: 3.16
setHasDepthBuffer
data GLAreaSetHasDepthBufferMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetHasDepthBufferMethodInfo a signature Source # | |
gLAreaSetHasDepthBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> m () |
If hasDepthBuffer
is True
the widget will allocate and
enable a depth buffer for the target framebuffer. Otherwise
there will be none.
Since: 3.16
setHasStencilBuffer
data GLAreaSetHasStencilBufferMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetHasStencilBufferMethodInfo a signature Source # | |
gLAreaSetHasStencilBuffer Source #
:: (HasCallStack, MonadIO m, IsGLArea a) | |
=> a |
|
-> Bool |
|
-> m () |
If hasStencilBuffer
is True
the widget will allocate and
enable a stencil buffer for the target framebuffer. Otherwise
there will be none.
Since: 3.16
setRequiredVersion
data GLAreaSetRequiredVersionMethodInfo Source #
((~) * signature (Int32 -> Int32 -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetRequiredVersionMethodInfo a signature Source # | |
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.
Since: 3.16
setUseEs
data GLAreaSetUseEsMethodInfo Source #
((~) * signature (Bool -> m ()), MonadIO m, IsGLArea a) => MethodInfo * GLAreaSetUseEsMethodInfo a signature Source # | |
:: (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 GLContext
before drawing
with either API.
Since: 3.22
Properties
autoRender
data GLAreaAutoRenderPropertyInfo Source #
constructGLAreaAutoRender :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
gLAreaAutoRender :: AttrLabelProxy "autoRender" Source #
context
data GLAreaContextPropertyInfo Source #
gLAreaContext :: AttrLabelProxy "context" Source #
hasAlpha
data GLAreaHasAlphaPropertyInfo Source #
constructGLAreaHasAlpha :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
gLAreaHasAlpha :: AttrLabelProxy "hasAlpha" Source #
hasDepthBuffer
data GLAreaHasDepthBufferPropertyInfo Source #
constructGLAreaHasDepthBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
gLAreaHasDepthBuffer :: AttrLabelProxy "hasDepthBuffer" Source #
hasStencilBuffer
data GLAreaHasStencilBufferPropertyInfo Source #
constructGLAreaHasStencilBuffer :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
gLAreaHasStencilBuffer :: AttrLabelProxy "hasStencilBuffer" Source #
useEs
data GLAreaUseEsPropertyInfo Source #
constructGLAreaUseEs :: IsGLArea o => Bool -> IO (GValueConstruct o) Source #
gLAreaUseEs :: AttrLabelProxy "useEs" Source #
Signals
createContext
afterGLAreaCreateContext :: (GObject a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId Source #
mk_GLAreaCreateContextCallback :: C_GLAreaCreateContextCallback -> IO (FunPtr C_GLAreaCreateContextCallback) Source #
onGLAreaCreateContext :: (GObject a, MonadIO m) => a -> GLAreaCreateContextCallback -> m SignalHandlerId Source #
wrap_GLAreaCreateContextCallback :: GLAreaCreateContextCallback -> Ptr () -> Ptr () -> IO (Ptr GLContext) Source #
render
afterGLAreaRender :: (GObject a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId Source #
onGLAreaRender :: (GObject a, MonadIO m) => a -> GLAreaRenderCallback -> m SignalHandlerId Source #
wrap_GLAreaRenderCallback :: GLAreaRenderCallback -> Ptr () -> Ptr GLContext -> Ptr () -> IO CInt Source #
resize
afterGLAreaResize :: (GObject a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId Source #
onGLAreaResize :: (GObject a, MonadIO m) => a -> GLAreaResizeCallback -> m SignalHandlerId Source #
wrap_GLAreaResizeCallback :: GLAreaResizeCallback -> Ptr () -> Int32 -> Int32 -> Ptr () -> IO () Source #