upstream-man-pages/man2/glXGetConfig.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="glXGetConfig">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXGetConfig</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXGetConfig</refname>
  17         <refpurpose>return information about GLX visuals</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>int <function>glXGetConfig</function></funcdef>
  23                 <paramdef>Display * <parameter>dpy</parameter></paramdef>
  24                 <paramdef>XVisualInfo * <parameter>vis</parameter></paramdef>
  25                 <paramdef>int <parameter>attrib</parameter></paramdef>
  26                 <paramdef>int * <parameter>value</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <!-- eqn: ignoring delim $$ -->
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>dpy</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specifies the connection to the X server.
  38                 </para>
  39             </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42             <term><parameter>vis</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies the visual to be queried.
  46                     It is a pointer to an <constant>XVisualInfo</constant> structure,
  47                     not a visual ID or a pointer to a <constant>Visual</constant>.
  48                 </para>
  49             </listitem>
  50         </varlistentry>
  51         <varlistentry>
  52             <term><parameter>attrib</parameter></term>
  53             <listitem>
  54                 <para>
  55                     Specifies the visual attribute to be returned.
  56                 </para>
  57             </listitem>
  58         </varlistentry>
  59         <varlistentry>
  60             <term><parameter>value</parameter></term>
  61             <listitem>
  62                 <para>
  63                     Returns the requested value.
  64                 </para>
  65             </listitem>
  66         </varlistentry>
  67         </variablelist>
  68     </refsect1>
  69     <refsect1 id="description"><title>Description</title>
  70         <para>
  71             <function>glXGetConfig</function> sets <parameter>value</parameter> to the <parameter>attrib</parameter> value of windows or GLX pixmaps
  72             created with respect to <parameter>vis</parameter>.
  73             <function>glXGetConfig</function> returns an error code if it fails for any reason.
  74             Otherwise, zero is returned.
  75         </para>
  76         <para>
  77             <parameter>attrib</parameter> is one of the following:
  78         </para>
  79         <para>
  80         </para>
  81         <variablelist>
  82             <varlistentry>
  83                 <term><constant>GLX_USE_GL</constant></term>
  84                 <listitem>
  85                     <para>
  86                         <constant>True</constant> if OpenGL rendering is supported by this visual,
  87                         <constant>False</constant> otherwise.
  88                     </para>
  89                 </listitem>
  90             </varlistentry>
  91             <varlistentry>
  92                 <term><constant>GLX_BUFFER_SIZE</constant></term>
  93                 <listitem>
  94                     <para>
  95                         Number of bits per color buffer.
  96                         For RGBA visuals, <constant>GLX_BUFFER_SIZE</constant> is the sum of
  97                         <constant>GLX_RED_SIZE</constant>,
  98                         <constant>GLX_GREEN_SIZE</constant>,
  99                         <constant>GLX_BLUE_SIZE</constant>, and
 100                         <constant>GLX_ALPHA_SIZE</constant>.
 101                         For color index visuals, <constant>GLX_BUFFER_SIZE</constant> is the size of the
 102                         color indexes.
 103                     </para>
 104                 </listitem>
 105             </varlistentry>
 106             <varlistentry>
 107                 <term><constant>GLX_LEVEL</constant></term>
 108                 <listitem>
 109                     <para>
 110                         Frame buffer level of the visual.
 111                         Level zero is the default frame buffer.
 112                         Positive levels correspond to frame buffers that overlay the default buffer,
 113                         and negative levels correspond to frame buffers that underlay the default
 114                         buffer.
 115                     </para>
 116                 </listitem>
 117             </varlistentry>
 118             <varlistentry>
 119                 <term><constant>GLX_RGBA</constant></term>
 120                 <listitem>
 121                     <para>
 122                         <constant>True</constant> if color buffers store red, green, blue, and alpha values.
 123                         <constant>False</constant> if they store color indexes.
 124                     </para>
 125                 </listitem>
 126             </varlistentry>
 127             <varlistentry>
 128                 <term><constant>GLX_DOUBLEBUFFER</constant></term>
 129                 <listitem>
 130                     <para>
 131                         <constant>True</constant> if color buffers exist in front/back pairs that can be swapped,
 132                         <constant>False</constant> otherwise.
 133                     </para>
 134                 </listitem>
 135             </varlistentry>
 136             <varlistentry>
 137                 <term><constant>GLX_STEREO</constant></term>
 138                 <listitem>
 139                     <para>
 140                         <constant>True</constant> if color buffers exist in left/right pairs,
 141                         <constant>False</constant> otherwise.
 142                     </para>
 143                 </listitem>
 144             </varlistentry>
 145             <varlistentry>
 146                 <term><constant>GLX_AUX_BUFFERS</constant></term>
 147                 <listitem>
 148                     <para>
 149                         Number of auxiliary color buffers that are available.
 150                         Zero indicates that no auxiliary color buffers exist.
 151                     </para>
 152                 </listitem>
 153             </varlistentry>
 154             <varlistentry>
 155                 <term><constant>GLX_RED_SIZE</constant></term>
 156                 <listitem>
 157                     <para>
 158                         Number of bits of red stored in each color buffer.
 159                         Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
 160                     </para>
 161                 </listitem>
 162             </varlistentry>
 163             <varlistentry>
 164                 <term><constant>GLX_GREEN_SIZE</constant></term>
 165                 <listitem>
 166                     <para>
 167                         Number of bits of green stored in each color buffer.
 168                         Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
 169                     </para>
 170                 </listitem>
 171             </varlistentry>
 172             <varlistentry>
 173                 <term><constant>GLX_BLUE_SIZE</constant></term>
 174                 <listitem>
 175                     <para>
 176                         Number of bits of blue stored in each color buffer.
 177                         Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
 178                     </para>
 179                 </listitem>
 180             </varlistentry>
 181             <varlistentry>
 182                 <term><constant>GLX_ALPHA_SIZE</constant></term>
 183                 <listitem>
 184                     <para>
 185                         Number of bits of alpha stored in each color buffer.
 186                         Undefined if <constant>GLX_RGBA</constant> is <constant>False</constant>.
 187                     </para>
 188                 </listitem>
 189             </varlistentry>
 190             <varlistentry>
 191                 <term><constant>GLX_DEPTH_SIZE</constant></term>
 192                 <listitem>
 193                     <para>
 194                         Number of bits in the depth buffer.
 195                     </para>
 196                 </listitem>
 197             </varlistentry>
 198             <varlistentry>
 199                 <term><constant>GLX_STENCIL_SIZE</constant></term>
 200                 <listitem>
 201                     <para>
 202                         Number of bits in the stencil buffer.
 203                     </para>
 204                 </listitem>
 205             </varlistentry>
 206             <varlistentry>
 207                 <term><constant>GLX_ACCUM_RED_SIZE</constant></term>
 208                 <listitem>
 209                     <para>
 210                         Number of bits of red stored in the accumulation buffer.
 211                     </para>
 212                 </listitem>
 213             </varlistentry>
 214             <varlistentry>
 215                 <term><constant>GLX_ACCUM_GREEN_SIZE</constant></term>
 216                 <listitem>
 217                     <para>
 218                         Number of bits of green stored in the accumulation buffer.
 219                     </para>
 220                 </listitem>
 221             </varlistentry>
 222             <varlistentry>
 223                 <term><constant>GLX_ACCUM_BLUE_SIZE</constant></term>
 224                 <listitem>
 225                     <para>
 226                         Number of bits of blue stored in the accumulation buffer.
 227                     </para>
 228                 </listitem>
 229             </varlistentry>
 230             <varlistentry>
 231                 <term><constant>GLX_ACCUM_ALPHA_SIZE</constant></term>
 232                 <listitem>
 233                     <para>
 234                         Number of bits of alpha stored in the accumulation buffer.
 235                     </para>
 236                 </listitem>
 237             </varlistentry>
 238         </variablelist>
 239         <para>
 240             The X protocol allows a single visual ID to be instantiated with
 241             different numbers of bits per pixel.
 242             Windows or GLX pixmaps that will be rendered with OpenGL, however,
 243             must be instantiated with a color buffer depth of <constant>GLX_BUFFER_SIZE</constant>.
 244         </para>
 245         <para>
 246             Although a GLX implementation can export many visuals that support GL
 247             rendering,
 248             it must support
 249             at least one RGBA visual. This visual must have at
 250             least one color buffer,
 251             a stencil buffer of at least 1 bit,
 252             a depth buffer of at least 12 bits,
 253             and an accumulation buffer.
 254             Alpha bitplanes are optional in this visual.
 255             However,
 256             its color buffer size must be as great as that of the
 257             deepest <constant>TrueColor</constant>, <constant>DirectColor</constant>,
 258             <constant>PseudoColor</constant>, or <constant>StaticColor</constant> visual supported on level zero,
 259             and it must itself be made available on level zero.
 260         </para>
 261         <para>
 262             In addition, if the X server exports a <constant>PseudoColor</constant>
 263             or <constant>StaticColor</constant> visual on framebuffer level 0, a color index
 264             visual is also required on that level.
 265             It must have
 266             at least one color buffer,
 267             a stencil buffer of at least 1 bit,
 268             and a depth buffer of at least 12 bits.
 269             This visual must
 270             have as many
 271             color bitplanes as the deepest
 272             <constant>PseudoColor</constant> or <constant>StaticColor</constant> visual supported on level 0.
 273         </para>
 274         <para>
 275             Applications are best written to select the visual that most closely
 276             meets their requirements.
 277             Creating windows or GLX pixmaps with unnecessary buffers can result in
 278             reduced rendering performance as well as poor resource allocation.
 279         </para>
 280     </refsect1>
 281     <refsect1 id="notes"><title>Notes</title>
 282         <para>
 283             <constant>XVisualInfo</constant> is defined in <emphasis>Xutil.h.</emphasis>
 284             It is a structure that includes <emphasis>visual</emphasis>, <emphasis>visualID</emphasis>, <emphasis>screen</emphasis>, and
 285             <emphasis>depth</emphasis> elements.
 286         </para>
 287     </refsect1>
 288     <refsect1 id="errors"><title>Errors</title>
 289         <para>
 290             <constant>GLX_NO_EXTENSION</constant> is returned if <parameter>dpy</parameter> does not support the GLX
 291             extension.
 292         </para>
 293         <para>
 294             <constant>GLX_BAD_SCREEN</constant> is returned if the screen of <parameter>vis</parameter> does not correspond
 295             to a screen.
 296         </para>
 297         <para>
 298             <constant>GLX_BAD_ATTRIBUTE</constant> is returned if <parameter>attrib</parameter> is not a valid GLX attribute.
 299         </para>
 300         <para>
 301             <constant>GLX_BAD_VISUAL</constant> is returned if <parameter>vis</parameter> doesn't support GLX and an
 302             attribute other than <constant>GLX_USE_GL</constant> is requested.
 303         </para>
 304     </refsect1>
 305     <refsect1 id="seealso"><title>See Also</title>
 306         <para>
 307             <citerefentry><refentrytitle>glXChooseVisual</refentrytitle></citerefentry>,
 308             <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>
 309         </para>
 310     </refsect1>
 311     <refsect1 id="Copyright"><title>Copyright</title>
 312         <para>
 313             Copyright <trademark class="copyright"></trademark> 1991-2006
 314             Silicon Graphics, Inc. This document is licensed under the SGI
 315             Free Software B License. For details, see
 316             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 317         </para>
 318     </refsect1>
 319 </refentry>