X Windows Capabilities

This section describes the steps involved in setting up an IVL program in the X environment. It then describes some of the IVL-specific steps in more detail. Finally, it describes other, optional capabilities of IVL in an X environment.

Setting Up an X/IVL Program

There are nine main steps for setting up an IVL application. They are listed below. (Note that it is good programming practice to check the return value from these functions and respond to any errors.)

Open a connection The first step is to call XOpenDisplay to establish a connection to the X server. This sets up the communication link to the X server.
Check for the GLX extension You can then call glXQueryExtension to ensure that the GLX extension is present.
Select a visual type Now select an appropriate X visual. The easiest method is to call glXChooseVisual, but you could also implement your own algorithm with calls to XGetVisualInfo and glXGetConfig.
Create a window Once you have decided which visual type to use, you need to create a window. One straightforward way of doing this is to set the necessary window attributes and call XCreateWindow. You may also want to set the standard properties for the window, such as the window name, the icon name, and so on. If you select a visual type that is different from the parent window's visual type and has a read/write color map, you should create the color map prior to creating the window and make sure that it is properly initialized.
Create a rendering context The next step is to call glXCreateContext to create a rendering context that matches the visual type of your window. The resulting rendering context will hold the state values necessary for rendering.
Make the window and rendering context current By calling glXMakeCurrent, you can establish both the current drawable and the current rendering context. This routine will generate an error if the visual type of the drawable does not match the visual type for which the rendering context was created. Note: using glXMakeCurrent for each image frame will reduce application performance.
Initialize rendering state If you need to set any IVL state values to something other than their default values, you would probably want to call an initialization routine prior to falling into your main event processing loop. IVL state attributes are designed to have reasonable defaults, so you probably will not need to initialize too many values.
Map the window This step finally makes the window visible. Because of the previous steps, the window is ready for IVL rendering as soon as you call XMapWindow. There is a finite delay between the time you issue the map window command and the time the window appears on the screen. If you issue rendering commands during this period, they will not show up on the window when it becomes visible. Consequently, it is usually wise to wait until after the first Expose event, indicating that the window is actually visible on the screen.
Main event loop At this point, your X program will typically enter an event loop that waits for events (for example: expose, input, resize) to occur and then processes them. The XNextEvent call is the "wait for event" operation.

See the sample code provided with IVL for source code that demonstrates these steps (though not necessarily in the exact order shown above).

Selecting Visuals

Over the years, a number of frame-buffer architectures with different capabilities have been developed:

Some store three channels of data (red, green, and blue), others store only one.
Some allow pixel values to be routed through hardware lookup tables (color maps) in order to provide a level of indirection.
Some are inherently monochrome, others are polychrome.
Some are single layer, others are multi-layer (with overlay or underlay planes).

To expose these different capabilities in a portable way, the X Window System introduced the concept of a visual type. There are six visual types in X: TrueColor, DirectColor, PseudoColor, StaticColor, GrayScale, and StaticGray.

In the X environment, applications create windows (regions of the frame buffer that they can draw into) of a particular visual type. The visual type of a window defines its behavior in some important ways, and it is through this mechanism that frame buffer features are exposed and software portability is defined. To be specific, an XVisualInfo structure in X defines the visual type, screen, and depth of the window, as well as the number of bits of red, green, and blue information in a pixel. To achieve true portability, applications should work on systems that support any visual types that meet their minimum requirements.

In the X Window System environment, IVL adds attributes to the X visual type. These attributes can be queried using routines defined by the GLX extension which provides support for IVL in the X environment. All visual types that are supported are defined within the X server and are reported back to the client at connection time. Since X does not return information about the extended attributes defined by IVL, it is quite possible that an X server will report two or more visuals that look identical to the client. However, these visual types will differ in the IVL attributes they support, and the differences may be ascertained using the IVL routines provided for this purpose.

The easiest method to find a visual that meets your application's requirements is to use glXChooseVisual. This routine has its own prioritization algorithm to select the "best" visual from the list of attributes that you specify. If you wish to implement your own prioritization algorithm, use XGetVisualInfo and glXGetConfig.

IVL and Color Recovery

IVL does not support Color Recovery.

Managing Rendering Contexts

In order to render anything with IVL, you need to specify both a current rendering context and a current drawable (either a window or a GLX pixmap). The glXMakeCurrent routine accomplishes this. This routine seems a bit different from most other IVL routines in that it requires you to specify two separate pieces of state simultaneously.

The reason this routine requires you to set the drawable and the rendering context simultaneously is that the two are related. When you create a rendering context, you must specify a visual type. This tells IVL that the rendering context will be used in conjunction with drawables of that type. The glXMakeCurrent routine checks to ensure that the rendering context you specify will work with the drawable you specify. If the drawable is not a visual type that will work with the rendering context you provide, IVL generates an error.

