upstream-doc/man2/glXIntro.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="glXIntro">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXIntro</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXIntro</refname>
  17         <refpurpose>Introduction to OpenGL in the X window system</refpurpose>
  18     </refnamediv>
  19     <refsect1 id="overview"><title>Overview</title>
  20         <para>
  21         </para>
  22         <para>
  23             OpenGL (called GL in other pages) is a high-performance 3D-oriented
  24             renderer.  It is available in the X window system through the GLX extension.
  25             To determine whether the GLX extension is supported by an X server, and if
  26             so, what version is supported, call <citerefentry><refentrytitle>glXQueryExtension</refentrytitle></citerefentry> and
  27             <citerefentry><refentrytitle>glXQueryVersion</refentrytitle></citerefentry>.
  28         </para>
  29         <para>
  30             GLX extended X servers make a subset of their visuals available for OpenGL
  31             rendering.  Drawables created with these visual can also be rendered into
  32             using the core X renderer and or any other X extension that is compatible
  33             with all core X visuals.
  34         </para>
  35         <para>
  36             GLX extends a drawable's standard color buffer with additional buffers.
  37             These buffers include back and auxiliary color buffers, a depth buffer, a
  38             stencil buffer, and a color accumulation buffer.  Some or all of the buffers
  39             listed are included in each X visual that supports OpenGL.
  40         </para>
  41         <para>
  42             GLX supports rendering into three types of drawables: windows, pixmaps, and
  43             pbuffers (pixel buffers). GLX windows and pixmaps are X resources, and
  44             capable of accepting core X rendering as well as OpenGL rendering.
  45             GLX-pbuffers are GLX only resources and might not accept core X rendering.
  46         </para>
  47         <para>
  48             To render using OpenGL into a GLX drawable, you must determine the
  49             appropriate GLXFBConfig that supports the rendering features your
  50             application requires. <citerefentry><refentrytitle>glXChooseFBConfig</refentrytitle></citerefentry> returns a GLXFBConfig matching
  51             the required attributes or <constant>NULL</constant> if no match is found.  A complete
  52             list of GLXFBConfigs supported by a server can be obtained by calling
  53             <citerefentry><refentrytitle>glXGetFBConfigs</refentrytitle></citerefentry>.  Attributes of a particular GLXFBConfig can be
  54             queried by calling <citerefentry><refentrytitle>glXGetFBConfigAttrib</refentrytitle></citerefentry>.
  55         </para>
  56         <para>
  57             For GLX windows and pixmaps, a suitable X drawable (using either
  58             <function>XCreateWindow</function> or <function>XCreatePixmap</function>, respectively) with a matching
  59             visual must be created first.  Call <citerefentry><refentrytitle>glXGetVisualFromFBConfig</refentrytitle></citerefentry> to obtain
  60             the necessary XVisualInfo structure for creating the X drawable.  For
  61             pbuffers, no underlying X drawable is required.
  62         </para>
  63         <para>
  64             To create a GLX window from an X window, call <citerefentry><refentrytitle>glXCreateWindow</refentrytitle></citerefentry>.
  65             Likewise, to create a GLX pixmap, call <citerefentry><refentrytitle>glXCreatePixmap</refentrytitle></citerefentry>. Pbuffers are
  66             created by calling <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>.  Use <citerefentry><refentrytitle>glXDestroyWindow</refentrytitle></citerefentry>,
  67             <citerefentry><refentrytitle>glXDestroyPixmap</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glXDestroyPbuffer</refentrytitle></citerefentry> to release previously
  68             allocated resources.
  69         </para>
  70         <para>
  71             A GLX context is required to bind OpenGL rendering to a GLX resource.  A GLX
  72             resource and rendering context must have compatible GLXFBConfigs.  To create
  73             a GLX context, call <citerefentry><refentrytitle>glXCreateNewContext</refentrytitle></citerefentry>.  A context may be bound to a
  74             GLX drawable by using <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>.  This context/drawable
  75             pair becomes the current context and current drawable, and is used by all
  76             OpenGL rendering commands until <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry> is called with
  77             different arguments.
  78         </para>
  79         <para>
  80             Both core X and OpenGL commands can be used to operate on drawables;
  81             however, the X and OpenGL command streams are not synchronized.
  82             Synchronization can be explicitly specified using by calling <citerefentry><refentrytitle>glXWaitGL</refentrytitle></citerefentry>,
  83             <citerefentry><refentrytitle>glXWaitX</refentrytitle></citerefentry>, <function>XSync</function>, and <function>XFlush</function>.
  84         </para>
  85         <para>
  86         </para>
  87     </refsect1>
  88     <refsect1 id="examples"><title>Examples</title>
  89         <para>
  90             Below is a minimal example of creating an RGBA-format X window that's
  91             compatible with OpenGL using GLX 1.3 commands.  The window is cleared to
  92             yellow when the program runs.  The program does minimal error checking; all
  93             return values should be checked.
  94         </para>
  95         <para>
  96             <programlisting>
  97 #include &lt;stdio.h&gt;
  98 #include &lt;stdlib.h&gt;
  99 #include &lt;GL/gl.h&gt;
 100 #include &lt;GL/glx.h&gt;
 101
 102 int singleBufferAttributess[] = {
 103     GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
 104     GLX_RENDER_TYPE,   GLX_RGBA_BIT,
 105     GLX_RED_SIZE,      1,   /* Request a single buffered color buffer */
 106     GLX_GREEN_SIZE,    1,   /* with the maximum number of color bits  */
 107     GLX_BLUE_SIZE,     1,   /* for each component                     */
 108     None
 109 };
 110
 111 int doubleBufferAttributes[] = {
 112     GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
 113     GLX_RENDER_TYPE,   GLX_RGBA_BIT,
 114     GLX_DOUBLEBUFFER,  True,  /* Request a double-buffered color buffer with */
 115     GLX_RED_SIZE,      1,     /* the maximum number of bits per component    */
 116     GLX_GREEN_SIZE,    1,
 117     GLX_BLUE_SIZE,     1,
 118     None
 119 };
 120
 121
 122 static Bool WaitForNotify( Display *dpy, XEvent *event, XPointer arg ) {
 123     return (event-&gt;type == MapNotify) &amp;&amp; (event-&gt;xmap.window == (Window) arg);
 124 }
 125 int main( int argc, char *argv[] )
 126 {
 127     Display              *dpy;
 128     Window                xWin;
 129     XEvent                event;
 130     XVisualInfo          *vInfo;
 131     XSetWindowAttributes  swa;
 132     GLXFBConfig          *fbConfigs;
 133     GLXContext            context;
 134     GLXWindow             glxWin;
 135     int                   swaMask;
 136     int                   numReturned;
 137     int                   swapFlag = True;
 138
 139     /* Open a connection to the X server */
 140     dpy = XOpenDisplay( NULL );
 141     if ( dpy == NULL ) {
 142         printf( "Unable to open a connection to the X server\n" );
 143         exit( EXIT_FAILURE );
 144     }
 145
 146     /* Request a suitable framebuffer configuration - try for a double
 147     ** buffered configuration first */
 148     fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
 149                                    doubleBufferAttributes, &amp;numReturned );
 150
 151     if ( fbConfigs == NULL ) {  /* no double buffered configs available */
 152       fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
 153                                      singleBufferAttributess, &amp;numReturned );
 154       swapFlag = False;
 155     }
 156
 157     /* Create an X colormap and window with a visual matching the first
 158     ** returned framebuffer config */
 159     vInfo = glXGetVisualFromFBConfig( dpy, fbConfigs[0] );
 160
 161     swa.border_pixel = 0;
 162     swa.event_mask = StructureNotifyMask;
 163     swa.colormap = XCreateColormap( dpy, RootWindow(dpy, vInfo-&gt;screen),
 164                                     vInfo-&gt;visual, AllocNone );
 165
 166     swaMask = CWBorderPixel | CWColormap | CWEventMask;
 167
 168     xWin = XCreateWindow( dpy, RootWindow(dpy, vInfo-&gt;screen), 0, 0, 256, 256,
 169                           0, vInfo-&gt;depth, InputOutput, vInfo-&gt;visual,
 170                           swaMask, &amp;swa );
 171
 172     /* Create a GLX context for OpenGL rendering */
 173     context = glXCreateNewContext( dpy, fbConfigs[0], GLX_RGBA_TYPE,
 174                                  NULL, True );
 175
 176     /* Create a GLX window to associate the frame buffer configuration
 177     ** with the created X window */
 178     glxWin = glXCreateWindow( dpy, fbConfigs[0], xWin, NULL );
 179
 180     /* Map the window to the screen, and wait for it to appear */
 181     XMapWindow( dpy, xWin );
 182     XIfEvent( dpy, &amp;event, WaitForNotify, (XPointer) xWin );
 183
 184     /* Bind the GLX context to the Window */
 185     glXMakeContextCurrent( dpy, glxWin, glxWin, context );
 186
 187     /* OpenGL rendering ... */
 188     glClearColor( 1.0, 1.0, 0.0, 1.0 );
 189     glClear( GL_COLOR_BUFFER_BIT );
 190
 191     glFlush();
 192
 193     if ( swapFlag )
 194         glXSwapBuffers( dpy, glxWin );
 195
 196     sleep( 10 );
 197     exit( EXIT_SUCCESS );
 198 }
 199             </programlisting>
 200         </para>
 201         <para>
 202         </para>
 203     </refsect1>
 204     <refsect1 id="notes"><title>Notes</title>
 205         <para>
 206             An X color map must be created and passed to <function>XCreateWindow</function>.
 207         </para>
 208         <para>
 209             A GLX context must be created and bound to a GLX drawable before OpenGL
 210             commands can be executed.  OpenGL commands executed while no
 211             context/drawable pair is current result in undefined behavior.
 212         </para>
 213         <para>
 214             Exposure events indicate that <emphasis>all</emphasis> buffers associated with the
 215             specified window may be damaged and should be repainted. Although certain
 216             buffers of some visuals on some systems may never require repainting (the
 217             depth buffer, for example), it is incorrect to write a program assuming that
 218             these buffers will not be damaged.
 219         </para>
 220         <para>
 221             GLX commands utilize XVisualInfo structures rather than pointers to visuals
 222             or visualIDs directly.  XVisualInfo structures contain <emphasis>visual</emphasis>,
 223             <emphasis>visualID</emphasis>, <emphasis>screen</emphasis>, and <emphasis>depth</emphasis> elements, as well as other
 224             X-specific information.
 225         </para>
 226         <para>
 227         </para>
 228     </refsect1>
 229     <refsect1 id="usingglxextensions"><title>Using GLX Extensions</title>
 230         <para>
 231             All supported GLX extensions will have a corresponding definition in glx.h
 232             and a token in the extension string returned by
 233             <citerefentry><refentrytitle>glXQueryExtensionsString</refentrytitle></citerefentry>.  For example, if the
 234             <code>EXT_visual_info</code> extension is supported, then this token will be
 235             defined in glx.h and <code>EXT_visual_info</code> will appear in the extension
 236             string returned by <citerefentry><refentrytitle>glXQueryExtensionsString</refentrytitle></citerefentry>. The definitions in glx.h
 237             can be used at compile time to determine if procedure calls corresponding to
 238             an extension exist in the library.
 239         </para>
 240         <para>
 241             OpenGL itself is capable of being extended.
 242         </para>
 243         <para>
 244         </para>
 245     </refsect1>
 246     <refsect1 id="glx11glx12andglx13"><title>GLX 1.1, GLX 1.2, and GLX 1.3</title>
 247         <para>
 248             GLX 1.3 is now supported and is backward compatible with GLX 1.1 and GLX
 249             1.2.  It introduces new functionality (namely GLXFBConfigs) that supersedes
 250             the GLX 1.2 functionality.  GLX 1.2 commands are supported, but their use in
 251             new application development is not recommended.
 252         </para>
 253         <para>
 254             GLX 1.3 corresponds to OpenGL versions 1.2 and introduces the following new
 255             calls: <citerefentry><refentrytitle>glXGetFBConfigs</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXGetFBConfigAttrib</refentrytitle></citerefentry>,
 256             <citerefentry><refentrytitle>glXGetVisualFromFBConfig</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXCreateWindow</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXDestroyWindow</refentrytitle></citerefentry>,
 257             <citerefentry><refentrytitle>glXCreatePixmap</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXDestroyPixmap</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>,
 258             <citerefentry><refentrytitle>glXDestroyPbuffer</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXQueryDrawable</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXCreateNewContext</refentrytitle></citerefentry>,
 259             <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
 260             <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXQueryContext</refentrytitle></citerefentry>, and <citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>,
 261             <citerefentry><refentrytitle>glXGetSelectedEvent</refentrytitle></citerefentry>.
 262         </para>
 263         <para>
 264             GLX 1.2 corresponds to OpenGL version 1.1 and introduces the following new
 265             call: <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>.
 266         </para>
 267         <para>
 268             GLX 1.1 corresponds to OpenGL version 1.0 and introduces the following new
 269             calls: <citerefentry><refentrytitle>glXQueryExtensionsString</refentrytitle></citerefentry>, <citerefentry><refentrytitle>glXQueryServerString</refentrytitle></citerefentry>, and
 270             <citerefentry><refentrytitle>glXGetClientString</refentrytitle></citerefentry>.
 271         </para>
 272         <para>
 273             Call <citerefentry><refentrytitle>glXQueryVersion</refentrytitle></citerefentry> to determine at runtime what version of GLX is
 274             available. <citerefentry><refentrytitle>glXQueryVersion</refentrytitle></citerefentry> returns the version that is supported on the
 275             connection. Thus, if 1.3 is returned, both the client and server support GLX
 276             1.3.  You can also check the GLX version at compile time: GLX_VERSION_1_1
 277             will be defined in glx.h if GLX 1.1 calls are supported, GLX_VERSION_1_2
 278             will be defined if GLX 1.2 calls are supported, and GLX_VERSION_1_3 will be
 279             defined if GLX 1.3 calls are supported.
 280         </para>
 281         <para>
 282         </para>
 283     </refsect1>
 284     <refsect1 id="seealso"><title>See Also</title>
 285         <para>
 286             <citerefentry><refentrytitle>glFinish</refentrytitle></citerefentry>,
 287             <citerefentry><refentrytitle>glFlush</refentrytitle></citerefentry>,
 288             <citerefentry><refentrytitle>glXChooseVisual</refentrytitle></citerefentry>,
 289             <citerefentry><refentrytitle>glXCopyContext</refentrytitle></citerefentry>,
 290             <citerefentry><refentrytitle>glXCreateContext</refentrytitle></citerefentry>,
 291             <citerefentry><refentrytitle>glXCreateGLXPixmap</refentrytitle></citerefentry>,
 292             <citerefentry><refentrytitle>glXCreateNewContext</refentrytitle></citerefentry>,
 293             <citerefentry><refentrytitle>glXCreatePbuffer</refentrytitle></citerefentry>,
 294             <citerefentry><refentrytitle>glXCreatePixmap</refentrytitle></citerefentry>,
 295             <citerefentry><refentrytitle>glXCreateWindow</refentrytitle></citerefentry>,
 296             <citerefentry><refentrytitle>glXDestroyContext</refentrytitle></citerefentry>,
 297             <citerefentry><refentrytitle>glXDestroyPbuffer</refentrytitle></citerefentry>,
 298             <citerefentry><refentrytitle>glXDestroyPixmap</refentrytitle></citerefentry>,
 299             <citerefentry><refentrytitle>glXDestroyWindow</refentrytitle></citerefentry>,
 300             <citerefentry><refentrytitle>glXGetClientString</refentrytitle></citerefentry>,
 301             <citerefentry><refentrytitle>glXGetConfig</refentrytitle></citerefentry>,
 302             <citerefentry><refentrytitle>glXGetCurrentDisplay</refentrytitle></citerefentry>,
 303             <citerefentry><refentrytitle>glXGetCurrentReadDrawable</refentrytitle></citerefentry>,
 304             <citerefentry><refentrytitle>glXGetFBConfigAttrib</refentrytitle></citerefentry>,
 305             <citerefentry><refentrytitle>glXGetFBConfigs</refentrytitle></citerefentry>,
 306             <citerefentry><refentrytitle>glXGetProcAddress</refentrytitle></citerefentry>,
 307             <citerefentry><refentrytitle>glXGetSelectedEvent</refentrytitle></citerefentry>,
 308             <citerefentry><refentrytitle>glXGetVisualFromFBConfig</refentrytitle></citerefentry>,
 309             <citerefentry><refentrytitle>glXIsDirect</refentrytitle></citerefentry>,
 310             <citerefentry><refentrytitle>glXMakeContextCurrent</refentrytitle></citerefentry>,
 311             <citerefentry><refentrytitle>glXMakeCurrent</refentrytitle></citerefentry>,
 312             <citerefentry><refentrytitle>glXQueryContext</refentrytitle></citerefentry>,
 313             <citerefentry><refentrytitle>glXQueryDrawable</refentrytitle></citerefentry>,
 314             <citerefentry><refentrytitle>glXQueryExtension</refentrytitle></citerefentry>,
 315             <citerefentry><refentrytitle>glXQueryExtensionsString</refentrytitle></citerefentry>,
 316             <citerefentry><refentrytitle>glXQueryServerString</refentrytitle></citerefentry>,
 317             <citerefentry><refentrytitle>glXQueryVersion</refentrytitle></citerefentry>,
 318             <citerefentry><refentrytitle>glXSelectEvent</refentrytitle></citerefentry>,
 319             <citerefentry><refentrytitle>glXSwapBuffers</refentrytitle></citerefentry>,
 320             <citerefentry><refentrytitle>glXUseXFont</refentrytitle></citerefentry>,
 321             <citerefentry><refentrytitle>glXWaitGL</refentrytitle></citerefentry>,
 322             <citerefentry><refentrytitle>glXWaitX</refentrytitle></citerefentry>.
 323             <function>XCreateColormap</function>,
 324             <function>XCreateWindow</function>,
 325             <function>XSync</function>
 326         </para>
 327     </refsect1>
 328     <refsect1 id="Copyright"><title>Copyright</title>
 329         <para>
 330             Copyright <trademark class="copyright"></trademark> 1991-2006
 331             Silicon Graphics, Inc. This document is licensed under the SGI
 332             Free Software B License. For details, see
 333             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 334         </para>
 335     </refsect1>
 336 </refentry>