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