--- /dev/null
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "xhtml1-transitional.dtd">
+<!-- saved from url=(0013)about:internet -->
+<?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>glXIntro</title><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /></head><body><div class="refentry" lang="en" xml:lang="en"><a id="glXIntro"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>glXIntro — Introduction to OpenGL in the X window system</p></div><div class="refsect1" lang="en" xml:lang="en"><a id="overview"></a><h2>Overview</h2><p>
+ </p><p>
+ 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 <a class="citerefentry" href="glXQueryExtension.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtension</span></span></a> and
+ <a class="citerefentry" href="glXQueryVersion.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryVersion</span></span></a>.
+ </p><p>
+ 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.
+ </p><p>
+ GLX extends a drawable's standard color buffer with additional 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.
+ </p><p>
+ GLX supports rendering into three types of drawables: windows, 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.
+ </p><p>
+ To render using OpenGL into a GLX drawable, you must determine the
+ appropriate GLXFBConfig that supports the rendering features your
+ application requires. <a class="citerefentry" href="glXChooseFBConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXChooseFBConfig</span></span></a> returns a GLXFBConfig matching
+ the required attributes or <code class="constant">NULL</code> if no match is found. A complete
+ list of GLXFBConfigs supported by a server can be obtained by calling
+ <a class="citerefentry" href="glXGetFBConfigs.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigs</span></span></a>. Attributes of a particular GLXFBConfig can be
+ queried by calling <a class="citerefentry" href="glXGetFBConfigAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigAttrib</span></span></a>.
+ </p><p>
+ For GLX windows and pixmaps, a suitable X drawable (using either
+ <code class="function">XCreateWindow</code> or <code class="function">XCreatePixmap</code>, respectively) with a matching
+ visual must be created first. Call <a class="citerefentry" href="glXGetVisualFromFBConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetVisualFromFBConfig</span></span></a> to obtain
+ the necessary XVisualInfo structure for creating the X drawable. For
+ pbuffers, no underlying X drawable is required.
+ </p><p>
+ To create a GLX window from an X window, call <a class="citerefentry" href="glXCreateWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateWindow</span></span></a>.
+ Likewise, to create a GLX pixmap, call <a class="citerefentry" href="glXCreatePixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePixmap</span></span></a>. Pbuffers are
+ created by calling <a class="citerefentry" href="glXCreatePbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePbuffer</span></span></a>. Use <a class="citerefentry" href="glXDestroyWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyWindow</span></span></a>,
+ <a class="citerefentry" href="glXDestroyPixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPixmap</span></span></a>, and <a class="citerefentry" href="glXDestroyPbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPbuffer</span></span></a> to release previously
+ allocated resources.
+ </p><p>
+ A GLX context is required to bind OpenGL rendering to a GLX resource. A GLX
+ resource and rendering context must have compatible GLXFBConfigs. To create
+ a GLX context, call <a class="citerefentry" href="glXCreateNewContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateNewContext</span></span></a>. A context may be bound to a
+ GLX drawable by using <a class="citerefentry" href="glXMakeContextCurrent.xml"><span class="citerefentry"><span class="refentrytitle">glXMakeContextCurrent</span></span></a>. This context/drawable
+ pair becomes the current context and current drawable, and is used by all
+ OpenGL rendering commands until <a class="citerefentry" href="glXMakeContextCurrent.xml"><span class="citerefentry"><span class="refentrytitle">glXMakeContextCurrent</span></span></a> is called with
+ different arguments.
+ </p><p>
+ Both core X and OpenGL commands can be used to operate on drawables;
+ however, the X and OpenGL command streams are not synchronized.
+ Synchronization can be explicitly specified using by calling <a class="citerefentry" href="glXWaitGL.xml"><span class="citerefentry"><span class="refentrytitle">glXWaitGL</span></span></a>,
+ <a class="citerefentry" href="glXWaitX.xml"><span class="citerefentry"><span class="refentrytitle">glXWaitX</span></span></a>, <code class="function">XSync</code>, and <code class="function">XFlush</code>.
+ </p><p>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="examples"></a><h2>Examples</h2><p>
+ Below is a minimal example of creating an RGBA-format X window that's
+ compatible with OpenGL using GLX 1.3 commands. The window is cleared to
+ yellow when the program runs. The program does minimal error checking; all
+ return values should be checked.
+ </p><p>
+ </p><pre class="programlisting">
+#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.window == (Window) arg);
+}
+int main( int argc, char *argv[] )
+{
+ Display *dpy;
+ Window xWin;
+ XEvent event;
+ XVisualInfo *vInfo;
+ XSetWindowAttributes swa;
+ GLXFBConfig *fbConfigs;
+ 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 server\n" );
+ exit( EXIT_FAILURE );
+ }
+
+ /* Request a suitable framebuffer configuration - try for a double
+ ** buffered configuration first */
+ fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
+ doubleBufferAttributes, &numReturned );
+
+ if ( fbConfigs == NULL ) { /* no double buffered configs available */
+ fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
+ singleBufferAttributess, &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, AllocNone );
+
+ 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 */
+ context = glXCreateNewContext( dpy, fbConfigs[0], GLX_RGBA_TYPE,
+ NULL, True );
+
+ /* Create a GLX window to associate the frame buffer configuration
+ ** with the created X window */
+ glxWin = glXCreateWindow( dpy, fbConfigs[0], xWin, NULL );
+
+ /* Map the window to the screen, and wait for it to appear */
+ XMapWindow( dpy, xWin );
+ XIfEvent( dpy, &event, WaitForNotify, (XPointer) xWin );
+
+ /* 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 );
+}
+ </pre><p>
+ </p><p>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="notes"></a><h2>Notes</h2><p>
+ An X color map must be created and passed to <code class="function">XCreateWindow</code>.
+ </p><p>
+ 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.
+ </p><p>
+ Exposure events indicate that <span class="emphasis"><em>all</em></span> 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.
+ </p><p>
+ GLX commands utilize XVisualInfo structures rather than pointers to visuals
+ or visualIDs directly. XVisualInfo structures contain <span class="emphasis"><em>visual</em></span>,
+ <span class="emphasis"><em>visualID</em></span>, <span class="emphasis"><em>screen</em></span>, and <span class="emphasis"><em>depth</em></span> elements, as well as other
+ X-specific information.
+ </p><p>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="usingglxextensions"></a><h2>Using GLX Extensions</h2><p>
+ All supported GLX extensions will have a corresponding definition in glx.h
+ and a token in the extension string returned by
+ <a class="citerefentry" href="glXQueryExtensionsString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtensionsString</span></span></a>. For example, if the
+ <code class="code">EXT_visual_info</code> extension is supported, then this token will be
+ defined in glx.h and <code class="code">EXT_visual_info</code> will appear in the extension
+ string returned by <a class="citerefentry" href="glXQueryExtensionsString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtensionsString</span></span></a>. The definitions in glx.h
+ can be used at compile time to determine if procedure calls corresponding to
+ an extension exist in the library.
+ </p><p>
+ OpenGL itself is capable of being extended.
+ </p><p>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="glx11glx12andglx13"></a><h2>GLX 1.1, GLX 1.2, and GLX 1.3</h2><p>
+ GLX 1.3 is now supported and is backward compatible with GLX 1.1 and GLX
+ 1.2. It introduces new functionality (namely GLXFBConfigs) that supersedes
+ the GLX 1.2 functionality. GLX 1.2 commands are supported, but their use in
+ new application development is not recommended.
+ </p><p>
+ GLX 1.3 corresponds to OpenGL versions 1.2 and introduces the following new
+ calls: <a class="citerefentry" href="glXGetFBConfigs.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigs</span></span></a>, <a class="citerefentry" href="glXGetFBConfigAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigAttrib</span></span></a>,
+ <a class="citerefentry" href="glXGetVisualFromFBConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetVisualFromFBConfig</span></span></a>, <a class="citerefentry" href="glXCreateWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateWindow</span></span></a>, <a class="citerefentry" href="glXDestroyWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyWindow</span></span></a>,
+ <a class="citerefentry" href="glXCreatePixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePixmap</span></span></a>, <a class="citerefentry" href="glXDestroyPixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPixmap</span></span></a>, <a class="citerefentry" href="glXCreatePbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePbuffer</span></span></a>,
+ <a class="citerefentry" href="glXDestroyPbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPbuffer</span></span></a>, <a class="citerefentry" href="glXQueryDrawable.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryDrawable</span></span></a>, <a class="citerefentry" href="glXCreateNewContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateNewContext</span></span></a>,
+ <a class="citerefentry" href="glXMakeContextCurrent.xml"><span class="citerefentry"><span class="refentrytitle">glXMakeContextCurrent</span></span></a>, <a class="citerefentry" href="glXGetCurrentReadDrawable.xml"><span class="citerefentry"><span class="refentrytitle">glXGetCurrentReadDrawable</span></span></a>,
+ <a class="citerefentry" href="glXGetCurrentDisplay.xml"><span class="citerefentry"><span class="refentrytitle">glXGetCurrentDisplay</span></span></a>, <a class="citerefentry" href="glXQueryContext.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryContext</span></span></a>, and <a class="citerefentry" href="glXSelectEvent.xml"><span class="citerefentry"><span class="refentrytitle">glXSelectEvent</span></span></a>,
+ <a class="citerefentry" href="glXGetSelectedEvent.xml"><span class="citerefentry"><span class="refentrytitle">glXGetSelectedEvent</span></span></a>.
+ </p><p>
+ GLX 1.2 corresponds to OpenGL version 1.1 and introduces the following new
+ call: <a class="citerefentry" href="glXGetCurrentDisplay.xml"><span class="citerefentry"><span class="refentrytitle">glXGetCurrentDisplay</span></span></a>.
+ </p><p>
+ GLX 1.1 corresponds to OpenGL version 1.0 and introduces the following new
+ calls: <a class="citerefentry" href="glXQueryExtensionsString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtensionsString</span></span></a>, <a class="citerefentry" href="glXQueryServerString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryServerString</span></span></a>, and
+ <a class="citerefentry" href="glXGetClientString.xml"><span class="citerefentry"><span class="refentrytitle">glXGetClientString</span></span></a>.
+ </p><p>
+ Call <a class="citerefentry" href="glXQueryVersion.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryVersion</span></span></a> to determine at runtime what version of GLX is
+ available. <a class="citerefentry" href="glXQueryVersion.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryVersion</span></span></a> 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_VERSION_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.
+ </p><p>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="seealso"></a><h2>See Also</h2><p>
+ <a class="citerefentry" href="glFinish.xml"><span class="citerefentry"><span class="refentrytitle">glFinish</span></span></a>,
+ <a class="citerefentry" href="glFlush.xml"><span class="citerefentry"><span class="refentrytitle">glFlush</span></span></a>,
+ <a class="citerefentry" href="glXChooseVisual.xml"><span class="citerefentry"><span class="refentrytitle">glXChooseVisual</span></span></a>,
+ <a class="citerefentry" href="glXCopyContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCopyContext</span></span></a>,
+ <a class="citerefentry" href="glXCreateContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateContext</span></span></a>,
+ <a class="citerefentry" href="glXCreateGLXPixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateGLXPixmap</span></span></a>,
+ <a class="citerefentry" href="glXCreateNewContext.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateNewContext</span></span></a>,
+ <a class="citerefentry" href="glXCreatePbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePbuffer</span></span></a>,
+ <a class="citerefentry" href="glXCreatePixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXCreatePixmap</span></span></a>,
+ <a class="citerefentry" href="glXCreateWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXCreateWindow</span></span></a>,
+ <a class="citerefentry" href="glXDestroyContext.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyContext</span></span></a>,
+ <a class="citerefentry" href="glXDestroyPbuffer.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPbuffer</span></span></a>,
+ <a class="citerefentry" href="glXDestroyPixmap.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyPixmap</span></span></a>,
+ <a class="citerefentry" href="glXDestroyWindow.xml"><span class="citerefentry"><span class="refentrytitle">glXDestroyWindow</span></span></a>,
+ <a class="citerefentry" href="glXGetClientString.xml"><span class="citerefentry"><span class="refentrytitle">glXGetClientString</span></span></a>,
+ <a class="citerefentry" href="glXGetConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetConfig</span></span></a>,
+ <a class="citerefentry" href="glXGetCurrentDisplay.xml"><span class="citerefentry"><span class="refentrytitle">glXGetCurrentDisplay</span></span></a>,
+ <a class="citerefentry" href="glXGetCurrentReadDrawable.xml"><span class="citerefentry"><span class="refentrytitle">glXGetCurrentReadDrawable</span></span></a>,
+ <a class="citerefentry" href="glXGetFBConfigAttrib.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigAttrib</span></span></a>,
+ <a class="citerefentry" href="glXGetFBConfigs.xml"><span class="citerefentry"><span class="refentrytitle">glXGetFBConfigs</span></span></a>,
+ <a class="citerefentry" href="glXGetProcAddress.xml"><span class="citerefentry"><span class="refentrytitle">glXGetProcAddress</span></span></a>,
+ <a class="citerefentry" href="glXGetSelectedEvent.xml"><span class="citerefentry"><span class="refentrytitle">glXGetSelectedEvent</span></span></a>,
+ <a class="citerefentry" href="glXGetVisualFromFBConfig.xml"><span class="citerefentry"><span class="refentrytitle">glXGetVisualFromFBConfig</span></span></a>,
+ <a class="citerefentry" href="glXIsDirect.xml"><span class="citerefentry"><span class="refentrytitle">glXIsDirect</span></span></a>,
+ <a class="citerefentry" href="glXMakeContextCurrent.xml"><span class="citerefentry"><span class="refentrytitle">glXMakeContextCurrent</span></span></a>,
+ <a class="citerefentry" href="glXMakeCurrent.xml"><span class="citerefentry"><span class="refentrytitle">glXMakeCurrent</span></span></a>,
+ <a class="citerefentry" href="glXQueryContext.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryContext</span></span></a>,
+ <a class="citerefentry" href="glXQueryDrawable.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryDrawable</span></span></a>,
+ <a class="citerefentry" href="glXQueryExtension.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtension</span></span></a>,
+ <a class="citerefentry" href="glXQueryExtensionsString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryExtensionsString</span></span></a>,
+ <a class="citerefentry" href="glXQueryServerString.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryServerString</span></span></a>,
+ <a class="citerefentry" href="glXQueryVersion.xml"><span class="citerefentry"><span class="refentrytitle">glXQueryVersion</span></span></a>,
+ <a class="citerefentry" href="glXSelectEvent.xml"><span class="citerefentry"><span class="refentrytitle">glXSelectEvent</span></span></a>,
+ <a class="citerefentry" href="glXSwapBuffers.xml"><span class="citerefentry"><span class="refentrytitle">glXSwapBuffers</span></span></a>,
+ <a class="citerefentry" href="glXUseXFont.xml"><span class="citerefentry"><span class="refentrytitle">glXUseXFont</span></span></a>,
+ <a class="citerefentry" href="glXWaitGL.xml"><span class="citerefentry"><span class="refentrytitle">glXWaitGL</span></span></a>,
+ <a class="citerefentry" href="glXWaitX.xml"><span class="citerefentry"><span class="refentrytitle">glXWaitX</span></span></a>.
+ <code class="function">XCreateColormap</code>,
+ <code class="function">XCreateWindow</code>,
+ <code class="function">XSync</code>
+ </p></div><div class="refsect1" lang="en" xml:lang="en"><a id="Copyright"></a><h2>Copyright</h2><p>
+ Copyright <span class="trademark"></span>© 1991-2006
+ Silicon Graphics, Inc. This document is licensed under the SGI
+ Free Software B License. For details, see
+ <a class="ulink" href="http://oss.sgi.com/projects/FreeB/" target="_top">http://oss.sgi.com/projects/FreeB/</a>.
+ </p></div></div></body></html>