glXIntro(3g)

1GLXINTRO(3G)                     OpenGL Manual                    GLXINTRO(3G)
2
3
4

NAME

6       glXIntro - Introduction to OpenGL in the X window system
7

OVERVIEW

9       OpenGL (called GL in other pages) is a high-performance 3D-oriented
10       renderer. It is available in the X window system through the GLX
11       extension. To determine whether the GLX extension is supported by an X
12       server, and if so, what version is supported, call glXQueryExtension()
13       and glXQueryVersion().
14
15       GLX extended X servers make a subset of their visuals available for
16       OpenGL rendering. Drawables created with these visual can also be
17       rendered into using the core X renderer and or any other X extension
18       that is compatible with all core X visuals.
19
20       GLX extends a drawable's standard color buffer with additional buffers.
21       These buffers include back and auxiliary color buffers, a depth buffer,
22       a stencil buffer, and a color accumulation buffer. Some or all of the
23       buffers listed are included in each X visual that supports OpenGL.
24
25       GLX supports rendering into three types of drawables: windows, pixmaps,
26       and pbuffers (pixel buffers). GLX windows and pixmaps are X resources,
27       and capable of accepting core X rendering as well as OpenGL rendering.
28       GLX-pbuffers are GLX only resources and might not accept core X
29       rendering.
30
31       To render using OpenGL into a GLX drawable, you must determine the
32       appropriate GLXFBConfig that supports the rendering features your
33       application requires.  glXChooseFBConfig() returns a GLXFBConfig
34       matching the required attributes or NULL if no match is found. A
35       complete list of GLXFBConfigs supported by a server can be obtained by
36       calling glXGetFBConfigs(). Attributes of a particular GLXFBConfig can
37       be queried by calling glXGetFBConfigAttrib().
38
39       For GLX windows and pixmaps, a suitable X drawable (using either
40       XCreateWindow or XCreatePixmap, respectively) with a matching visual
41       must be created first. Call glXGetVisualFromFBConfig() to obtain the
42       necessary XVisualInfo structure for creating the X drawable. For
43       pbuffers, no underlying X drawable is required.
44
45       To create a GLX window from an X window, call glXCreateWindow().
46       Likewise, to create a GLX pixmap, call glXCreatePixmap(). Pbuffers are
47       created by calling glXCreatePbuffer(). Use glXDestroyWindow(),
48       glXDestroyPixmap(), and glXDestroyPbuffer() to release previously
49       allocated resources.
50
51       A GLX context is required to bind OpenGL rendering to a GLX resource. A
52       GLX resource and rendering context must have compatible GLXFBConfigs.
53       To create a GLX context, call glXCreateNewContext(). A context may be
54       bound to a GLX drawable by using glXMakeContextCurrent(). This
55       context/drawable pair becomes the current context and current drawable,
56       and is used by all OpenGL rendering commands until
57       glXMakeContextCurrent() is called with different arguments.
58
59       Both core X and OpenGL commands can be used to operate on drawables;
60       however, the X and OpenGL command streams are not synchronized.
61       Synchronization can be explicitly specified using by calling
62       glXWaitGL(), glXWaitX(), XSync, and XFlush.
63

EXAMPLES

65       Below is a minimal example of creating an RGBA-format X window that's
66       compatible with OpenGL using GLX 1.3 commands. The window is cleared to
67       yellow when the program runs. The program does minimal error checking;
68       all return values should be checked.
69
70           #include <stdio.h>
71           #include <stdlib.h>
72           #include <GL/gl.h>
73           #include <GL/glx.h>
74
75           int singleBufferAttributess[] = {
76               GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
77               GLX_RENDER_TYPE,   GLX_RGBA_BIT,
78               GLX_RED_SIZE,      1,   /* Request a single buffered color buffer */
79               GLX_GREEN_SIZE,    1,   /* with the maximum number of color bits  */
80               GLX_BLUE_SIZE,     1,   /* for each component                     */
81               None
82           };
83
84           int doubleBufferAttributes[] = {
85               GLX_DRAWABLE_TYPE, GLX_WINDOW_BIT,
86               GLX_RENDER_TYPE,   GLX_RGBA_BIT,
87               GLX_DOUBLEBUFFER,  True,  /* Request a double-buffered color buffer with */
88               GLX_RED_SIZE,      1,     /* the maximum number of bits per component    */
89               GLX_GREEN_SIZE,    1,
90               GLX_BLUE_SIZE,     1,
91               None
92           };
93
94
95           static Bool WaitForNotify( Display *dpy, XEvent *event, XPointer arg ) {
96               return (event->type == MapNotify) && (event->xmap.window == (Window) arg);
97           }
98           int main( int argc, char *argv[] )
99           {
100               Display              *dpy;
101               Window                xWin;
102               XEvent                event;
103               XVisualInfo          *vInfo;
104               XSetWindowAttributes  swa;
105               GLXFBConfig          *fbConfigs;
106               GLXContext            context;
107               GLXWindow             glxWin;
108               int                   swaMask;
109               int                   numReturned;
110               int                   swapFlag = True;
111
112               /* Open a connection to the X server */
113               dpy = XOpenDisplay( NULL );
114               if ( dpy == NULL ) {
115                   printf( "Unable to open a connection to the X server\n" );
116                   exit( EXIT_FAILURE );
117               }
118
119               /* Request a suitable framebuffer configuration - try for a double
120               ** buffered configuration first */
121               fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
122                                              doubleBufferAttributes, &numReturned );
123
124               if ( fbConfigs == NULL ) {  /* no double buffered configs available */
125                 fbConfigs = glXChooseFBConfig( dpy, DefaultScreen(dpy),
126                                                singleBufferAttributess, &numReturned );
127                 swapFlag = False;
128               }
129
130               /* Create an X colormap and window with a visual matching the first
131               ** returned framebuffer config */
132               vInfo = glXGetVisualFromFBConfig( dpy, fbConfigs[0] );
133
134               swa.border_pixel = 0;
135               swa.event_mask = StructureNotifyMask;
136               swa.colormap = XCreateColormap( dpy, RootWindow(dpy, vInfo->screen),
137                                               vInfo->visual, AllocNone );
138
139               swaMask = CWBorderPixel | CWColormap | CWEventMask;
140
141               xWin = XCreateWindow( dpy, RootWindow(dpy, vInfo->screen), 0, 0, 256, 256,
142                                     0, vInfo->depth, InputOutput, vInfo->visual,
143                                     swaMask, &swa );
144
145               /* Create a GLX context for OpenGL rendering */
146               context = glXCreateNewContext( dpy, fbConfigs[0], GLX_RGBA_TYPE,
147                                NULL, True );
148
149               /* Create a GLX window to associate the frame buffer configuration
150               ** with the created X window */
151               glxWin = glXCreateWindow( dpy, fbConfigs[0], xWin, NULL );
152
153               /* Map the window to the screen, and wait for it to appear */
154               XMapWindow( dpy, xWin );
155               XIfEvent( dpy, &event, WaitForNotify, (XPointer) xWin );
156
157               /* Bind the GLX context to the Window */
158               glXMakeContextCurrent( dpy, glxWin, glxWin, context );
159
160               /* OpenGL rendering ... */
161               glClearColor( 1.0, 1.0, 0.0, 1.0 );
162               glClear( GL_COLOR_BUFFER_BIT );
163
164               glFlush();
165
166               if ( swapFlag )
167                   glXSwapBuffers( dpy, glxWin );
168
169               sleep( 10 );
170               exit( EXIT_SUCCESS );
171           }
172
173

