glXIntro - Introduction to OpenGL in the X window system



OVERVIEW

       OpenGL  (called  GL  in other pages) is a high-performance
       3D-oriented renderer.  It is available  in  the  X  window
       system  through  the  GLX extension.  To determine whether
       the GLX extension is supported by an X server, and if  so,
       what  version  is  supported,  call  glXQueryExtension and
       glXQueryVersion.

       GLX extended X servers make  a  subset  of  their  visuals
       available  for  OpenGL  rendering.  Drawables created with
       these visual can also be rendered into using  the  core  X
       renderer  and  or any other X extension that is compatible
       with all core X visuals.

       GLX extends a drawable's standard color buffer with  addi-
       tional  buffers.  These buffers include back and auxiliary
       color buffers, a depth buffer, a  stencil  buffer,  and  a
       color  accumulation  buffer.   Some  or all of the buffers
       listed are included in each X visual that supports OpenGL.

       GLX supports rendering into three types of drawables: win-
       dows, pixmaps and pbuffers (pixel  buffers).  GLX  windows
       and pixmaps are X resources, and capable of accepting core
       X rendering as well as OpenGL rendering.  GLX pbuffers are
       GLX only resources, and might not accept core X rendering.

       To render using OpenGL  into  a  GLX  drawable,  you  must
       determine  the  appropriate GLXFBConfig which supports the
       rendering    features    your    application     requires.
       glXChooseFBConfig   returns  a  GLXFBConfig  matching  the
       required attributes, or NULL if no match is found.  A com-
       plete  list  of  GLXFBConfigs supported by a server can be
       obtained by calling glXGetFBConfigs.  Attributes of a par-
       ticular    GLXFBConfig   can   be   queried   by   calling
       glXGetFBConfigAttrib.

       For GLX windows and pixmaps, a suitable X drawable  (using
       either  XCreateWindow or XCreatePixmap, respectively) with
       a  matching  visual   must   be   created   first.    Call
       glXGetVisualFromFBConfig  to obtain the necessary XVisual-
       Info structure for creating the X drawable.  For pbuffers,
       no underlying X drawable is required.

       To   create   a   GLX   window  from  an  X  window,  call
       glXCreateWindow.  Likewise, to create a GLX  pixmap,  call
       glXCreatePixmap.   Pbuffers   are   created   by   calling
       glXCreatePbuffer.  Use glXDestroyWindow, glXDestroyPixmap,
       and  glXDestroyPbuffer  to  release  previously  allocated
       resources.
       ified  using  by  calling  glXWaitGL, glXWaitX, XSync, and
       XFlush.



EXAMPLES

       Below is a minimal example of creating an  RGBA-format,  X
       window  that's  compatible  with OpenGL using GLX 1.3 com-
       mands.  The window is cleared to yellow when  the  program
       runs.  The program does minimal error checking; all return
       values should be checked.

       #include <stdio.h> #include <stdlib.h> #include  <GL/gl.h>
       #include <GL/glx.h>

       int singleBufferAttributess[] = {
           GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
           GLX_RENDER_TYPE,   GLX_RGBA_BIT,
           GLX_RED_SIZE,       1,    /* Request a single buffered
       color buffer */
           GLX_GREEN_SIZE,    1,   /* with the maximum number  of
       color bits  */
           GLX_BLUE_SIZE,       1,     /*   for   each  component
       */
           None };

       int doubleBufferAttributes[] = {
           GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
           GLX_RENDER_TYPE,   GLX_RGBA_BIT,
           GLX_DOUBLEBUFFER,  True,  /* Request a double-buffered
       color buffer with */
           GLX_RED_SIZE,       1,      /*  the  maximum number of
       bits per component    */
           GLX_GREEN_SIZE,    1,
           GLX_BLUE_SIZE,     1,
           None };


       static Bool WaitForNotify( Display  *dpy,  XEvent  *event,
       XPointer arg ) {
           return (event->type == MapNotify) && (event->xmap.win-
       dow == (Window) arg); }











           GLXContext            context;
           GLXWindow             glxWin;
           int                   swaMask;
           int                   numReturned;
           int                   swapFlag = True;

           /* Open a connection to the X server */
           dpy = XOpenDisplay( NULL );
           if ( dpy == NULL ) {
               printf( "Unable to open  a  connection  to  the  X
       server0 );
               exit( EXIT_FAILURE );
           }

           /*  Request a suitable framebuffer configuration - try
       for a double
           ** buffered configuration first */
           fbConfigs   =   glXChooseFBConfig(    dpy,    Default-
       Screen(dpy),
                                          doubleBufferAttributes,
       &numReturned );

           if ( fbConfigs == NULL ) {  /* no double buffered con-
       figs available */
             fbConfigs   =   glXChooseFBConfig(   dpy,   Default-
       Screen(dpy),
                                            singleBufferAttribut-
       ess, &numReturned );
             swapFlag = False;
           }

           /*  Create  an  X  colormap  and  window with a visual
       matching the first
           ** returned framebuffer config */
           vInfo = glXGetVisualFromFBConfig( dpy, fbConfigs[0] );

           swa.border_pixel = 0;
           swa.event_mask = StructureNotifyMask;
           swa.colormap  =  XCreateColormap( dpy, RootWindow(dpy,
       vInfo->screen),
                                           vInfo->visual,  Alloc-
       None );

           swaMask = CWBorderPixel | CWColormap | CWEventMask;

           xWin    =    XCreateWindow(    dpy,    RootWindow(dpy,
       vInfo->screen), 0, 0, 256, 256,
                                 0,  vInfo->depth,   InputOutput,
       vInfo->visual,
                                 swaMask, &swa );

           /* Create a GLX context for OpenGL rendering */

           /* Bind the GLX context to the Window */
           glXMakeContextCurrent( dpy, glxWin, glxWin, context );

           /* OpenGL rendering ... */
           glClearColor( 1.0, 1.0, 0.0, 1.0 );
           glClear( GL_COLOR_BUFFER_BIT );

           glFlush();

           if ( swapFlag )
               glXSwapBuffers( dpy, glxWin );

           sleep( 10 );
           exit( EXIT_SUCCESS ); }



