upstream-man-pages/man2/xhtml/glXChooseVisual.xml

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
   2 <!-- saved from url=(0013)about:internet -->
   3 <?xml-stylesheet type="text/xsl" href="mathml.xsl"?><html xmlns="http://www.w3.org/1999/xhtml" xmlns:pref="http://www.w3.org/2002/Math/preference" pref:renderer="mathplayer-dl"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>glXChooseVisual</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glXChooseVisual"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glXChooseVisual — return a visual that matches specified attributes</p></div><div class="refsynopsisdiv"><h2>C Specification</h2><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0"><tr><td><code class="funcdef">XVisualInfo* <b class="fsfunc">glXChooseVisual</b>(</code></td><td>Display *  </td><td><var class="pdparam">dpy</var>, </td></tr><tr><td> </td><td>int  </td><td><var class="pdparam">screen</var>, </td></tr><tr><td> </td><td>int *  </td><td><var class="pdparam">attribList</var><code>)</code>;</td></tr></table></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="parameters"></a><h2>Parameters</h2><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>dpy</code></em></span></dt><dd><p>
   4                     Specifies the connection to the X server.
   5                 </p></dd><dt><span class="term"><em class="parameter"><code>screen</code></em></span></dt><dd><p>
   6                     Specifies the screen number.
   7                 </p></dd><dt><span class="term"><em class="parameter"><code>attribList</code></em></span></dt><dd><p>
   8                     Specifies a list of boolean attributes and integer attribute/value pairs.
   9                     The last attribute must be <code class="constant">None</code>.
  10                 </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="description"></a><h2>Description</h2><p>
  11             <code class="function">glXChooseVisual</code> returns a pointer to an XVisualInfo structure describing the visual
  12             that best meets a minimum specification.
  13             The boolean GLX attributes of the visual that is returned will match the
  14             specified values,
  15             and the integer GLX attributes will meet or exceed the specified
  16             minimum values.
  17             If all other attributes are equivalent, then TrueColor and PseudoColor
  18             visuals have priority over DirectColor and StaticColor visuals,
  19             respectively.
  20             If no conforming visual exists, <code class="constant">NULL</code> is returned.
  21             To free the data returned by this function, use <code class="function">XFree</code>.
  22         </p><p>
  23             All boolean GLX attributes default to <code class="constant">False</code>
  24             except <code class="constant">GLX_USE_GL</code>,
  25             which defaults to <code class="constant">True</code>.
  26             All integer GLX attributes default to zero.
  27             Default specifications are superseded by attributes included in <em class="parameter"><code>attribList</code></em>.
  28             Boolean attributes included in <em class="parameter"><code>attribList</code></em> are understood to be <code class="constant">True</code>.
  29             Integer attributes and enumerated type attributes are followed immediately
  30             by the corresponding desired or
  31             minimum value.
  32             The list must be terminated with <code class="constant">None</code>.
  33         </p><p>
  34             The interpretations of the various GLX visual attributes are as follows:
  35         </p><div class="variablelist"><dl><dt><span class="term"><code class="constant">GLX_USE_GL</code></span></dt><dd><p>
  36                         Ignored.
  37                         Only visuals that can be rendered with GLX are considered.
  38                     </p></dd><dt><span class="term"><code class="constant">GLX_BUFFER_SIZE</code></span></dt><dd><p>
  39                         Must be followed by a nonnegative integer that indicates the desired
  40                         color index buffer size.
  41                         The smallest index buffer of at least the specified size is preferred.
  42                         Ignored if <code class="constant">GLX_RGBA</code> is asserted.
  43                     </p></dd><dt><span class="term"><code class="constant">GLX_LEVEL</code></span></dt><dd><p>
  44                         Must be followed by an integer buffer-level specification.
  45                         This specification is honored exactly.
  46                         Buffer level zero corresponds to the main frame buffer of the display.
  47                         Buffer level one is the first overlay frame buffer, level two the second
  48                         overlay frame buffer, and so on.
  49                         Negative buffer levels correspond to underlay frame buffers.
  50                     </p></dd><dt><span class="term"><code class="constant">GLX_RGBA</code></span></dt><dd><p>
  51                         If present,
  52                         only TrueColor and DirectColor visuals are considered.
  53                         Otherwise,
  54                         only PseudoColor and StaticColor visuals are considered.
  55                     </p></dd><dt><span class="term"><code class="constant">GLX_DOUBLEBUFFER</code></span></dt><dd><p>
  56                         If present,
  57                         only double-buffered visuals are considered.
  58                         Otherwise,
  59                         only single-buffered visuals are considered.
  60                     </p></dd><dt><span class="term"><code class="constant">GLX_STEREO</code></span></dt><dd><p>
  61                         If present,
  62                         only stereo visuals are considered.
  63                         Otherwise,
  64                         only monoscopic visuals are considered.
  65                     </p></dd><dt><span class="term"><code class="constant">GLX_AUX_BUFFERS</code></span></dt><dd><p>
  66                         Must be followed by a nonnegative integer that indicates the desired
  67                         number of auxiliary buffers.
  68                         Visuals with the
  69                         smallest number of auxiliary buffers that meets or exceeds
  70                         the specified number are preferred.
  71                     </p></dd><dt><span class="term"><code class="constant">GLX_RED_SIZE</code></span></dt><dd><p>
  72                         Must be followed by a nonnegative minimum size specification.
  73                         If this value is zero,
  74                         the smallest available red buffer is preferred.
  75                         Otherwise, the largest available red buffer of at least the minimum size
  76                         is preferred.
  77                     </p></dd><dt><span class="term"><code class="constant">GLX_GREEN_SIZE</code></span></dt><dd><p>
  78                         Must be followed by a nonnegative minimum size specification.
  79                         If this value is zero,
  80                         the smallest available green buffer is preferred.
  81                         Otherwise, the largest available green buffer of at least the minimum size
  82                         is preferred.
  83                     </p></dd><dt><span class="term"><code class="constant">GLX_BLUE_SIZE</code></span></dt><dd><p>
  84                         Must be followed by a nonnegative minimum size specification.
  85                         If this value is zero,
  86                         the smallest available blue buffer is preferred.
  87                         Otherwise, the largest available blue buffer of at least the minimum size
  88                         is preferred.
  89                     </p></dd><dt><span class="term"><code class="constant">GLX_ALPHA_SIZE</code></span></dt><dd><p>
  90                         Must be followed by a nonnegative minimum size specification.
  91                         If this value is zero,
  92                         the smallest available alpha buffer is preferred.
  93                         Otherwise, the largest available alpha buffer of at least the minimum size
  94                         is preferred.
  95                     </p></dd><dt><span class="term"><code class="constant">GLX_DEPTH_SIZE</code></span></dt><dd><p>
  96                         Must be followed by a nonnegative minimum size specification.
  97                         If this value is zero,
  98                         visuals with no depth buffer are preferred.
  99                         Otherwise, the largest available depth buffer of at least the minimum size
 100                         is preferred.
 101                     </p></dd><dt><span class="term"><code class="constant">GLX_STENCIL_SIZE</code></span></dt><dd><p>
 102                         Must be followed by a nonnegative integer that indicates the desired
 103                         number of stencil bitplanes.
 104                         The smallest stencil buffer of at least the specified size is preferred.
 105                         If the desired value is zero,
 106                         visuals with no stencil buffer are preferred.
 107                     </p></dd><dt><span class="term"><code class="constant">GLX_ACCUM_RED_SIZE</code></span></dt><dd><p>
 108                         Must be followed by a nonnegative minimum size specification.
 109                         If this value is zero,
 110                         visuals with no red accumulation buffer are preferred.
 111                         Otherwise, the largest possible red accumulation buffer
 112                         of at least the minimum size is preferred.
 113                     </p></dd><dt><span class="term"><code class="constant">GLX_ACCUM_GREEN_SIZE</code></span></dt><dd><p>
 114                         Must be followed by a nonnegative minimum size specification.
 115                         If this value is zero,
 116                         visuals with no green accumulation buffer are preferred.
 117                         Otherwise, the largest possible green accumulation buffer
 118                         of at least the minimum size is preferred.
 119                     </p></dd><dt><span class="term"><code class="constant">GLX_ACCUM_BLUE_SIZE</code></span></dt><dd><p>
 120                         Must be followed by a nonnegative minimum size specification.
 121                         If this value is zero,
 122                         visuals with no blue accumulation buffer are preferred.
 123                         Otherwise, the largest possible blue accumulation buffer
 124                         of at least the minimum size is preferred.
 125                     </p></dd><dt><span class="term"><code class="constant">GLX_ACCUM_ALPHA_SIZE</code></span></dt><dd><p>
 126                         Must be followed by a nonnegative minimum size specification.
 127                         If this value is zero,
 128                         visuals with no alpha accumulation buffer are preferred.
 129                         Otherwise, the largest possible alpha accumulation buffer
 130                         of at least the minimum size is preferred.
 131                     </p></dd></dl></div></div><div class="refsect1" lang="en" xml:lang="en"><a id="examples"></a><h2>Examples</h2><p>
 132         </p><div class="variablelist"><dl><dt><span class="term"><em class="parameter"><code>attribList</code></em> =</span></dt><dd><p>
 133                         {<code class="constant">GLX_RGBA</code>,
 134                         <code class="constant">GLX_RED_SIZE</code>, 4,
 135                         <code class="constant">GLX_GREEN_SIZE</code>, 4,
 136                         <code class="constant">GLX_BLUE_SIZE</code>, 4,
 137                         <code class="constant">None</code>};
 138                     </p></dd></dl></div><p>
 139             Specifies a single-buffered RGB visual in the normal frame buffer,
 140             not an overlay or underlay buffer.
 141             The returned visual supports at least four bits each of red,
 142             green, and blue,
 143             and possibly no bits of alpha.
 144             It does not support color index mode,
 145             double-buffering, or stereo display.
 146             It may or may not have one or more auxiliary color buffers,
 147             a depth buffer,
 148             a stencil buffer,
 149             or an accumulation buffer.
 150         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
 151             <code class="constant">XVisualInfo</code> is defined in <span class="emphasis"><em>Xutil.h.</em></span>
 152             It is a structure that includes <span class="emphasis"><em>visual</em></span>, <span class="emphasis"><em>visualID</em></span>, <span class="emphasis"><em>screen</em></span>, and
 153             <span class="emphasis"><em>depth</em></span> elements.
 154         </p><p>
 155             <code class="function">glXChooseVisual</code> is implemented as a client-side utility using only <code class="function">XGetVisualInfo</code>
 156             and <a class="citerefentry" href="glXGetConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetConfig</span></span></a>.
 157             Calls to these two routines can be used to implement selection algorithms
 158             other than the generic one implemented by <code class="function">glXChooseVisual</code>.
 159         </p><p>
 160             GLX implementations are strongly discouraged,
 161             but not proscribed,
 162             from changing the selection algorithm used by <code class="function">glXChooseVisual</code>.
 163             Therefore, selections may change from release to release
 164             of the client-side library.
 165         </p><p>
 166             There is no direct filter for picking only visuals that
 167             support GLXPixmaps.
 168             GLXPixmaps are supported for visuals whose
 169             <code class="constant">GLX_BUFFER_SIZE</code>
 170             is one of the pixmap depths supported by the X server.
 171         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="errors"></a><h2>Errors</h2><p>
 172             <code class="constant">NULL</code> is returned if an undefined GLX attribute is encountered in
 173             <em class="parameter"><code>attribList</code></em>.
 174         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
 175             <a class="citerefentry" href="glXCreateContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateContext</span></span></a>,
 176             <a class="citerefentry" href="glXGetConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetConfig</span></span></a>
 177         </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
 178             Copyright <span class="trademark"></span>© 1991-2006
 179             Silicon Graphics, Inc. This document is licensed under the SGI
 180             Free Software B License. For details, see
 181             <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
 182         </p></div></div></body></html>