NOTES

175       An X color map must be created and passed to XCreateWindow.
176
177       A GLX context must be created and bound to a GLX drawable before OpenGL
178       commands can be executed. OpenGL commands executed while no
179       context/drawable pair is current result in undefined behavior.
180
181       Exposure events indicate that all buffers associated with the specified
182       window may be damaged and should be repainted. Although certain buffers
183       of some visuals on some systems may never require repainting (the depth
184       buffer, for example), it is incorrect to write a program assuming that
185       these buffers will not be damaged.
186
187       GLX commands utilize XVisualInfo structures rather than pointers to
188       visuals or visualIDs directly. XVisualInfo structures contain visual,
189       visualID, screen, and depth elements, as well as other X-specific
190       information.
191

USING GLX EXTENSIONS

193       All supported GLX extensions will have a corresponding definition in
194       glx.h and a token in the extension string returned by
195       glXQueryExtensionsString(). For example, if the EXT_visual_info
196       extension is supported, then this token will be defined in glx.h and
197       EXT_visual_info will appear in the extension string returned by
198       glXQueryExtensionsString(). The definitions in glx.h can be used at
199       compile time to determine if procedure calls corresponding to an
200       extension exist in the library.
201
202       OpenGL itself is capable of being extended.
203

GLX 1.1, GLX 1.2, AND GLX 1.3

205       GLX 1.3 is now supported and is backward compatible with GLX 1.1 and
206       GLX 1.2. It introduces new functionality (namely GLXFBConfigs) that
207       supersedes the GLX 1.2 functionality. GLX 1.2 commands are supported,
208       but their use in new application development is not recommended.
209
210       GLX 1.3 corresponds to OpenGL versions 1.2 and introduces the following
211       new calls: glXGetFBConfigs(), glXGetFBConfigAttrib(),
212       glXGetVisualFromFBConfig(), glXCreateWindow(), glXDestroyWindow(),
213       glXCreatePixmap(), glXDestroyPixmap(), glXCreatePbuffer(),
214       glXDestroyPbuffer(), glXQueryDrawable(), glXCreateNewContext(),
215       glXMakeContextCurrent(), glXGetCurrentReadDrawable(),
216       glXGetCurrentDisplay(), glXQueryContext(), and glXSelectEvent(),
217       glXGetSelectedEvent().
218
219       GLX 1.2 corresponds to OpenGL version 1.1 and introduces the following
220       new call: glXGetCurrentDisplay().
221
222       GLX 1.1 corresponds to OpenGL version 1.0 and introduces the following
223       new calls: glXQueryExtensionsString(), glXQueryServerString(), and
224       glXGetClientString().
225
226       Call glXQueryVersion() to determine at runtime what version of GLX is
227       available.  glXQueryVersion() returns the version that is supported on
228       the connection. Thus, if 1.3 is returned, both the client and server
229       support GLX 1.3. You can also check the GLX version at compile time:
230       GLX_VERSION_1_1 will be defined in glx.h if GLX 1.1 calls are
231       supported, GLX_VERSION_1_2 will be defined if GLX 1.2 calls are
232       supported, and GLX_VERSION_1_3 will be defined if GLX 1.3 calls are
233       supported.
234

COPYRIGHT

251       Copyright © 1991-2006 Silicon Graphics, Inc. This document is licensed
252       under the SGI Free Software B License. For details, see
253       http://oss.sgi.com/projects/FreeB/.
254

AUTHORS

256       opengl.org
257
258
259
260opengl.org                        06/10/2014                      GLXINTRO(3G)