Restrictions on Using Enhanced X-Windows Calls with GL Subroutines

Some GL and Enhanced X-Windows calls cannot be used together. Only a few routines make sense and are valid, while all others result in undefined behavior.

As mentioned previously, the GL subroutine library is partitioned into two pieces: one, of which the X server remains ignorant, and the second, which operates through Enhanced X-Windows. Due to this partitioning, certain Enhanced X-Windows calls, when invoked with GL calls, result in unpredictable behavior. For this reason, do not use these calls together. The following sections outline restrictions on calls:

• Rendering Models
• Color Maps
• Fonts
• Internal Properties
• Fullscreen Mode
• Coordinate Transformation
• Mixed GL and Windows Input

List of GL Enhanced X-Windows Subroutines

Rendering Models

Enhanced X-Windows calls should not be used to render into a GL window, and GL calls should not be used to render into an Enhanced X-Windows window. The X server is ignorant of the state of a GL window, and the GL subroutines are not aware of Enhanced X-Windows. If rendering into the other type of window is attempted, the most likely outcome is that anything drawn appears either in the wrong colors or the wrong place, or does not appear at all. In some situations, the application exits prematurely.

The previous restrictions do not imply that you cannot do Enhanced X-Windows and GL drawing within the same process, only that you should not use both rendering models to draw into the same window. As long as Enhanced X-Windows drawing is limited to Enhanced X-Windows windows, and GL drawing is limited to GL windows, there should be no conflicts.

The following is a partial list of Enhanced X-Windows and AIX drawing routines. Do not use these routines to draw inside a GL window.

Do not use GL subroutines on an Enhanced X-Windows window unless that window has first been converted to a GL window with the winX subroutine.

Color Maps

The AIXwindows window manager does not always install a new colormap immediately. Usually, colormaps are installed only when the input focus changes. This problem can affect color index mode windows, as well as RGB mode windows on the POWERgraphics GTO, POWER Gt4, and POWER Gt4x adapters.

Although the X server performs overall color map management, including color map creation, allocation, and installation, do not use Enhanced X-Windows calls to change the GL color map, or GL calls to change X color maps.

Internally, GL maintains two color maps. One is the global color-index-mode color map, and it can be modified by any GL application. The other color map is an internal color map maintained for PseudoRGB graphics adapters. For 8-bit adapters, this internal palette is loaded with a 3-3-2 dithered color map. On 24-bit adapters, this palette is loaded with an 8-8-8 straight ramp. The actual format of either of these two color maps depends on which adapter is installed in your system. Modifying either of these color maps results in unpredictable colors on the screen.

The following is a partial list of Enhanced X-Windows color map manipulation routines. Do not use these routines to modify GL color maps.

Fonts

Do not use Enhanced X-Windows fonts calls to load a GL font. If you wish to use Enhanced X-Windows fonts with the GL charstr subroutine, use the GL loadXfont subroutine to access them. The following Enhanced X-Windows routines cannot be used to load a GL font and do not affect the current GL font:

• XLoadFont
• XLoadQueryFont

Likewise, do not attempt to use the GL loadXfont subroutine to get a font for Enhanced X-Windows rendering.

Although the internal GL font structure is almost identical to the Enhanced X-Windows font structure, each font registered with either the loadXfont or defrasterfont subroutine associates a handle with that font. GL keeps an internal hash table of all fonts registered for the process. Xfonts need to be registered with GL to be usable by GL.

Internal Properties

GL defines several Enhanced X-Windows properties that are used internally. If these properties are changed or destroyed, unpredictable behavior results. Therefore, use the following routines with caution:

• XChangeProperty
• XDeleteProperty

Widgets

The GL widget is not properly created and initialized if it is created with the XtCreateManagedWidget subroutine. To properly create and initialize the GL widget, use the XtCreateWidget subroutine and subsequently manage the widget with the XtManageChild subroutine.

Fullscreen Mode

In the current implementation of the GL fullscrn subroutine, the pointer is grabbed so that all input is redirected to the process that has called the fullscrn subroutine. Ungrabbing the pointer prematurely causes unpredictable results. Performing any other grabs or ungrabs can also cause unpredictable results within a fullscrn/endfullscrn subroutine pair.

The following Enhanced X-Windows functions interfere with GL fullscreen mode. Do not use these routines when GL is in fullscreen mode.

Coordinate Transformation

GL and Enhanced X-Windows have different coordinate mappings. The GL window origin is in the lower left and the Enhanced X-Windows window origin is in the upper left. Do not use the XTranslateCoordinates subroutine, an Enhanced X-Windows function, to manipulate GL coordinate data.

Likewise, do not use GL matrix and viewport manipulation routines on Enhanced X-Windows windows.

Mixed GL and Windows Input

Currently, programming that combines GL input queue handling routines (such as qread and qtest) with X input queue handling routines (such as XNextEvent and XCheckIfEvent ) on the same display connection is not recommended. X and GL input can be combined provided that such input is obtained through separate sockets.

Although you can use the Enhanced X-Windows event mechanism to obtain Enhanced X-Windows events for a GL window, do not try to use the GL event mechanism to obtain events for some GL windows and the Enhanced X-Windows event mechanism to obtain events for other GL windows.

The GL event queue is fed by events returning from the X server; the GL event handling library simply converts events from X format into GL format. The mapping is not one-to-one; sometimes multiple X events translate into only on GL event; sometimes multiple GL events are generated from one X event. If an unrecognized or unexpected event is encountered, it is discarded. Thus, changing the event mask for the GL connection, removing X events from the GL connection, or sending events to the GL connection results in the unpredictable or inconsistent operation of the GL input queue handling routines. It is for this reason that X and GL event routines should not be combined on the same display connection.

In the current implementation, when a qtest or qread subroutine call is made, all pending events for the process are retrieved from the X server and placed in an internal device queue. As a result, the GL and the Enhanced X-Windows event queues are no longer synchronized; that is, the arrival order of events is not preserved. Events retrieved by freely mixing calls to the GL qread subroutines and calls to the Enhanced X-Windows event processing routines are not guaranteed to be in chronological order.

In the current implementation, the GL qenter subroutine performs an XSendEvent subroutine call, and thus writes to the Enhanced X-Windows event queue.

The following is a partial list of Enhanced X-Windows functions that, if used in conjunction with the GL input queue, lead to asynchronous event delivery. Do not use these routines in conjunction with the GL input queue.

Example Programs

Example programs showing the usage of the getXdpy, getXwid, and winX subroutines can be found in the /usr/lpp/GL/examples directory.