+++ /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>
HCoop / clinton / guile-figl.git / blobdiff