<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkGLArea">
<refmeta>
<refentrytitle role="top_of_page" id="GtkGLArea.top_of_page">GtkGLArea</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkGLArea</refname>
<refpurpose>A widget for custom drawing with OpenGL</refpurpose>
</refnamediv>

<refsect1 id="GtkGLArea.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-gl-area-new">gtk_gl_area_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GdkGLContext"><returnvalue>GdkGLContext</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-context">gtk_gl_area_get_context</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-make-current">gtk_gl_area_make_current</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-queue-render">gtk_gl_area_queue_render</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-attach-buffers">gtk_gl_area_attach_buffers</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-error">gtk_gl_area_set_error</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GError"><returnvalue>GError</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-error">gtk_gl_area_get_error</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-has-depth-buffer">gtk_gl_area_set_has_depth_buffer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-has-depth-buffer">gtk_gl_area_get_has_depth_buffer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-has-stencil-buffer">gtk_gl_area_set_has_stencil_buffer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-has-stencil-buffer">gtk_gl_area_get_has_stencil_buffer</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-auto-render">gtk_gl_area_set_auto_render</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-auto-render">gtk_gl_area_get_auto_render</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-required-version">gtk_gl_area_get_required_version</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-required-version">gtk_gl_area_set_required_version</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-set-use-es">gtk_gl_area_set_use_es</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-gl-area-get-use-es">gtk_gl_area_get_use_es</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkGLArea.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkGLArea--auto-render">auto-render</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="GdkGLContext"><type>GdkGLContext</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkGLArea--context">context</link></entry><entry role="property_flags">Read</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkGLArea--has-depth-buffer">has-depth-buffer</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkGLArea--has-stencil-buffer">has-stencil-buffer</link></entry><entry role="property_flags">Read / Write</entry></row>
<row><entry role="property_type"><link linkend="gboolean"><type>gboolean</type></link></entry><entry role="property_name"><link linkend="GtkGLArea--use-es">use-es</link></entry><entry role="property_flags">Read / Write</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkGLArea.signals" role="signal_proto">
<title role="signal_proto.title">Signals</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="signal_proto_type" colwidth="150px"/>
<colspec colname="signal_proto_name" colwidth="300px"/>
<colspec colname="signal_proto_flags" colwidth="200px"/>
<tbody>
<row><entry role="signal_type"><link linkend="GdkGLContext"><returnvalue>GdkGLContext</returnvalue></link>*</entry><entry role="signal_name"><link linkend="GtkGLArea-create-context">create-context</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>
<row><entry role="signal_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkGLArea-render">render</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>
<row><entry role="signal_type"><link linkend="void"><returnvalue>void</returnvalue></link></entry><entry role="signal_name"><link linkend="GtkGLArea-resize">resize</link></entry><entry role="signal_flags"><link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkGLArea.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkGLArea-struct">GtkGLArea</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkGLAreaClass">GtkGLAreaClass</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkGLArea.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GInitiallyUnowned">GInitiallyUnowned</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkWidget">GtkWidget</link>
            <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkGLArea
</screen>
</refsect1>
<refsect1 id="GtkGLArea.implemented-interfaces" role="impl_interfaces">
<title role="impl_interfaces.title">Implemented Interfaces</title>
<para>
GtkGLArea implements
 <link linkend="AtkImplementorIface">AtkImplementorIface</link>,  <link linkend="GtkBuildable">GtkBuildable</link> and  <link linkend="GtkConstraintTarget">GtkConstraintTarget</link>.</para>

</refsect1>

<refsect1 id="GtkGLArea.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkGLArea.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkGLArea"><type>GtkGLArea</type></link> is a widget that allows drawing with OpenGL.</para>
<para><link linkend="GtkGLArea"><type>GtkGLArea</type></link> sets up its own <link linkend="GdkGLContext"><type>GdkGLContext</type></link> 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.</para>
<para>In order to draw, you have to connect to the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal,
or subclass <link linkend="GtkGLArea"><type>GtkGLArea</type></link> and override the <parameter>GtkGLAreaClass.render()</parameter>
 virtual
