Programming With X Visuals for the Solaris OpenGL Software

OpenGL rendering is supported on a subset of the visuals exported by the Solaris X window server on the Creator and Creator3D workstations. Because GLX overloads the core X visual classes with a set of attributes that indicate frame buffer capabilities, such as double buffer mode or stereo capabilities, the number of visuals supported by an OpenGL-capable X server is potentially large. For example, for the 24-bit TrueColor visual, the Solaris X window server on the Creator and Creator3D workstations exports the following types of GLX visuals: double buffer, single buffer, monoscopic, and stereoscopic.

This approach of exporting multiple GLX visuals for each X protocol core visual is colloquially referred to as the GLX expansion (or visual explosion). For each different type of GLX visual that is exported, there is a corresponding X protocol core visual. Thus, there are multiple GLX visuals whose core X visual attributes are all identical.

---

Note - Solaris OpenGL 1.1 does not support windows with backing store. Enabling backing store on a window will penalize the user's Creator3D rendering performance.

---

Various OpenGL-capable visuals are supported in various releases of the Solaris operating environment. These are the visuals that an OpenGL program can use. This information applies to both Creator3D and Creator systems.

• In the Solaris 2.5.1 release, there are no expanded visuals. Expanded visuals are not supported in this release.
• In Solaris 2.5.1-based systems, expanded visuals are disabled by default. The user will have the option of enabling or disabling expanded visuals by using the command ffbconfig -expvis <enable|disable>.

See Table 4-1 and Table 4-2 for detailed information on using OpenGL with or without expanded visuals.

---

Note - In Solaris 2.5.1-based systems, an OpenGL-capable overlay visual is present only if you run /usr/sbin/ffbconfig -sov enable before the Window system is started. You must run this command as root.

---

The advantage to the overloading of X visuals is that the X server can be specific about the frame buffer configurations that the graphics hardware provides. This approach also enables the OpenGL implementation to better manage resources. Instead of allocating the maximal amount of resources for each window, the OpenGL implementation only needs to allocate the resources necessary for the GLX visual the application has selected. Thus, the application has more direct control over resource allocation.

Using the glXGetConfig(3gl) and glXChooseVisual(3gl) routines, applications can get information on the supported visuals and choose the appropriate visual. For helpful information on GLX programming, refer to OpenGL Programming for X Windows Systems by Mark Kilgard and OpenGL Programming Guide.

Table 4-1 lists OpenGL-capable visuals with expanded visuals.

Table 4-1

Double Buffer Capable?	GLX BufferSize	X Visual Class	GL_RGBA	Gamma Corrected?	GLX Level
Yes	24	TrueColor	True	No	0
Yes	24	TrueColor	True	Yes	0
Yes	24	DirectColor	True	No	0
Yes	8	PseudoColor	False	No	0
No	24	TrueColor	True	No	0
No	24	TrueColor	True	Yes	0
No	24	DirectColor	True	No	0
No	8	PseudoColor	False	No	0
No	8	PseudoColor	False	No	1

When the frame buffer video mode is monoscopic, only GL_MONO versions of these visuals are supported. In a stereoscopic video mode, both GL_MONO and GL_STEREO versions of these visuals are supported.

Table 4-2 lists OpenGL-capable visuals without expanded visuals.

Table 4-2

Double Buffer Capable?	GLX BufferSize	X Visual Class	GL_RGBA	Gamma Corrected?	GLX Level
Yes	24	TrueColor	True	No	0
Yes	24	TrueColor	True	Yes	0
Yes	24	DirectColor	True	No	0
Yes	8	PseudoColor	False	No	0
No	8	PseudoColor	False	No	1

Colormap Flashing for OpenGL Indexed Applications

With the visuals exploded, there is greater potential for colormap flashing to occur for OpenGL indexed applications. This is because applications are forced to create private colormaps in order to create windows on the GLX visual they choose. In the Solaris 2.6 release, the colormap flashing problem is eased by the colormap equivalence feature. This feature allows OpenGL color indexed applications to be written in a way that creates less flashing.

Colormap equivalence allows a program to assign a colormap of one visual to a window that was created with a different visual, as long as the two visuals are colormap equivalent. This means, in general, that they share the same plane group and have the same number of colormap entries. The standard X11 protocol does not let programs mix visuals of colormaps and windows in this way. For more information on colormap equivalence, see the XSolarisCheckColormapEquivalence(3) man page.