With glXMakeCurrent, it is easy to change both the drawable and the rendering context at the same time. This is something that applications drawing into multiple windows may need to do quite often. If IVL required you to change the current rendering context and the current drawable with independent commands, there would be no way to change the current rendering context and the current drawable for use on a different visual type without generating an error.

Double-Buffering Support

In order to eliminate the flicker effect caused by clearing and redrawing an image in a visible window, IVL supports the notion of double-buffering. Visuals that support double-buffering have two drawing buffers: a front buffer and a back buffer. The front buffer is displayed while rendering is occurring in the back buffer. When rendering is completed, use glXSwapBuffers to display the rendered image. Also, remember to set the current draw buffer using glDrawBuffer.

There are three supported ways for IVL applications to perform double-buffering:

Using the double-buffering capabilities provided with IVL. See the glXSwapBuffers reference page for more information.
Using the Double-Buffering Extension to X (DBE). See the documentation in the file /usr/lib/X11/Xserver/info/screens/hp for more information.
Using the Multi-Buffering Extension to X (MBX). See the documentation in the file /usr/lib/X11/Xserver/info/screens/hp for more information. Also, please see the note below regarding use of MBX.

Please note that although MBX is supported with this release of IVL, it is not recommended. MBX has not been adopted as an industry standard, and it may become obsolete in the future. If you are currently using MBX, you should plan to migrate to one of the other double-buffering methods.

Furthermore, note that the combination of glXSwapBuffers and DBE in the same application is not supported; you must choose one or the other.

IVL and Backing Store

IVL does not support rendering into backing store.

Using Pixmaps

It is also possible to use IVL to render into off-screen memory. X pixmaps are the basis for supporting off-screen rendering. X is limited in that it does not define visual types for pixmaps. In X, pixmaps are not necessarily associated with a screen; they have a depth, but no visual type.

Since IVL extends the notion of visual types by defining additional visual attributes, the definition of a pixmap is also extended. IVL does this by defining a superset of an X pixmap, called a GLX pixmap. Unlike an X pixmap, a GLX pixmap has a visual type, so it may contain the extended visual attributes defined by IVL. In order to use a pixmap as a rendering destination, it is necessary to enable it for rendering with IVL by calling glXCreateGLXPixmap.

Once a GLX pixmap is no longer needed, deallocate it using glXDestroyGLXPixmap.

Synchronization

Using the `glFinish` Routine

For efficiency reasons, IVL contains the notion of a processing pipeline. For the most part, applications are shielded from the implementation details of this processing pipeline. However, since each stage of the pipeline takes finite time and could potentially involve some buffering, applications need a method to check that all the commands they have issued have completed.

One way to achieve this is with the glFinish routine. This routine can be quite inefficient, so use it sparingly. It requires notification from the lowest levels of the rendering system that all the commands have been processed, all state changes have been fully realized, and that everything that should be displayed is displayed. It may be necessary to use glFinish in order to synchronize IVL rendering with rendering commands from Xlib or Motif.

Using the `glFlush` Routine

Sometimes it is only necessary to tell IVL to flush any/all internal command buffers so that all commands will be sent to the display hardware for processing. Use the glFlush routine to achieve this.

This routine can be more efficient than glFinish. It does not wait until the results of all the commands are completed, but just issues commands to flush any and all buffers in the system so that all pending commands are at least queued up for processing. The results of subsequent rendering commands are guaranteed to complete in a finite amount of time after the issuing of a glFlush call.

In a system with rendering hardware that is independent of the CPU, it may be possible for the CPU to continue processing while the rendering hardware completes processing the rendering commands. Therefore, applications should call glFlush rather than glFinish whenever possible.

Note: the glFlush routine can be more efficient than glFinish, but should still be used sparingly for highest application performance.

The following routines implicitly invoke glFlush:

glXSwapBuffers causes glFlush to be called before it returns.
Query routines such as glGet and glIsEnabled are only required to flush as much of the stream as is necessary in order to return valid results. These query routines do not guarantee that all pending rendering commands will be flushed.

X Windows Capabilities

Technical documentation

» Table of Contents

» Glossary

» Index

Setting Up an X/IVL Program

Selecting Visuals

IVL and Color Recovery

Managing Rendering Contexts

Double-Buffering Support

IVL and Backing Store

Using Pixmaps

Synchronization

Using the `glFinish` Routine

Using the `glFlush` Routine

X Windows Capabilities

Technical documentation

» Table of Contents

» Glossary

» Index

Setting Up an X/IVL Program

Selecting Visuals

IVL and Color Recovery

Managing Rendering Contexts

Double-Buffering Support

IVL and Backing Store

Using Pixmaps

Synchronization

Using the glFinish Routine

Using the glFlush Routine

Using the `glFinish` Routine

Using the `glFlush` Routine