GLXINTRO() MachTen Programmer’s Manual GLXINTRO()

NAME
glXIntro - Introduction to OpenGL in the X window system

OVERVIEW
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 glXQueryExtension and glX-
QueryVersion.

GLX extended servers make a subset of their visuals avail-
able for OpenGL rendering. Drawables created with these
visuals can also be rendered using the core X renderer and
with the renderer of any other X extension that is compat-
ible with all core X visuals.

GLX extends drawables with several buffers other than the
standard color buffer. These buffers include back and
auxiliary color buffers, a depth buffer, a stencil buffer,
and a color accumulation buffer. Some or all are included
in each X visual that supports OpenGL.

To render using OpenGL into an X drawable, you must first
choose a visual that defines the required OpenGL buffers.
glXChooseVisual can be used to simplify selecting a com-
patible visual. If more control of the selection process
is required, use XGetVisualInfo and glXGetConfig to select
among all the available visuals.

Use the selected visual to create both a GLX context and
an X drawable. GLX contexts are created with glXCreate-
Context, and drawables are created with either XCreateWin-
dow or glXCreateGLXPixmap. Finally, bind the context and
the drawable together using glXMakeCurrent. This con-
text/drawable pair becomes the current context and current
drawable, and it is used by all OpenGL commands until glX-
MakeCurrent is called with different arguments.

Both core X and OpenGL commands can be used to operate on
the current drawable. The X and OpenGL command streams
are not synchronized, however, except at explicitly cre-
ated boundaries generated by calling glXWaitGL, glXWaitX,
XSync, and glFlush.

EXAMPLES
Below is the minimum code required to create an RGBA-
format, X window that’s compatible with OpenGL and to
clear it to yellow. The code is correct, but it does not
include any error checking. Return values dpy, vi, cx,
cmap, and win should all be tested.

#include <GL/glx.h> #include <GL/gl.h> #include <unistd.h>

static int attributeListSgl[] = { GLX_RGBA,
GLX_RED_SIZE, 1, /*get the deepest buffer with 1
red bit*/ GLX_GREEN_SIZE, 1, GLX_BLUE_SIZE, 1,
None };

static int attributeListDbl[] = { GLX_RGBA,
GLX_DOUBLE_BUFFER, /*In case single buffering is not
supported*/ GLX_RED_SIZE, 1, GLX_GREEN_SIZE,
1, GLX_BLUE_SIZE, 1, None };

static Bool WaitForNotify(Display *d, XEvent *e, char
*arg) {
return (e->type == MapNotify) && (e->xmap.window ==
(Window)arg); }

int main(int argc, char **argv) {
Display *dpy;
XVisualInfo *vi;
Colormap cmap;
XSetWindowAttributes swa;
Window win;
GLXContext cx;
XEvent event;
int swap_flag = FALSE;

/* get a connection */
dpy = XOpenDisplay(0);

/* get an appropriate visual */
vi = glXChooseVisual(dpy, DefaultScreen(dpy),
attributeListSgl);
if (vi == NULL) {
vi = glXChooseVisual(dpy, DefaultScreen(dpy),
attributeListDbl);
swap_flag = TRUE;
}

/* create a GLX context */
cx = glXCreateContext(dpy, vi, 0, GL_TRUE);

/* create a color map */
cmap = XCreateColormap(dpy, RootWindow(dpy,
vi->screen), vi->visual, AllocNone);

/* create a window */
swa.colormap = cmap;
swa.border_pixel = 0;
swa.event_mask = StructureNotifyMask;
win = XCreateWindow(dpy, RootWindow(dpy, vi->screen),
0, 0, 100, 100,
0, vi->depth, InputOutput,
vi->visual,
CWBorder-
Pixel|CWColormap|CWEventMask, &swa);
XMapWindow(dpy, win);
XIfEvent(dpy, &event, WaitForNotify, (char*)win);

/* connect the context to the window */
glXMakeCurrent(dpy, win, cx);

/* clear the buffer */
glClearColor(1,1,0,1);
glClear(GL_COLOR_BUFFER_BIT);
glFlush();
if (swap_flag) glXSwapBuffers(dpy,win);

/* wait a while */
sleep(10); }

NOTES
A color map must be created and passed to XCreateWindow.
See the preceding example code.

A GLX context must be created and attached to an X draw-
able before OpenGL commands can be executed. OpenGL com-
mands issued while no context/drawable pair is current
result in undefined behavior.

Exposure events indicate that all 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.

GLX commands manipulate XVisualInfo structures rather than
pointers to visuals or visual IDs. XVisualInfo structures
contain visual, visualID, screen, and depth elements, as
well as other X-specific information.

USING GLX EXTENSIONS
All supported GLX extensions will have a corresponding
definition in glx.h and a token in the extension string
returned by glXQueryExtensionsString. For example, if the
EXT_visual_info extension is supported, then this token
will be defined in glx.h and EXT_visual_info will appear
in the extension string returned by glXQueryExtension-
sString. The definitions in glx.h can be used at compile
time to determine if procedure calls corresponding to an
extension exist in the library.

OpenGL itself has also been extended. Refer to glIntro for
more information.

GLX 1.1 and GLX 1.2
GLX 1.2 is now supported. It is backward compatible with
GLX 1.1 and GLX 1.0.

GLX 1.2 corresponds to OpenGL version 1.1 and introduces
the following new call: glGetCurrentDisplay.

GLX 1.1 corresponds to OpenGL version 1.0 and introduces
the following new calls: glXQueryExtensionsString, glX-
QueryServerString, and glXGetClientString.

Call glQueryVersion to determine at runtime what version
of GLX is available. glQueryVersion returns the version
that is supported on the connection. Thus if 1.2 is
returned, both the client and server support GLX 1.2. 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 and GLX_VERSION_1_2 will be defined if GLX
1.2 calls are supported.

SEE ALSO
glIntro, glFinish, glFlush, glXChooseVisual, glXCopyCon-
text,
glXCreateContext, glXCreateGLXPixmap, glXDestroyContext,
glXGetClientString, glXGetConfig, glXIsDirect, glXMakeCur-
rent,
glXQueryExtension, glXQueryExtensionsString, glXQuery-
ServerString, glXQueryVersion, glXSwapBuffers, glXUseX-
Font, glXWaitGL, glXWaitX, XCreateColormap, XCreateWindow,
XSync

MachTen 4