NOTES

       An  X  color map must be created and passed to XCreateWin-
       dow.

       A GLX context must be created and bound to a GLX  drawable
       before  OpenGL  commands can be executed.  OpenGL commands
       executed while no context/drawable pair is current  result
       in undefined behavior.

       Exposure  events indicate that all buffers associated with
       the  specified  window  may  be  damaged  and  should   be
       repainted.  Although  certain  buffers  of some visuals on
       some systems  may  never  require  repainting  (the  depth
       buffer,  for  example), it is incorrect to write a program
       assuming that these buffers will not be damaged.

       GLX commands utilize XVisualInfo  structures  rather  than
       pointers  to  visuals  or visualIDs directly.  XVisualInfo
       structures contain visual,  visualID,  screen,  and  depth
       elements, as well as other X-specific information.



USING GLX EXTENSIONS

       All  supported  GLX  extensions  will have a corresponding
       definition in glx.h and a token in  the  extension  string
       returned by glXQueryExtensionsString.  For example, if the
       EXT_visual_info extension is supported,  then  this  token
       will  be  defined in glx.h and EXT_visual_info will appear
       in     the     extension      string      returned      by
       glXQueryExtensionsString.  The definitions in glx.h can be
       used at compile time to determine if procedure calls  cor-
       responding to an extension exist in the library.

       OpenGL  itself  is  capable  of  being extended.  Refer to
       glIntro for more information.
       glXQueryDrawable,                     glXCreateNewContext,
       glXMakeContextCurrent,          glXGetCurrentReadDrawable,
       glXGetCurrentDisplay,   glXQueryContext,   glXSelectEvent,
       glXGetSelectedEvent.

       GLX 1.2 corresponds to OpenGL version 1.1  and  introduced
       the following new call: glGetCurrentDisplay.

       GLX  1.1  corresponds to OpenGL version 1.0 and introduces
       the   following   new   calls:   glXQueryExtensionsString,
       glXQueryServerString, and glXGetClientString.

       Call  glQueryVersion  to determine at runtime what version
       of GLX is available. glQueryVersion  returns  the  version
       that  is  supported  on  the  connection.  Thus  if 1.3 is
       returned, both the client and server support GLX 1.3.  You
       can  also  check the GLX version at compile time: GLX_VER-
       SION_1_1 will be defined in glx.h if  GLX  1.1  calls  are
       supported,  GLX_VERSION_1_2  will  be  defined  if GLX 1.2
       calls are supported, and GLX_VERSION_1_3 will  be  defined
       if GLX 1.3 calls are supported.



SEE ALSO

       glIntro,      glFinish,      glFlush,     glXChooseVisual,
       glXCopyContext,   glXCreateContext,    glXCreateGLXPixmap,
       glXDestroyContext,    glXGetClientString,    glXGetConfig,
       glXIsDirect,      glXMakeCurrent,       glXQueryExtension,
       glXQueryExtensionsString,            glXQueryServerString,
       glXQueryVersion, glXSwapBuffers,  glXUseXFont,  glXWaitGL,
       glXWaitX,      glXGetFBConfigs,      glXGetFBConfigAttrib,
       glXGetVisualFromFBConfig,                 glXCreateWindow,
       glXDestroyWindow,    glXCreatePixmap,    glXDestroyPixmap,
       glXCreatePbuffer,   glXDestroyPbuffer,   glXQueryDrawable,
       glXCreateNewContext,                glXMakeContextCurrent,
       glXGetCurrentReadDrawable,           glXGetCurrentDisplay,
       glXQueryContext,    glXSelectEvent,   glXGetSelectedEvent.
       XCreateColormap, XCreateWindow, XSync



                                                                1