winX Subroutine

GL3.2 for AIX: Graphics Library (GL) Technical Reference

winX Subroutine

Purpose

Converts an Enhanced X-Windows window into a GL window.

Library

Graphics Library

C (libgl.a)

FORTRAN (libfgl.a)

C Syntax

short winX (Display *dpy, Window xid)

FORTRAN Syntax

INTEGER *2 FUNCTION WINX(dpy, xid)
INTEGER *4 dpy, xid

Description

The winX subroutine converts the specified Enhanced X-Windows window into a GL window. The Enhanced X-Windows window must be created with the XCreateWindow subroutine from the Enhanced X-Windows library. The Enhanced X-Windows window can be mapped before or after conversion to a GL window, and can subsequently be unmapped or remapped.

Not all possible combinations of GL and Enhanced X-Windows calls result in defined behavior, however. In particular, avoid the following usages:

Do not use Enhanced X-Windows drawing routines to draw into a GL window. The screen results are undefined. Use Enhanced X-Windows drawing routines to draw into Enhanced X-Windows only.
Use only the GL loadXfont subroutine to load X fonts for use with the GL charstr subroutine. Use the XLoadFont or XLoadQueryFont subroutine only if you plan to use X text-rendering routines to draw into an Enhanced X-Windows window.
Do not change, modify, or delete GL internal properties associated with GL windows. Doing so causes unpredictable behavior.
Do not grab or ungrab pointers, keyboards, or the server while in GL fullscreen mode. Doing so causes unpredictable behavior.
Events associated with GL windows can be obtained through the Enhanced X-Windows event queue. However, if you choose to obtain events in this manner, do not also use the GL event queue. Doing so causes unpredictable results. An application can use both the GL and Enhanced X-Windows event queues within the same executable if the GL queue is used only for GL events and the Enhanced X-Windows event queue is used only for Enhanced X-Windows events.

The previous brief restrictions are explained more fully in "Using Enhanced X-Windows Calls with GL Subroutines" in GL3.2 Version 4 for AIX: Programming Concepts.

To use the winX subroutine correctly, the Enhanced X-Windows window must have been created with the XCreateWindow subroutine. The following conditions must also be met within the XCreateWindow attributes:

The visual specified with this subroutine must be the largest available PseudoColor visual. Failure to use the largest possible PseudoColor visual results in unpredictable behavior.
The window depth must match the depth of the visual. If it does not, a BadMatch event error is generated.
The window attributes must include a color map that was created with this large visual. Specifying a color map of the wrong size causes a BadMatch event error to be generated. Failure to specify a color map that has been created with the large visual results in unpredictable behavior.
Do not use the default attributes for the border_pixel and the back_pixel attributes, because the default CopyFromParent does not have the correct visual for the border and background pixel maps. Using the incorrect border and back attributes generates a BadMatch event error. It is acceptable to specify None for these attributes. Please refer to example programs in the /usr/lpp/GL/examples directory for usage.

If only the Enhanced X-Windows ID of a GL window is needed, use the getXdpy and getXwid subroutines.

A window must be converted to a DirectAccess window (with either the winX or winopen subroutine) before any GL drawing can occur in it. DirectAccess allows the GL drawing library to write rendering commands directly, without intervening layers, to the MicroChannel address space of the graphics adapter. Thus, a Direct Access client must execute locally; that is, a GL program must execute on the machine containing the display adapter. Currently, a GL program cannot be operated over a network.

Parameters

dpy	Specifies the Enhanced X-Windows connection (as returned by the XOpenDisplay subroutine).
xid	Specifies the Enhanced X-Windows window ID (as returned by the XCreateWindow subroutine) of the window to be converted into a GL window.

Return Value

The GL window identifier.

Example

An example program showing the usage of the winX subroutine can be found in the /usr/lpp/GL/examples directory.

Implementation Specifics

This subroutine is part of GL in the AIXwindows Environment/6000 Version 1, Release 2 with AIXwindows/3D Feature.

Because the windowing design on the GXT1000 has changed from that supported on previous graphics adapters, the rules for using winX have changed. The gconfig subroutine cannot be used to change the mode (color index mode to RGB mode) of a window created with winX on the GXT1000. The X11 window must be created in advance with the appropriate visual type that is desired by the application. Choose a PseudoColor visual if color-index mode GL rendering is desired; choose a DirectColor visual if RGB mode operation is desired.

The GLC_CREATE_OVERLAY token on the glcompat subroutine modifies the operation of the winX routine.

Files

/usr/include/gl/gl.h	Contains C language constant and variable type definitions for GL.
/usr/include/gl/fgl.h	Contains FORTRAN constant and variable type definitions for GL.
/usr/include/X11/Xlib.h	Contains C language constant and variable type definitions for version X11 of Enhanced X-Windows.

Related Information

The charstr subroutine, getXdpy subroutine, getXwid subroutine, loadXfont subroutine, winopen subroutine.

The XOpenDisplay subroutine, XCreateWindow subroutine, XLoadFont subroutine, XLoadQueryFont subroutine.

Using Enhanced X-Windows Calls with GL Subroutines in GL3.2 Version 4 for AIX: Programming Concepts.