function.</para>
<para>The <link linkend="GtkGLArea"><type>GtkGLArea</type></link> widget ensures that the <link linkend="GdkGLContext"><type>GdkGLContext</type></link> is associated with
the widget's drawing area, and it is kept updated when the size and
position of the drawing area changes.</para>
<refsect3><title>Drawing with GtkGLArea</title><para>The simplest way to draw using OpenGL commands in a <link linkend="GtkGLArea"><type>GtkGLArea</type></link> is to
create a widget instance and connect to the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal:</para>
<informalexample><programlisting role="example"><![CDATA[

]]></programlisting></informalexample>
<para></para>
<para>The <literal><link linkend="render"><function>render()</function></link></literal> function will be called when the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> is ready
for you to draw its content:</para>
<informalexample><programlisting role="example"><![CDATA[
  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);
  }
]]></programlisting></informalexample>
<para></para>
<para>If you need to initialize OpenGL state, e.g. buffer objects or
shaders, you should use the <link linkend="GtkWidget-realize"><type>“realize”</type></link> signal; you
can use the <link linkend="GtkWidget-unrealize"><type>“unrealize”</type></link> signal to clean up. Since the
<link linkend="GdkGLContext"><type>GdkGLContext</type></link> creation and initialization may fail, you will
need to check for errors, using <link linkend="gtk-gl-area-get-error"><function>gtk_gl_area_get_error()</function></link>. An example
of how to safely initialize the GL state is:</para>
<informalexample><programlisting role="example"><![CDATA[
  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;
      }
  }
]]></programlisting></informalexample>
<para></para>
<para>If you need to change the options for creating the <link linkend="GdkGLContext"><type>GdkGLContext</type></link>
you should use the <link linkend="GtkGLArea-create-context"><type>“create-context”</type></link> signal.</para>
</refsect3>

