330 lines
14 KiB
XML
330 lines
14 KiB
XML
|
<?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>
|