Commit | Line | Data |
---|---|---|
7faf1d71 AW |
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 <stdio.h> | |
98 | #include <stdlib.h> | |
99 | #include <GL/gl.h> | |
100 | #include <GL/glx.h> | |
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->type == MapNotify) && (event->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, &numReturned ); | |
150 | ||
151 | if ( fbConfigs == NULL ) { /* no double buffered configs available */ | |
152 | fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy), | |
153 | singleBufferAttributess, &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->screen), | |
164 | vInfo->visual, AllocNone ); | |
165 | ||
166 | swaMask = CWBorderPixel | CWColormap | CWEventMask; | |
167 | ||
168 | xWin = XCreateWindow( dpy, RootWindow(dpy, vInfo->screen), 0, 0, 256, 256, | |
169 | 0, vInfo->depth, InputOutput, vInfo->visual, | |
170 | swaMask, &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, &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> |