</refsect1>
<refsect1 id="GtkGLArea.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-gl-area-new" role="function">
<title>gtk_gl_area_new&#160;()</title>
<indexterm zone="gtk-gl-area-new"><primary>gtk_gl_area_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkWidget"><returnvalue>GtkWidget</returnvalue></link>&#160;*
gtk_gl_area_new (<parameter><type>void</type></parameter>);</programlisting>
<para>Creates a new <link linkend="GtkGLArea"><type>GtkGLArea</type></link> widget.</para>
<refsect3 id="gtk-gl-area-new.returns" role="returns">
<title>Returns</title>
<para> a new <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-context" role="function">
<title>gtk_gl_area_get_context&#160;()</title>
<indexterm zone="gtk-gl-area-get-context"><primary>gtk_gl_area_get_context</primary></indexterm>
<programlisting language="C"><link linkend="GdkGLContext"><returnvalue>GdkGLContext</returnvalue></link>&#160;*
gtk_gl_area_get_context (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Retrieves the <link linkend="GdkGLContext"><type>GdkGLContext</type></link> used by <parameter>area</parameter>
.</para>
<refsect3 id="gtk-gl-area-get-context.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-context.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GdkGLContext"><type>GdkGLContext</type></link>. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-make-current" role="function">
<title>gtk_gl_area_make_current&#160;()</title>
<indexterm zone="gtk-gl-area-make-current"><primary>gtk_gl_area_make_current</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_make_current (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Ensures that the <link linkend="GdkGLContext"><type>GdkGLContext</type></link> used by <parameter>area</parameter>
 is associated with
the <link linkend="GtkGLArea"><type>GtkGLArea</type></link>.</para>
<para>This function is automatically called before emitting the
<link linkend="GtkGLArea-render"><type>“render”</type></link> signal, and doesn't normally need to be called
by application code.</para>
<refsect3 id="gtk-gl-area-make-current.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-queue-render" role="function">
<title>gtk_gl_area_queue_render&#160;()</title>
<indexterm zone="gtk-gl-area-queue-render"><primary>gtk_gl_area_queue_render</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_queue_render (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Marks the currently rendered data (if any) as invalid, and queues
a redraw of the widget, ensuring that the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal
is emitted during the draw.</para>
<para>This is only needed when the <link linkend="gtk-gl-area-set-auto-render"><function>gtk_gl_area_set_auto_render()</function></link> has
been called with a <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> value. The default behaviour is to
emit <link linkend="GtkGLArea-render"><type>“render”</type></link> on each draw.</para>
<refsect3 id="gtk-gl-area-queue-render.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-attach-buffers" role="function">
<title>gtk_gl_area_attach_buffers&#160;()</title>
<indexterm zone="gtk-gl-area-attach-buffers"><primary>gtk_gl_area_attach_buffers</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_attach_buffers (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Ensures that the <parameter>area</parameter>
 framebuffer object is made the current draw
and read target, and that all the required buffers for the <parameter>area</parameter>

are created and bound to the frambuffer.</para>
<para>This function is automatically called before emitting the
<link linkend="GtkGLArea-render"><type>“render”</type></link> signal, and doesn't normally need to be called
by application code.</para>
<refsect3 id="gtk-gl-area-attach-buffers.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-error" role="function">
<title>gtk_gl_area_set_error&#160;()</title>
<indexterm zone="gtk-gl-area-set-error"><primary>gtk_gl_area_set_error</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_error (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                       <parameter>const <link linkend="GError"><type>GError</type></link> *error</parameter>);</programlisting>
<para>Sets an error on the area which will be shown instead of the
GL rendering. This is useful in the <link linkend="GtkGLArea-create-context"><type>“create-context”</type></link>
signal if GL context creation fails.</para>
<refsect3 id="gtk-gl-area-set-error.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>a new <link linkend="GError"><type>GError</type></link>, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to unset the error. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-error" role="function">
<title>gtk_gl_area_get_error&#160;()</title>
<indexterm zone="gtk-gl-area-get-error"><primary>gtk_gl_area_get_error</primary></indexterm>
<programlisting language="C"><link linkend="GError"><returnvalue>GError</returnvalue></link>&#160;*
gtk_gl_area_get_error (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Gets the current error set on the <parameter>area</parameter>
.</para>
<refsect3 id="gtk-gl-area-get-error.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-error.returns" role="returns">
<title>Returns</title>
<para>the <link linkend="GError"><type>GError</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-has-depth-buffer" role="function">
<title>gtk_gl_area_set_has_depth_buffer&#160;()</title>
<indexterm zone="gtk-gl-area-set-has-depth-buffer"><primary>gtk_gl_area_set_has_depth_buffer</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_has_depth_buffer (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                                  <parameter><link linkend="gboolean"><type>gboolean</type></link> has_depth_buffer</parameter>);</programlisting>
<para>If <parameter>has_depth_buffer</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the widget will allocate and
enable a depth buffer for the target framebuffer. Otherwise
there will be none.</para>
<refsect3 id="gtk-gl-area-set-has-depth-buffer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>has_depth_buffer</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to add a depth buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-has-depth-buffer" role="function">
<title>gtk_gl_area_get_has_depth_buffer&#160;()</title>
<indexterm zone="gtk-gl-area-get-has-depth-buffer"><primary>gtk_gl_area_get_has_depth_buffer</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_gl_area_get_has_depth_buffer (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Returns whether the area has a depth buffer.</para>
<refsect3 id="gtk-gl-area-get-has-depth-buffer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-has-depth-buffer.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <parameter>area</parameter>
has a depth buffer, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-has-stencil-buffer" role="function">
<title>gtk_gl_area_set_has_stencil_buffer&#160;()</title>
<indexterm zone="gtk-gl-area-set-has-stencil-buffer"><primary>gtk_gl_area_set_has_stencil_buffer</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_has_stencil_buffer (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                                    <parameter><link linkend="gboolean"><type>gboolean</type></link> has_stencil_buffer</parameter>);</programlisting>
<para>If <parameter>has_stencil_buffer</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the widget will allocate and
enable a stencil buffer for the target framebuffer. Otherwise
there will be none.</para>
<refsect3 id="gtk-gl-area-set-has-stencil-buffer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>has_stencil_buffer</para></entry>
<entry role="parameter_description"><para><link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to add a stencil buffer</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-has-stencil-buffer" role="function">
<title>gtk_gl_area_get_has_stencil_buffer&#160;()</title>
<indexterm zone="gtk-gl-area-get-has-stencil-buffer"><primary>gtk_gl_area_get_has_stencil_buffer</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_gl_area_get_has_stencil_buffer (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Returns whether the area has a stencil buffer.</para>
<refsect3 id="gtk-gl-area-get-has-stencil-buffer.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-has-stencil-buffer.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <parameter>area</parameter>
has a stencil buffer, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-auto-render" role="function">
<title>gtk_gl_area_set_auto_render&#160;()</title>
<indexterm zone="gtk-gl-area-set-auto-render"><primary>gtk_gl_area_set_auto_render</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_auto_render (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                             <parameter><link linkend="gboolean"><type>gboolean</type></link> auto_render</parameter>);</programlisting>
<para>If <parameter>auto_render</parameter>
 is <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal will be
emitted every time the widget draws. This is the default and is
useful if drawing the widget is faster.</para>
<para>If <parameter>auto_render</parameter>
 is <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> 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
<link linkend="gtk-gl-area-queue-render"><function>gtk_gl_area_queue_render()</function></link> must be called. This mode is useful when
the scene changes seldomly, but takes a long time to redraw.</para>
<refsect3 id="gtk-gl-area-set-auto-render.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>auto_render</para></entry>
<entry role="parameter_description"><para>a boolean</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-auto-render" role="function">
<title>gtk_gl_area_get_auto_render&#160;()</title>
<indexterm zone="gtk-gl-area-get-auto-render"><primary>gtk_gl_area_get_auto_render</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_gl_area_get_auto_render (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Returns whether the area is in auto render mode or not.</para>
<refsect3 id="gtk-gl-area-get-auto-render.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-auto-render.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <parameter>area</parameter>
is auto rendering, <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-required-version" role="function">
<title>gtk_gl_area_get_required_version&#160;()</title>
<indexterm zone="gtk-gl-area-get-required-version"><primary>gtk_gl_area_get_required_version</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_get_required_version (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                                  <parameter><link linkend="gint"><type>gint</type></link> *major</parameter>,
                                  <parameter><link linkend="gint"><type>gint</type></link> *minor</parameter>);</programlisting>
<para>Retrieves the required version of OpenGL set
using <link linkend="gtk-gl-area-set-required-version"><function>gtk_gl_area_set_required_version()</function></link>.</para>
<refsect3 id="gtk-gl-area-get-required-version.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>major</para></entry>
<entry role="parameter_description"><para>return location for the required major version. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><para>minor</para></entry>
<entry role="parameter_description"><para>return location for the required minor version. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>out</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-required-version" role="function">
<title>gtk_gl_area_set_required_version&#160;()</title>
<indexterm zone="gtk-gl-area-set-required-version"><primary>gtk_gl_area_set_required_version</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_required_version (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                                  <parameter><link linkend="gint"><type>gint</type></link> major</parameter>,
                                  <parameter><link linkend="gint"><type>gint</type></link> minor</parameter>);</programlisting>
<para>Sets the required version of OpenGL to be used when creating the context
for the widget.</para>
<para>This function must be called before the area has been realized.</para>
<refsect3 id="gtk-gl-area-set-required-version.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>major</para></entry>
<entry role="parameter_description"><para>the major version</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>minor</para></entry>
<entry role="parameter_description"><para>the minor version</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-set-use-es" role="function">
<title>gtk_gl_area_set_use_es&#160;()</title>
<indexterm zone="gtk-gl-area-set-use-es"><primary>gtk_gl_area_set_use_es</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_gl_area_set_use_es (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>,
                        <parameter><link linkend="gboolean"><type>gboolean</type></link> use_es</parameter>);</programlisting>
<para>Sets whether the <parameter>area</parameter>
 should create an OpenGL or an OpenGL ES context.</para>
<para>You should check the capabilities of the <link linkend="GdkGLContext"><type>GdkGLContext</type></link> before drawing
with either API.</para>
<refsect3 id="gtk-gl-area-set-use-es.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>use_es</para></entry>
<entry role="parameter_description"><para>whether to use OpenGL or OpenGL ES</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-gl-area-get-use-es" role="function">
<title>gtk_gl_area_get_use_es&#160;()</title>
<indexterm zone="gtk-gl-area-get-use-es"><primary>gtk_gl_area_get_use_es</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gtk_gl_area_get_use_es (<parameter><link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area</parameter>);</programlisting>
<para>Retrieves the value set by <link linkend="gtk-gl-area-set-use-es"><function>gtk_gl_area_set_use_es()</function></link>.</para>
<refsect3 id="gtk-gl-area-get-use-es.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkGLArea"><type>GtkGLArea</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-gl-area-get-use-es.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> should create an OpenGL ES context
and <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> otherwise</para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkGLArea.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkGLArea-struct" role="struct">
<title>struct GtkGLArea</title>
<indexterm zone="GtkGLArea-struct"><primary>GtkGLArea</primary></indexterm>
<programlisting language="C">struct GtkGLArea;</programlisting>
<para>A <link linkend="GtkWidget"><type>GtkWidget</type></link> used for drawing with OpenGL.</para>
</refsect2>
<refsect2 id="GtkGLAreaClass" role="struct">
<title>struct GtkGLAreaClass</title>
<indexterm zone="GtkGLAreaClass"><primary>GtkGLAreaClass</primary></indexterm>
<programlisting language="C">struct GtkGLAreaClass {
  gboolean       (* render)         (GtkGLArea        *area,
                                     GdkGLContext     *context);
  void           (* resize)         (GtkGLArea        *area,
                                     int               width,
                                     int               height);
  GdkGLContext * (* create_context) (GtkGLArea        *area);
};
</programlisting>
<para>The <literal>GtkGLAreaClass</literal> structure contains only private data.</para>
<refsect3 id="GtkGLAreaClass.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkGLAreaClass.render">render</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>class closure for the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkGLAreaClass.resize">resize</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>class closeure for the <link linkend="GtkGLArea-resize"><type>“resize”</type></link> signal</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><structfield id="GtkGLAreaClass.create-context">create_context</structfield>&#160;()</para></entry>
<entry role="struct_member_description"><para>class closure for the <link linkend="GtkGLArea-create-context"><type>“create-context”</type></link> signal</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>
<refsect1 id="GtkGLArea.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkGLArea--auto-render" role="property"><title>The <literal>“auto-render”</literal> property</title>
<indexterm zone="GtkGLArea--auto-render"><primary>GtkGLArea:auto-render</primary></indexterm>
<programlisting>  “auto-render”              <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the <link linkend="GtkGLArea-render"><type>“render”</type></link> signal will be emitted every time
the widget draws. This is the default and is useful if drawing the widget
is faster.</para>
<para>If set to <link linkend="FALSE:CAPS"><literal>FALSE</literal></link> 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 <link linkend="gtk-gl-area-queue-render"><function>gtk_gl_area_queue_render()</function></link> must be called.
This mode is useful when the scene changes seldomly, but takes a long time
to redraw.</para>
<para>Owner: GtkGLArea</para>
<para>Flags: Read / Write</para>
<para>Default value: TRUE</para>
</refsect2>
<refsect2 id="GtkGLArea--context" role="property"><title>The <literal>“context”</literal> property</title>
<indexterm zone="GtkGLArea--context"><primary>GtkGLArea:context</primary></indexterm>
<programlisting>  “context”                  <link linkend="GdkGLContext"><type>GdkGLContext</type></link>&#160;*</programlisting>
<para>The <link linkend="GdkGLContext"><type>GdkGLContext</type></link> used by the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> widget.</para>
<para>The <link linkend="GtkGLArea"><type>GtkGLArea</type></link> widget is responsible for creating the <link linkend="GdkGLContext"><type>GdkGLContext</type></link>
instance. If you need to render with other kinds of buffers (stencil,
depth, etc), use render buffers.</para>
<para>Owner: GtkGLArea</para>
<para>Flags: Read</para>
</refsect2>
<refsect2 id="GtkGLArea--has-depth-buffer" role="property"><title>The <literal>“has-depth-buffer”</literal> property</title>
<indexterm zone="GtkGLArea--has-depth-buffer"><primary>GtkGLArea:has-depth-buffer</primary></indexterm>
<programlisting>  “has-depth-buffer”         <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the widget will allocate and enable a depth buffer for the
target framebuffer.</para>
<para>Owner: GtkGLArea</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkGLArea--has-stencil-buffer" role="property"><title>The <literal>“has-stencil-buffer”</literal> property</title>
<indexterm zone="GtkGLArea--has-stencil-buffer"><primary>GtkGLArea:has-stencil-buffer</primary></indexterm>
<programlisting>  “has-stencil-buffer”       <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the widget will allocate and enable a stencil buffer for the
target framebuffer.</para>
<para>Owner: GtkGLArea</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>
<refsect2 id="GtkGLArea--use-es" role="property"><title>The <literal>“use-es”</literal> property</title>
<indexterm zone="GtkGLArea--use-es"><primary>GtkGLArea:use-es</primary></indexterm>
<programlisting>  “use-es”                   <link linkend="gboolean"><type>gboolean</type></link></programlisting>
<para>If set to <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> the widget will try to create a <link linkend="GdkGLContext"><type>GdkGLContext</type></link> using
OpenGL ES instead of OpenGL.</para>
<para>See also: <link linkend="gdk-gl-context-set-use-es"><function>gdk_gl_context_set_use_es()</function></link></para>
<para>Owner: GtkGLArea</para>
<para>Flags: Read / Write</para>
<para>Default value: FALSE</para>
</refsect2>

</refsect1>
<refsect1 id="GtkGLArea.signal-details" role="signals">
<title role="signals.title">Signal Details</title>
<refsect2 id="GtkGLArea-create-context" role="signal"><title>The <literal>“create-context”</literal> signal</title>
<indexterm zone="GtkGLArea-create-context"><primary>GtkGLArea::create-context</primary></indexterm>
<programlisting language="C"><link linkend="GdkGLContext"><returnvalue>GdkGLContext</returnvalue></link>*
user_function (<link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area,
               <link linkend="gpointer"><type>gpointer</type></link>   user_data)</programlisting>
<para>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.</para>
<para>If context creation fails then the signal handler can use
<link linkend="gtk-gl-area-set-error"><function>gtk_gl_area_set_error()</function></link> to register a more detailed error
of how the construction failed.</para>
<refsect3 id="GtkGLArea-create-context.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> that emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>error</para></entry>
<entry role="parameter_description"><para>location to store error information on failure. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>allow-none</acronym>]</emphasis></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GtkGLArea-create-context.returns" role="returns">
<title>Returns</title>
<para>a newly created <link linkend="GdkGLContext"><type>GdkGLContext</type></link>;
the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> widget will take ownership of the returned value. </para>
<para><emphasis role="annotation">[<acronym>transfer full</acronym>]</emphasis></para>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2><refsect2 id="GtkGLArea-render" role="signal"><title>The <literal>“render”</literal> signal</title>
<indexterm zone="GtkGLArea-render"><primary>GtkGLArea::render</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
user_function (<link linkend="GtkGLArea"><type>GtkGLArea</type></link>    *area,
               <link linkend="GdkGLContext"><type>GdkGLContext</type></link> *context,
               <link linkend="gpointer"><type>gpointer</type></link>      user_data)</programlisting>
<para>The ::render signal is emitted every time the contents
of the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> should be redrawn.</para>
<para>The <parameter>context</parameter>
 is bound to the <parameter>area</parameter>
 prior to emitting this function,
and the buffers are painted to the window once the emission terminates.</para>
<refsect3 id="GtkGLArea-render.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> that emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>the <link linkend="GdkGLContext"><type>GdkGLContext</type></link> used by <parameter>area</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="GtkGLArea-render.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> to stop other handlers from being invoked for the event.
<link linkend="FALSE:CAPS"><literal>FALSE</literal></link> to propagate the event further.</para>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2><refsect2 id="GtkGLArea-resize" role="signal"><title>The <literal>“resize”</literal> signal</title>
<indexterm zone="GtkGLArea-resize"><primary>GtkGLArea::resize</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
user_function (<link linkend="GtkGLArea"><type>GtkGLArea</type></link> *area,
               <link linkend="gint"><type>gint</type></link>       width,
               <link linkend="gint"><type>gint</type></link>       height,
               <link linkend="gpointer"><type>gpointer</type></link>   user_data)</programlisting>
<para>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.</para>
<para>The GL context for the area is guaranteed to be current when this signal
is emitted.</para>
<para>The default handler sets up the GL viewport.</para>
<refsect3 id="GtkGLArea-resize.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>area</para></entry>
<entry role="parameter_description"><para>the <link linkend="GtkGLArea"><type>GtkGLArea</type></link> that emitted the signal</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>width</para></entry>
<entry role="parameter_description"><para>the width of the viewport</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>height</para></entry>
<entry role="parameter_description"><para>the height of the viewport</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><simpara>user_data</simpara></entry>
<entry role="parameter_description"><simpara>user data set when the signal handler was connected.</simpara></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><para>Flags: <link linkend="G-SIGNAL-RUN-LAST:CAPS">Run Last</link></para>
</refsect2>
</refsect1>

</refentry>
