upstream-man-pages/man2/glXSelectEvent.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glXSelectEvent">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXSelectEvent</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXSelectEvent</refname>
  17         <refpurpose>select GLX events for a window or a GLX pixel buffer</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glXSelectEvent</function></funcdef>
  23                 <paramdef>Display * <parameter>dpy</parameter></paramdef>
  24                 <paramdef>GLXDrawable <parameter>draw</parameter></paramdef>
  25                 <paramdef>unsigned long <parameter>event_mask</parameter></paramdef>
  26             </funcprototype>
  27         </funcsynopsis>
  28     </refsynopsisdiv>
  29     <refsect1 id="parameters"><title>Parameters</title>
  30         <variablelist>
  31         <varlistentry>
  32             <term><parameter>dpy</parameter></term>
  33             <listitem>
  34                 <para>
  35                     Specifies the connection to the X server.
  36                 </para>
  37             </listitem>
  38         </varlistentry>
  39         <varlistentry>
  40             <term><parameter>draw</parameter></term>
  41             <listitem>
  42                 <para>
  43                     Specifies a GLX drawable. Must be a GLX pixel buffer or a window.
  44                 </para>
  45             </listitem>
  46         </varlistentry>
  47         <varlistentry>
  48             <term><parameter>event_mask</parameter></term>
  49             <listitem>
  50                 <para>
  51                     Specifies the events to be returned for <parameter>draw</parameter>.
  52                 </para>
  53             </listitem>
  54         </varlistentry>
  55         </variablelist>
  56     </refsect1>
  57     <refsect1 id="description"><title>Description</title>
  58         <para>
  59             <function>glXSelectEvent</function> sets the GLX event mask for a GLX pixel buffer or a window.
  60             Calling <function>glXSelectEvent</function> overrides any previous event mask that was
  61             set by the client for <parameter>draw</parameter>. Note that it does not affect the
  62             event masks that other clients may have specified for <parameter>draw</parameter> since
  63             each client rendering to <parameter>draw</parameter> has a separate event mask for it.
  64         </para>
  65         <para>
  66             Currently, only one GLX event, <constant>GLX_PBUFFER_CLOBBER_MASK</constant>,
  67             can be selected. The following data is returned to the client when a
  68             <constant>GLX_PBUFFER_CLOBBER_MASK</constant> event occurs:
  69         </para>
  70         <para>
  71             typedef struct {
  72         </para>
  73         <informaltable frame="topbot">
  74             <tgroup cols="2" align="left">
  75                 <colspec/>
  76                 <colspec/>
  77                 <tbody>
  78                     <row>
  79                         <entry align="left">
  80                             int <emphasis>event_type</emphasis>;
  81                         </entry>
  82                         <entry align="left">
  83                         /* GLX_DAMAGED or GLX_SAVED */
  84                         </entry>
  85                     </row>
  86                     <row>
  87                         <entry align="left">
  88                             int <emphasis>draw_type</emphasis>;
  89                         </entry>
  90                         <entry align="left">
  91                         /* GLX_WINDOW or GLX_PBUFFER */
  92                         </entry>
  93                     </row>
  94                     <row>
  95                         <entry align="left">
  96                             unsigned long <emphasis>serial</emphasis>;
  97                         </entry>
  98                         <entry align="left">
  99                         /* # of last request processed by server */
 100                         </entry>
 101                     </row>
 102                     <row>
 103                         <entry align="left">
 104                             Bool <emphasis>send_event</emphasis>;
 105                         </entry>
 106                         <entry align="left">
 107                         /* true if this came for SendEvent request */
 108                         </entry>
 109                     </row>
 110                     <row>
 111                         <entry align="left">
 112                             Display <emphasis>*display</emphasis>;
 113                         </entry>
 114                         <entry align="left">
 115                         /* display the event was read from */
 116                         </entry>
 117                     </row>
 118                     <row>
 119                         <entry align="left">
 120                             GLXDrawable <emphasis>drawable</emphasis>;
 121                         </entry>
 122                         <entry align="left">
 123                         /* i.d. of Drawable */
 124                         </entry>
 125                     </row>
 126                     <row>
 127                         <entry align="left">
 128                             unsigned int <emphasis>buffer_mask</emphasis>;
 129                         </entry>
 130                         <entry align="left">
 131                         /* mask indicating affected buffers */
 132                         </entry>
 133                     </row>
 134                     <row>
 135                         <entry align="left">
 136                             int <emphasis>x, y</emphasis>;
 137                         </entry>
 138                         <entry align="left">
 139
 140                         </entry>
 141                     </row>
 142                     <row>
 143                         <entry align="left">
 144                             int <emphasis>width, height</emphasis>;
 145                         </entry>
 146                         <entry align="left">
 147
 148                         </entry>
 149                     </row>
 150                     <row>
 151                         <entry align="left">
 152                             int <emphasis>count</emphasis>;
 153                         </entry>
 154                         <entry align="left">
 155                         /* if nonzero, at least this many more */
 156                         </entry>
 157                     </row>
 158                 </tbody>
 159             </tgroup>
 160         </informaltable>
 161         <para>
 162             } GLXPbufferClobberEvent;
 163             The valid bit masks used in <emphasis>buffer_mask</emphasis> are:
 164         </para>
 165         <para>
 166         </para>
 167         <informaltable frame="topbot">
 168             <tgroup cols="2" align="left">
 169                 <colspec/>
 170                 <colspec/>
 171                 <thead>
 172                     <row>
 173                         <entry rowsep="1" align="left"><emphasis role="bold">
 174                         Bitmask
 175                         </emphasis></entry>
 176                         <entry rowsep="1" align="left"><emphasis role="bold">
 177                         Corresponding Buffer
 178                         </emphasis></entry>
 179                     </row>
 180                 </thead>
 181                 <tbody>
 182                     <row>
 183                         <entry align="left">
 184                         <constant>GLX_FRONT_LEFT_BUFFER_BIT</constant>
 185                         </entry>
 186                         <entry align="left">
 187                         Front left color buffer
 188                         </entry>
 189                     </row>
 190                     <row>
 191                         <entry align="left">
 192                         <constant>GLX_FRONT_RIGHT_BUFFER_BIT</constant>
 193                         </entry>
 194                         <entry align="left">
 195                         Front right color buffer
 196                         </entry>
 197                     </row>
 198                     <row>
 199                         <entry align="left">
 200                         <constant>GLX_BACK_LEFT_BUFFER_BIT</constant>
 201                         </entry>
 202                         <entry align="left">
 203                         Back left color buffer
 204                         </entry>
 205                     </row>
 206                     <row>
 207                         <entry align="left">
 208                         <constant>GLX_BACK_RIGHT_BUFFER_BIT</constant>
 209                         </entry>
 210                         <entry align="left">
 211                         Back right color buffer
 212                         </entry>
 213                     </row>
 214                     <row>
 215                         <entry align="left">
 216                         <constant>GLX_AUX_BUFFERS_BIT</constant>
 217                         </entry>
 218                         <entry align="left">
 219                         Auxiliary buffer
 220                         </entry>
 221                     </row>
 222                     <row>
 223                         <entry align="left">
 224                         <constant>GLX_DEPTH_BUFFER_BIT</constant>
 225                         </entry>
 226                         <entry align="left">
 227                         Depth buffer
 228                         </entry>
 229                     </row>
 230                     <row>
 231                         <entry align="left">
 232                         <constant>GLX_STENCIL_BUFFER_BIT</constant>
 233                         </entry>
 234                         <entry align="left">
 235                         Stencil buffer
 236                         </entry>
 237                     </row>
 238                     <row>
 239                         <entry align="left">
 240                         <constant>GLX_ACCUM_BUFFER_BIT</constant>
 241                         </entry>
 242                         <entry align="left">
 243                         Accumulation buffer
 244                         </entry>
 245                     </row>
 246                 </tbody>
 247             </tgroup>
 248         </informaltable>
 249         <para>
 250             A single X server operation can cause several buffer clobber events to be
 251             sent. (e.g., a single GLX pixel buffer may be damaged and cause multiple
 252             buffer clobber events to be generated). Each event specifies one
 253             region of the GLX drawable that was affected by the X Server operation.
 254             The <emphasis>buffer_mask</emphasis> field indicates which color buffers and
 255             ancillary buffers were affected. All the buffer clobber events
 256             generated by a single X server action are guaranteed to be
 257             contiguous in the event queue. The conditions under which this event is
 258             generated and the <emphasis>event_type</emphasis> varies, depending on the type of the
 259             GLX drawable.
 260         </para>
 261         <para>
 262             When the <constant>GLX_AUX_BUFFERS_BIT</constant> is set in <emphasis>buffer_mask</emphasis>, then
 263             <emphasis>aux_buffer</emphasis> is set to indicate which buffer was affected. If more
 264             than one aux buffer was affected, then additional events are
 265             generated as part of the same contiguous event group. Each
 266             additional event will have only the <constant>GLX_AUX_BUFFERS_BIT</constant> set in
 267             <emphasis>buffer_mask</emphasis>, and the <emphasis>aux_buffer</emphasis> field will be set
 268             appropriately. For nonstereo drawables,
 269             <constant>GLX_FRONT_LEFT_BUFFER_BIT</constant> and <constant>GLX_BACK_LEFT_BUFFER_BIT</constant> are
 270             used to specify the front and back color buffers.
 271         </para>
 272         <para>
 273             For preserved GLX pixel buffers, a buffer clobber event with
 274             type <constant>GLX_SAVED</constant> is generated whenever the contents of the
 275             GLX pixel buffer is moved out of offscreen memory. The event(s) describes which
 276             portions of the GLX pixel buffer were affected. Clients who receive many
 277             buffer clobber events, referring to different save actions,
 278             should consider freeing the GLX pixel buffer resource in order to prevent
 279             the system from thrashing due to insufficient resources.
 280         </para>
 281         <para>
 282             For an unpreserved GLXPbuffer, a buffer clobber event, with type
 283             <constant>GLX_DAMAGED</constant>, is generated whenever a portion of the GLX pixel buffer
 284             becomes invalid. The client may wish to regenerate the invalid portions
 285             of the GLX pixel buffer.
 286         </para>
 287         <para>
 288             For Windows, buffer clobber events, with type <constant>GLX_SAVED</constant>, occur
 289             whenever an ancillary buffer, associated with the window, gets clobbered
 290             or moved out of off-screen memory. The event contains information
 291             indicating which color buffers and ancillary buffers\(emand which portions
 292             of those buffers\(emwere affected.
 293         </para>
 294     </refsect1>
 295     <refsect1 id="notes"><title>Notes</title>
 296         <para>
 297             <function>glXSelectEvent</function> is available only if the GLX version is 1.3 or greater.
 298         </para>
 299         <para>
 300             If the GLX version is 1.1 or 1.0, the GL version must be 1.0.
 301             If the GLX version is 1.2, then the GL version must be 1.1.
 302             If the GLX version is 1.3, then the GL version must be 1.2.
 303         </para>
 304     </refsect1>
 305     <refsect1 id="errors"><title>Errors</title>
 306         <para>
 307             <constant>GLXBadDrawable</constant> is generated if <parameter>draw</parameter> is not a valid window
 308             or a valid GLX pixel buffer.
 309         </para>
 310     </refsect1>
 311     <refsect1 id="associatedgets"><title>Associated Gets</title>
 312         <para>
 313             <citerefentry><refentrytitle>glXGetSelectedEvent</refentrytitle></citerefentry>
 314         </para>
 315     </refsect1>
 316     <refsect1 id="seealso"><title>See Also</title>
 317         <para>
 318             <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>
 319         </para>
 320     </refsect1>
 321     <refsect1 id="Copyright"><title>Copyright</title>
 322         <para>
 323             Copyright <trademark class="copyright"></trademark> 1991-2006
 324             Silicon Graphics, Inc. This document is licensed under the SGI
 325             Free Software B License. For details, see
 326             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 327         </para>
 328     </refsect1>
 329 </refentry>