forked from AuroraMiddleware/gtk
glarea: Convert docs
Change link syntax, add an example image, generally clean things up.
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
1072b56970
commit
8cf04b3345
207
gtk/gtkglarea.c
207
gtk/gtkglarea.c
@ -38,40 +38,37 @@
|
||||
* @Title: GtkGLArea
|
||||
* @Short_description: A widget for custom drawing with OpenGL
|
||||
*
|
||||
* #GtkGLArea is a widget that allows drawing with OpenGL.
|
||||
* `GtkGLArea` is a widget that allows drawing with OpenGL.
|
||||
*
|
||||
* #GtkGLArea sets up its own #GdkGLContext 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 #GtkGLArea::render signal,
|
||||
* or subclass #GtkGLArea and override the @GtkGLAreaClass.render() virtual
|
||||
* function.
|
||||
* `GtkGLArea` sets up its own [class@Gdk.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.
|
||||
*
|
||||
* The #GtkGLArea widget ensures that the #GdkGLContext is associated with
|
||||
* In order to draw, you have to connect to the [signal@Gtk.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 ##
|
||||
* ## Drawing with GtkGLArea
|
||||
*
|
||||
* The simplest way to draw using OpenGL commands in a #GtkGLArea is to
|
||||
* create a widget instance and connect to the #GtkGLArea::render signal:
|
||||
* The simplest way to draw using OpenGL commands in a `GtkGLArea` is to
|
||||
* create a widget instance and connect to the [signal@Gtk.GLArea::render] signal:
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
|
||||
* ]|
|
||||
*
|
||||
* The `render()` function will be called when the #GtkGLArea is ready
|
||||
* The `render()` function will be called when the `GtkGLArea` is ready
|
||||
* for you to draw its content:
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* ```c
|
||||
* 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
|
||||
* // 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
|
||||
@ -95,16 +92,17 @@
|
||||
* // 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 #GtkWidget::realize signal; you
|
||||
* can use the #GtkWidget::unrealize signal to clean up. Since the
|
||||
* #GdkGLContext creation and initialization may fail, you will
|
||||
* need to check for errors, using gtk_gl_area_get_error(). An example
|
||||
* of how to safely initialize the GL state is:
|
||||
* shaders, you should use the [signal@Gtk.Widget::realize] signal;
|
||||
* you can use the [signal@Gtk.Widget::unrealize] signal to clean up.
|
||||
* Since the `GdkGLContext` creation and initialization may fail, you
|
||||
* will need to check for errors, using [method@Gtk.GLArea.get_error].
|
||||
*
|
||||
* |[<!-- language="C" -->
|
||||
* An example of how to safely initialize the GL state is:
|
||||
*
|
||||
* ```c
|
||||
* static void
|
||||
* on_realize (GtkGLarea *area)
|
||||
* {
|
||||
@ -138,10 +136,10 @@
|
||||
* return;
|
||||
* }
|
||||
* }
|
||||
* ]|
|
||||
* ```
|
||||
*
|
||||
* If you need to change the options for creating the #GdkGLContext
|
||||
* you should use the #GtkGLArea::create-context signal.
|
||||
* If you need to change the options for creating the `GdkGLContext`
|
||||
* you should use the [signal@Gtk.GLArea::create-context] signal.
|
||||
*/
|
||||
|
||||
typedef struct {
|
||||
@ -516,15 +514,17 @@ gtk_gl_area_allocate_texture (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_attach_buffers:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* 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
|
||||
* #GtkGLArea::render signal, and doesn't normally need to be called
|
||||
* by application code.
|
||||
* [signal@Gtk.GLArea::render] signal, and doesn't normally need to be
|
||||
* called by application code.
|
||||
*/
|
||||
void
|
||||
gtk_gl_area_attach_buffers (GtkGLArea *area)
|
||||
@ -793,9 +793,9 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
/**
|
||||
* GtkGLArea:context:
|
||||
*
|
||||
* The #GdkGLContext used by the #GtkGLArea widget.
|
||||
* The `GdkGLContext` used by the `GtkGLArea` widget.
|
||||
*
|
||||
* The #GtkGLArea widget is responsible for creating the #GdkGLContext
|
||||
* 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.
|
||||
*/
|
||||
@ -810,13 +810,14 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
/**
|
||||
* GtkGLArea:auto-render:
|
||||
*
|
||||
* If set to %TRUE the #GtkGLArea::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 %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 gtk_gl_area_queue_render() must be called.
|
||||
* In order to force a rendering [method@Gtk.GLArea.queue_render] must be called.
|
||||
* This mode is useful when the scene changes seldom, but takes a long time
|
||||
* to redraw.
|
||||
*/
|
||||
@ -862,10 +863,10 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
/**
|
||||
* GtkGLArea:use-es:
|
||||
*
|
||||
* If set to %TRUE the widget will try to create a #GdkGLContext using
|
||||
* If set to %TRUE the widget will try to create a `GdkGLContext` using
|
||||
* OpenGL ES instead of OpenGL.
|
||||
*
|
||||
* See also: gdk_gl_context_set_use_es()
|
||||
* See also: [method@Gdk.GLContext.set_use_es]
|
||||
*/
|
||||
obj_props[PROP_USE_ES] =
|
||||
g_param_spec_boolean ("use-es",
|
||||
@ -884,11 +885,10 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
|
||||
/**
|
||||
* GtkGLArea::render:
|
||||
* @area: the #GtkGLArea that emitted the signal
|
||||
* @context: the #GdkGLContext used by @area
|
||||
* @area: the `GtkGLArea` that emitted the signal
|
||||
* @context: the `GdkGLContext` used by @area
|
||||
*
|
||||
* The ::render signal is emitted every time the contents
|
||||
* of the #GtkGLArea should be redrawn.
|
||||
* 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.
|
||||
@ -911,14 +911,16 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
|
||||
/**
|
||||
* GtkGLArea::resize:
|
||||
* @area: the #GtkGLArea that emitted the signal
|
||||
* @area: the `GtkGLArea` that emitted the signal
|
||||
* @width: the width of the viewport
|
||||
* @height: the height of the viewport
|
||||
*
|
||||
* The ::resize signal is 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.
|
||||
* 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.
|
||||
@ -939,21 +941,21 @@ gtk_gl_area_class_init (GtkGLAreaClass *klass)
|
||||
|
||||
/**
|
||||
* GtkGLArea::create-context:
|
||||
* @area: the #GtkGLArea that emitted the signal
|
||||
* @area: the `GtkGLArea` that emitted the signal
|
||||
* @error: (allow-none): location to store error information on failure
|
||||
*
|
||||
* The ::create-context signal is emitted when the widget is being
|
||||
* realized, and 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.
|
||||
* 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
|
||||
* gtk_gl_area_set_error() to register a more detailed error
|
||||
* [method@Gtk.GLArea.set_error] to register a more detailed error
|
||||
* of how the construction failed.
|
||||
*
|
||||
* Returns: (transfer full): a newly created #GdkGLContext;
|
||||
* the #GtkGLArea widget will take ownership of the returned value.
|
||||
* Returns: (transfer full): a newly created `GdkGLContext`;
|
||||
* the `GtkGLArea` widget will take ownership of the returned value.
|
||||
*/
|
||||
area_signals[CREATE_CONTEXT] =
|
||||
g_signal_new (I_("create-context"),
|
||||
@ -981,9 +983,9 @@ gtk_gl_area_init (GtkGLArea *area)
|
||||
/**
|
||||
* gtk_gl_area_new:
|
||||
*
|
||||
* Creates a new #GtkGLArea widget.
|
||||
* Creates a new `GtkGLArea` widget.
|
||||
*
|
||||
* Returns: a new #GtkGLArea
|
||||
* Returns: a new `GtkGLArea`
|
||||
*/
|
||||
GtkWidget *
|
||||
gtk_gl_area_new (void)
|
||||
@ -993,11 +995,13 @@ gtk_gl_area_new (void)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_error:
|
||||
* @area: a #GtkGLArea
|
||||
* @error: (allow-none): a new #GError, or %NULL to unset the error
|
||||
* @area: a `GtkGLArea`
|
||||
* @error: (allow-none): a new `GError`, or %NULL to unset the error
|
||||
*
|
||||
* Sets an error on the area which will be shown instead of the
|
||||
* GL rendering. This is useful in the #GtkGLArea::create-context
|
||||
* GL rendering.
|
||||
*
|
||||
* This is useful in the [signal@Gtk.GLArea::create-context]
|
||||
* signal if GL context creation fails.
|
||||
*/
|
||||
void
|
||||
@ -1015,7 +1019,7 @@ gtk_gl_area_set_error (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_error:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Gets the current error set on the @area.
|
||||
*
|
||||
@ -1033,7 +1037,7 @@ gtk_gl_area_get_error (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_use_es:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @use_es: whether to use OpenGL or OpenGL ES
|
||||
*
|
||||
* Sets whether the @area should create an OpenGL or an OpenGL ES context.
|
||||
@ -1062,11 +1066,13 @@ gtk_gl_area_set_use_es (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_use_es:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Retrieves the value set by gtk_gl_area_set_use_es().
|
||||
* Returns whether the `GtkGLArea` should use OpenGL ES.
|
||||
*
|
||||
* Returns: %TRUE if the #GtkGLArea should create an OpenGL ES context
|
||||
* See [method@Gtk.GLArea.set_use_es].
|
||||
*
|
||||
* Returns: %TRUE if the `GtkGLArea` should create an OpenGL ES context
|
||||
* and %FALSE otherwise
|
||||
*/
|
||||
gboolean
|
||||
@ -1081,12 +1087,12 @@ gtk_gl_area_get_use_es (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_required_version:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @major: the major version
|
||||
* @minor: the minor version
|
||||
*
|
||||
* Sets the required version of OpenGL to be used when creating the context
|
||||
* for the widget.
|
||||
* 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.
|
||||
*/
|
||||
@ -1105,12 +1111,13 @@ gtk_gl_area_set_required_version (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_required_version:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @major: (out): return location for the required major version
|
||||
* @minor: (out): return location for the required minor version
|
||||
*
|
||||
* Retrieves the required version of OpenGL set
|
||||
* using gtk_gl_area_set_required_version().
|
||||
* Retrieves the required version of OpenGL.
|
||||
*
|
||||
* See [method@Gtk.GLArea.set_required_version].
|
||||
*/
|
||||
void
|
||||
gtk_gl_area_get_required_version (GtkGLArea *area,
|
||||
@ -1129,7 +1136,7 @@ gtk_gl_area_get_required_version (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_has_depth_buffer:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Returns whether the area has a depth buffer.
|
||||
*
|
||||
@ -1147,9 +1154,11 @@ gtk_gl_area_get_has_depth_buffer (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_has_depth_buffer:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @has_depth_buffer: %TRUE to add a depth buffer
|
||||
*
|
||||
* 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.
|
||||
@ -1176,7 +1185,7 @@ gtk_gl_area_set_has_depth_buffer (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_has_stencil_buffer:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Returns whether the area has a stencil buffer.
|
||||
*
|
||||
@ -1194,9 +1203,11 @@ gtk_gl_area_get_has_stencil_buffer (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_has_stencil_buffer:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @has_stencil_buffer: %TRUE to add a stencil buffer
|
||||
*
|
||||
* 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.
|
||||
@ -1223,15 +1234,17 @@ gtk_gl_area_set_has_stencil_buffer (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_queue_render:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Marks the currently rendered data (if any) as invalid, and queues
|
||||
* a redraw of the widget, ensuring that the #GtkGLArea::render signal
|
||||
* a redraw of the widget.
|
||||
*
|
||||
* This ensures that the [signal@Gtk.GLArea::render] signal
|
||||
* is emitted during the draw.
|
||||
*
|
||||
* This is only needed when the gtk_gl_area_set_auto_render() has
|
||||
* This is only needed when [method@Gtk.GLArea.set_auto_render] has
|
||||
* been called with a %FALSE value. The default behaviour is to
|
||||
* emit #GtkGLArea::render on each draw.
|
||||
* emit [signal@Gtk.GLArea::render] on each draw.
|
||||
*/
|
||||
void
|
||||
gtk_gl_area_queue_render (GtkGLArea *area)
|
||||
@ -1248,7 +1261,7 @@ gtk_gl_area_queue_render (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_auto_render:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Returns whether the area is in auto render mode or not.
|
||||
*
|
||||
@ -1266,18 +1279,20 @@ gtk_gl_area_get_auto_render (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_set_auto_render:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
* @auto_render: a boolean
|
||||
*
|
||||
* If @auto_render is %TRUE the #GtkGLArea::render signal will be
|
||||
* emitted every time the widget draws. This is the default and is
|
||||
* Sets whether the `GtkGLArea` is in auto render mode.
|
||||
*
|
||||
* If @auto_render is %TRUE the [signal@Gtk.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 @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
|
||||
* gtk_gl_area_queue_render() must be called. This mode is useful when
|
||||
* the scene changes seldom, but takes a long time to redraw.
|
||||
* [method@Gtk.GLArea.queue_render] must be called. This mode is
|
||||
* useful when the scene changes seldom, but takes a long time to redraw.
|
||||
*/
|
||||
void
|
||||
gtk_gl_area_set_auto_render (GtkGLArea *area,
|
||||
@ -1302,11 +1317,11 @@ gtk_gl_area_set_auto_render (GtkGLArea *area,
|
||||
|
||||
/**
|
||||
* gtk_gl_area_get_context:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Retrieves the #GdkGLContext used by @area.
|
||||
* Retrieves the `GdkGLContext` used by @area.
|
||||
*
|
||||
* Returns: (transfer none): the #GdkGLContext
|
||||
* Returns: (transfer none): the `GdkGLContext`
|
||||
*/
|
||||
GdkGLContext *
|
||||
gtk_gl_area_get_context (GtkGLArea *area)
|
||||
@ -1320,14 +1335,14 @@ gtk_gl_area_get_context (GtkGLArea *area)
|
||||
|
||||
/**
|
||||
* gtk_gl_area_make_current:
|
||||
* @area: a #GtkGLArea
|
||||
* @area: a `GtkGLArea`
|
||||
*
|
||||
* Ensures that the #GdkGLContext used by @area is associated with
|
||||
* the #GtkGLArea.
|
||||
* Ensures that the `GdkGLContext` used by @area is associated with
|
||||
* the `GtkGLArea`.
|
||||
*
|
||||
* This function is automatically called before emitting the
|
||||
* #GtkGLArea::render signal, and doesn't normally need to be called
|
||||
* by application code.
|
||||
* [signal@Gtk.GLArea::render] signal, and doesn't normally need
|
||||
* to be called by application code.
|
||||
*/
|
||||
void
|
||||
gtk_gl_area_make_current (GtkGLArea *area)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user