Colormap equivalence is useful for OpenGL programs because the GLX visual expansion creates up to four different variants of each base GL_CAPABLE visual. So, for example, instead of one 8-bit default PseudoColor colormap, there may be a double-buffered variant, a stereo variant, and so on. Without colormap equivalence, an application cannot assign the default colormap to windows of these variant visuals, and this will result in more colormap flashing. With colormap equivalence, windows of all variants can share a colormap that was created using the base visual, and less colormap flashing will occur.

GL Rendering Model and X Visual Class

OpenGL RGBA rendering is supported on the 24-bit TrueColor and DirectColor visuals. OpenGL indexed rendering is supported on the 8-bit PseudoColor visuals and on the indexed or 224-color overlay visuals.

Depth Buffer

All GL-capable visuals, except for overlay visuals, have a 28-bit Z buffer (GLX_DEPTH_SIZE == 28).

Accumulation Buffer

All GL RGBA visuals have a (16, 16, 16, 16) accumulation buffer

(GLX_ACCUM_RED_SIZE == GLX_ACCUM_GREEN_SIZE==
GLX_ACCUM_BLUE_SIZE == GLX_ACCUM_ALPHA_SIZE = 16).

Stencil Buffer

All GL capable visuals, except for the overlay and stereo visuals, have a 4-bit stencil buffer (GLX_STENCIL_SIZE == 4).

Auxiliary Buffers

Auxiliary buffers are not supported by the Solaris OpenGL product (GLX_AUX_BUFFERS == 0).

Stereo

---

Note - This section is specific to Creator and Creator3D systems.

---

To run a stereo application in stereo mode, the frame buffer must be configured for stereo operation.

· To Set Up the Frame Buffer for Stereo Operation:

1. Exit the window system.

2. Type this command:

   For Solaris 2.5.1 HW297 /usr/sbin/ffbconfig -res stereo -expvis enable

   For Solaris 2.6 /usr/sbin/ffbconfig -res stereo Note that in the Solaris 2.6 release, this command must be run under superuser permissions or sys admin permissions.

3. Restart the window system.

Application can now use the stereo hardware buffers.

Rendering to DirectColor Visuals

The OpenGL API has no support for color mapping. The only way to get a DirectColor visual is to implement visual selection in the application using XGetVisualInfo(3gl) and glXGetConfig. If you request a visual with glXChooseVisual, you will get a 24-bit TrueColor visual for RGBA rendering and an 8-bit PseudoColor visual for index rendering.

When rendering to DirectColor visuals, the GL system calculates pixel values in the same way as it does for TrueColor visuals. The application is responsible for loading the window colormap with cells that make sense to the application.

Overlays

The Creator and Creator3D systems have one 8-bit overlay visual in monoscopic mode and two 8-bit overlays in stereo mode. The overlay visual GLX level is greater than zero (GLX_LEVEL > 0). Visuals with a GLX level less than or equal to zero are underlay visuals.

Server Overlay Visual (SOV) Convention

Server Overlay Visual (SOV) is an API for rendering transparent pixels in an overlay window. A transparent pixel is a special pixel code that allows the contents of underlay windows underneath to show through. SOV derives its name from the X property that informs the user of the special transparent pixel value: SERVER_OVERLAY_VISUALS. This value can be used as the input value to glIndex* calls so that the transparent pixel can be rendered into the overlay.

The SOV API, while not an X11 standard, is a convention that is supported by many X11 vendors. It is described at length in the book OpenGL Programming for the X Window System by Mark J. Kilgard. This section describes Sun-specific aspects of the SOV implementation.

---

Note - In this section, the term underlay is used as a synonym for the normal planes referred to in OpenGL Programming for the X Window System.

---

The SERVER_OVERLAY_VISUALS property describes visuals with transparent pixels (TransparentType = TransparentPixel), and also completely opaque visuals (TransparentType = None). If you need an overlay visual with a

transparent pixel, make sure that you check the TransparentType field of the entries in this property. The remainder of this section will discuss only the TransparentPixel SOV visuals.

Enabling SOV Visuals

SOV visuals are present by default in Solaris 2.6. But in Solaris 2.5.1 HW297, they must be explicitly enabled. SOV visuals can be enabled in an OpenWindows environment by becoming root, then typing the following command before starting the OpenWindows^TM system: /usr/sbin/ffbconfig -sov enable. Then restart the Window system.

