Blame |
Last modification |
View Log
| RSS feed
<?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>