<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
              "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
<refentry id="glXSelectEvent">
    <refmeta>
        <refmetainfo>
            <copyright>
                <year>1991-2006</year>
                <holder>Silicon Graphics, Inc.</holder>
            </copyright>
        </refmetainfo>
        <refentrytitle>glXSelectEvent</refentrytitle>
        <manvolnum>3G</manvolnum>
    </refmeta>
    <refnamediv>
        <refname>glXSelectEvent</refname>
        <refpurpose>select GLX events for a window or a GLX pixel buffer</refpurpose>
    </refnamediv>
    <refsynopsisdiv><title>C Specification</title>
        <funcsynopsis>
            <funcprototype>
                <funcdef>void <function>glXSelectEvent</function></funcdef>
                <paramdef>Display * <parameter>dpy</parameter></paramdef>
                <paramdef>GLXDrawable <parameter>draw</parameter></paramdef>
                <paramdef>unsigned long <parameter>event_mask</parameter></paramdef>
            </funcprototype>
        </funcsynopsis>
    </refsynopsisdiv>
    <refsect1 id="parameters"><title>Parameters</title>
        <variablelist>
        <varlistentry>
            <term><parameter>dpy</parameter></term>
            <listitem>
                <para>
                    Specifies the connection to the X server. 
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>draw</parameter></term>
            <listitem>
                <para>
                    Specifies a GLX drawable. Must be a GLX pixel buffer or a window.
                </para>
            </listitem>
        </varlistentry>
        <varlistentry>
            <term><parameter>event_mask</parameter></term>
            <listitem>
                <para>
                    Specifies the events to be returned for <parameter>draw</parameter>.
                </para>
            </listitem>
        </varlistentry>
        </variablelist>
    </refsect1>
    <refsect1 id="description"><title>Description</title>
        <para>
            <function>glXSelectEvent</function> sets the GLX event mask for a GLX pixel buffer or a window. 
            Calling <function>glXSelectEvent</function> overrides any previous event mask that was
            set by the client for <parameter>draw</parameter>. Note that it does not affect the
            event masks that other clients may have specified for <parameter>draw</parameter> since
            each client rendering to <parameter>draw</parameter> has a separate event mask for it.
        </para>
        <para>
            Currently, only one GLX event, <constant>GLX_PBUFFER_CLOBBER_MASK</constant>, 
            can be selected. The following data is returned to the client when a
            <constant>GLX_PBUFFER_CLOBBER_MASK</constant> event occurs:
        </para>
        <para>
            typedef struct {
        </para>
        <informaltable frame="topbot">
            <tgroup cols="2" align="left">
                <colspec/>
                <colspec/>
                <tbody>
                    <row>
                        <entry align="left">
                            int <emphasis>event_type</emphasis>;
                        </entry>
                        <entry align="left">
                        /* GLX_DAMAGED or GLX_SAVED */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            int <emphasis>draw_type</emphasis>;
                        </entry>
                        <entry align="left">
                        /* GLX_WINDOW or GLX_PBUFFER */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            unsigned long <emphasis>serial</emphasis>;
                        </entry>
                        <entry align="left">
                        /* # of last request processed by server */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            Bool <emphasis>send_event</emphasis>;
                        </entry>
                        <entry align="left">
                        /* true if this came for SendEvent request */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            Display <emphasis>*display</emphasis>;
                        </entry>
                        <entry align="left">
                        /* display the event was read from */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            GLXDrawable <emphasis>drawable</emphasis>;
                        </entry>
                        <entry align="left">
                        /* i.d. of Drawable */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            unsigned int <emphasis>buffer_mask</emphasis>;
                        </entry>
                        <entry align="left">
                        /* mask indicating affected buffers */
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            int <emphasis>x, y</emphasis>;
                        </entry>
                        <entry align="left">
                         
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            int <emphasis>width, height</emphasis>;
                        </entry>
                        <entry align="left">
                         
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                            int <emphasis>count</emphasis>;
                        </entry>
                        <entry align="left">
                        /* if nonzero, at least this many more */
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
        <para>
            } GLXPbufferClobberEvent;
            The valid bit masks used in <emphasis>buffer_mask</emphasis> are:
        </para>
        <para>
        </para>
        <informaltable frame="topbot">
            <tgroup cols="2" align="left">
                <colspec/>
                <colspec/>
                <thead>
                    <row>
                        <entry rowsep="1" align="left"><emphasis role="bold">
                        Bitmask
                        </emphasis></entry>
                        <entry rowsep="1" align="left"><emphasis role="bold">
                        Corresponding Buffer
                        </emphasis></entry>
                    </row>
                </thead>
                <tbody>
                    <row>
                        <entry align="left">
                        <constant>GLX_FRONT_LEFT_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Front left color buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_FRONT_RIGHT_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Front right color buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_BACK_LEFT_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Back left color buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_BACK_RIGHT_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Back right color buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_AUX_BUFFERS_BIT</constant>
                        </entry>
                        <entry align="left">
                        Auxiliary buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_DEPTH_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Depth buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_STENCIL_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Stencil buffer
                        </entry>
                    </row>
                    <row>
                        <entry align="left">
                        <constant>GLX_ACCUM_BUFFER_BIT</constant>
                        </entry>
                        <entry align="left">
                        Accumulation buffer
                        </entry>
                    </row>
                </tbody>
            </tgroup>
        </informaltable>
        <para>
            A single X server operation can cause several buffer clobber events to be
            sent. (e.g., a single GLX pixel buffer may be damaged and cause multiple 
            buffer clobber events to be generated). Each event specifies one 
            region of the GLX drawable that was affected by the X Server operation. 
            The <emphasis>buffer_mask</emphasis> field indicates which color buffers and 
            ancillary buffers were affected. All the buffer clobber events 
            generated by a single X server action are guaranteed to be
            contiguous in the event queue. The conditions under which this event is
            generated and the <emphasis>event_type</emphasis> varies, depending on the type of the
            GLX drawable.
        </para>
        <para>
            When the <constant>GLX_AUX_BUFFERS_BIT</constant> is set in <emphasis>buffer_mask</emphasis>, then
            <emphasis>aux_buffer</emphasis> is set to indicate which buffer was affected. If more
            than one aux buffer was affected, then additional events are
            generated as part of the same contiguous event group. Each
            additional event will have only the <constant>GLX_AUX_BUFFERS_BIT</constant> set in 
            <emphasis>buffer_mask</emphasis>, and the <emphasis>aux_buffer</emphasis> field will be set
            appropriately. For nonstereo drawables,
            <constant>GLX_FRONT_LEFT_BUFFER_BIT</constant> and <constant>GLX_BACK_LEFT_BUFFER_BIT</constant> are 
            used to specify the front and back color buffers.
        </para>
        <para>
            For preserved GLX pixel buffers, a buffer clobber event with 
            type <constant>GLX_SAVED</constant> is generated whenever the contents of the 
            GLX pixel buffer is moved out of offscreen memory. The event(s) describes which
            portions of the GLX pixel buffer were affected. Clients who receive many
            buffer clobber events, referring to different save actions,
            should consider freeing the GLX pixel buffer resource in order to prevent
            the system from thrashing due to insufficient resources.
        </para>
        <para>
            For an unpreserved GLXPbuffer, a buffer clobber event, with type
            <constant>GLX_DAMAGED</constant>, is generated whenever a portion of the GLX pixel buffer
            becomes invalid. The client may wish to regenerate the invalid portions
            of the GLX pixel buffer.
        </para>
        <para>
            For Windows, buffer clobber events, with type <constant>GLX_SAVED</constant>, occur
            whenever an ancillary buffer, associated with the window, gets clobbered
            or moved out of off-screen memory. The event contains information
            indicating which color buffers and ancillary buffers\(emand which portions
            of those buffers\(emwere affected.
        </para>
    </refsect1>
    <refsect1 id="notes"><title>Notes</title>
        <para>
            <function>glXSelectEvent</function> is available only if the GLX version is 1.3 or greater.
        </para>
        <para>
            If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
            If the GLX version is 1.2, then the GL version must be 1.1.
            If the GLX version is 1.3, then the GL version must be 1.2.
        </para>
    </refsect1>
    <refsect1 id="errors"><title>Errors</title>
        <para>
            <constant>GLXBadDrawable</constant> is generated if <parameter>draw</parameter> is not a valid window
            or a valid GLX pixel buffer. 
        </para>
    </refsect1>
    <refsect1 id="associatedgets"><title>Associated Gets</title>
        <para>
            <citerefentry><refentrytitle>glXGetSelectedEvent</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="seealso"><title>See Also</title>
        <para>
            <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>
        </para>
    </refsect1>
    <refsect1 id="Copyright"><title>Copyright</title>
        <para>
            Copyright <trademark class="copyright"></trademark> 1991-2006
            Silicon Graphics, Inc. This document is licensed under the SGI
            Free Software B License. For details, see
            <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
        </para>
    </refsect1>
</refentry>