Both Creator and Creator3D platforms support SOV visuals. When these devices are configured for a monoscopic video mode, there is one TransparentPixel SOV visual. When in a stereoscopic video mode, there are two TransparentPixel SOV visuals exported: a monoscopic visual and a stereoscopic visual.

---

Note - Regardless of the video mode, there is always one overlay visual exported on these devices that is not SOV-capable. This visual is provided in order to support OVL, the Sun-specific overlay extension. This visual is not GL_CAPABLE and is never returned by glXChooseVisuals.

---

OpenGL Restrictions on SOV

---

Note - Creator and Creator3D systems do not directly support SOV, so the Solaris OpenGL 1.1 software provides the SOV support using a low-overhead software translation mechanism. If a program follows the restrictions described below, this mechanism provides rendering to SOV windows at full hardware speeds in most cases.

---

SOV is fully supported on SOV-capable visuals except for the following features, which are not supported:

• Uncorrelated window configurations. These window configurations are described below.
• Read back of transparent pixels via glReadPixels.
• Interframebuffer copies of transparent pixels via glCopyPixels.

• Logic operations other than GL_COPY.
• Index masks other than 0xff.
• glShadeModel (GL_SMOOTH.

If one of these unsupported features is used, rendering will complete without generating an error but the visual results will be undefined.

A correlated window configuration is a combination of an overlay and an underlay window that are the exact same size and shape. Typically, the overlay window is a child of the underlay window, but it may also be a sibling. In either case, there must be no other windows (mapped or unmapped) intervening between them. Once the window configuration is set up, it should not be changed by re-parenting one of the windows. If a window configuration doesn't meet this definition, then it is called an uncorrelated configuration and is not supported by OpenGL.

The application is responsible for maintaining the correlated relationship. The system does not maintain it automatically. The client must check for underlay window shape changes and if any occur, it must perform the equivalent changes on the overlay window.

Compatibility of SOV with other Overlay Models

Programs that use SOV visuals may coexist on the same screen with programs that use OVL, the Sun-specific overlay extension. But the two may not be used simultaneously with the same window.

Some XGL^TM and OpenGL 1.0 programs are written to use the SOV transparent pixel if the SOV property is present, and to use XOR rendering in the default underlay visual if the SOV property is not present. These programs may not behave properly when the SOV property is present. When the SOV property is not present and the underlay is being used, a program may simply attach the default colormap to the default visual underlay window. In the presence of the SOV visual, the program will switch to using the SOV overlay visual but may continue to use the default colormap. Since the SOV overlay visual is usually not the same as the default visual, this will result in an X11 BadMatch error when the program attempts to attach the colormap to the overlay window. Care should be taken to write programs that always attach colormaps of the

proper visual to overlay windows. In this case, the program should have created a colormap using the SOV visual instead of trying to use the default colormap.

Programs that use SOV can also coexist with programs using the Sun visual overlay capability glXGetTransparentIndexSUN. However, glXGetTransparentIndexSUN is deprecated. It is provided only for compatability for existing programs that use it. Newly written transparent overlay programs should use SERVER_OVERLAY_VISUALS instead.

For information on using the Sun visual overlay capability, see the glXGetTransparentIndexSUN man page. In addition, look at the overlay example programs included in the SUNWglut package. These programs are installed by default into the directory /opt/SUNWsdk/sdk_2.5/GL/contrib/examples/sun/overlay.

Gamma Correction

On Creator and Creator3D workstations, two 24-bit TrueColor visuals are exported. One is gamma corrected; the other is not. To support imaging and Xlib applications, the nonlinear (not gamma-corrected) visuals are listed before linear visuals. However, to provide linear visuals for graphics applications running under the Solaris OpenGL software, the glXChooseVisual() call was modified to return a linear visual.

If you want to use a nonlinear TrueColor visual, you need to get the visual list from Xlib. Use the Solaris API XSolarisGetVisualGamma(3) to query the linearity of the visual. To determine whether a visual supports OpenGL, call glXGetConfig with attrib set to GLX_USE_GL.

If you are using another vendor's OpenGL and displaying your application on a Creator or Creator3D graphics workstation, and you want to use a linear visual, run the command /usr/sbin/ffbconfig -linearorder first to change the order of visuals so that the linear (gamma-corrected) visual is the first visual in the visual list. See Solaris X Window System Developer's Guide for more information on gamma correction and XSolarisGetVisualGamma.