Solaris Handbook for Sun Frame Buffers

Creator Visuals

The built-in factory default visual for the Creator accelerator is eight-bit PseudoColor. The user can specify a different default visual using the defdepth and defclass options of Xsun(1) and the -defoverlay and -deflinear options of ffbconfig(1m).

Note -

The Creator accelerator is also called the Fast Frame Buffer (FFB). The FFB name is used in Creator software package names, loadable device pipeline module names, the configuration program, and device man pages.

When starting OpenWindows, you can specify an alternate default visual using standard OpenWindows command line options. Any of the exported visuals can be selected as the default. For example, you can select the 24-bit TrueColor visual to be the default by using the openwin defdepth 24 option (see Xsun(1)). A 24-bit default helps to reduce colormap flashing.

List of Visuals

The Creator accelerator exports eleven visuals on the X11 screen visual list. You can query these visuals using XGetVisualInfo(3) or XMatchVisualInfo(3). The linearity of a visual can be queried using XSolarisGetVisualGamma(3). The visuals are:

Note -

In the above list, a visual is non-linear (not gamma corrected) unless it is explicitly specified to be linear. Also, an 8-bit visual resides in the Creator accelerator underlay plane group unless it is explicitly specified to reside in the overlay. 24-bit visuals are always underlay.

Figure 3-1 shows how the Creator accelerator visuals relate to the pixel storage (plane groups) in the frame buffer. X, B, G, and R denote the four 8-bit channels in which pixel data can be stored. The figure shows pixel storage for Creator Series 1, 2, and 3 with extended overlay option disabled.

The B, G, and R channels can either store 8-bit pixel data (in the red channel only) or 24-bit pixel data (using all three channels). The R channel provides storage for windows of seven different visual types (the 8R visuals). The BGR channels provide storage for windows for three different visual types (the 24-bit visuals). Only one visual is provided by the X channel: 8X PseudoColor.

Figure 3-1 The 11 Creator Accelerator Visuals


The colormap_size of the underlay visuals is 256. In the Creator Series 1 and 2, the colormap_size of the overlay visual is 256 - maxwids. The Creator Series 3 can be configured to use a full 256-color overlay or to run in Series 1 or 2 compatibility mode with 25 -maxwids colors.

Overlay and Underlay Structure

The underlay 8-bit PseudoColor visual is sometimes referred to as the 8R visual because the pixel is stored in the red channel of the frame buffer. The overlay 8-bit PseudoColor visual is referred to as the 8X visual because it is stored in the X channel.

The window pixels in the overlay visual do not interfere with the window pixels in the underlay visuals. However, window pixels in the underlay visuals do interfere with window pixels in the overlay visual. This is true because underlay windows have color data which lives in the BGR (or just R) channels but they also have window id (WID) data which resides in the X channel. This can cause an x11 expose event (damage) to be generated.

When an overlay window is occluded by an underlay window, the WID portion of the underlay data will corrupt the color data of the overlay window. When the underlay window is moved away again, an x11 expose event will be sent out for the damaged portion of the overlay window. This is different from the ZX accelerator, which has mutually non-interfering underlays and overlays. Like the ZX accelerator, the pixels of Creator 8-bit underlay windows interfere with the pixels of 24-bit underlay windows.

The Creator accelerator follows an X-channel architecture. In this architecture, some pixel values in the 8X plane group display opaque colors and some codes are used as window IDs that control the display of pixels in the underlay visuals.

The Creator 3D Series 3 has an extended overlay mode that has non-interfering overlays and underlays like the ZX accelerator. When this mode is enabled, the window id planegroup no longer shares the X or overlay channel so that an underlay window will not cause an x11 expose (damage) event.

The maxwids configuration option to ffbconfig(1m) specifies how many of the overlay pixel values are to be used as hardware window IDs. See "Hardware Window IDs"" for details. The minimum legal value for maxwids is 1. The default value is 32. Thus, the overlay visual is a partial visual because it has less than the usual 256 colormap entries. For colormaps of this visual, if the client renders with a pixel value greater than or equal to the specified number of colormap entries, no error is generated and the colors displayed are undefined.

Comparison with the SX Accelerator

The visual architecture of the Creator accelerator is most similar to the CG14, the display adaptor of the SX accelerator. CG14 is also an X-channel architecture display adaptor that has 8-bit and 24-bit underlay visuals and a single 8-bit PseudoColor overlay visual. However, there are two primary differences, as described in the sections that follow.

Gamma Correction

The Creator accelerator has some visuals that are gamma-corrected and some that are not. A gamma-corrected visual is called a linear visual. The linear visuals are:

Both linear and non-linear visuals are present on the X11 screen visual list, which can be queried with XGetVisualInfo. Because linearity is not a visual property recognized by the X11 core protocol, an extended routine must be called to distinguish a linear visual from its nonlinear counterpart. This routine is XSolarisGetVisualGamma. Refer to the XSolarisGetVisualGamma(1) man page for further details.

CG14 does not have linear visuals like the Creator accelerator. It performs gamma correction using a special Gamma LUT that affects the entire screen. Thus, it is not possible on the CG14 to have both gamma-corrected and uncorrected 24-bit windows on the screen at the same time. This is possible, however, on the Creator accelerator.

Single Color LUT

CG14 has two hardware color LUTs. One is used by the 8-bit underlay visuals and the other is used by the 8-bit overlay visual. In contrast, the Creator accelerator Series 1 and 2 have only one hardware color LUT. This means that an overlay window on the Creator accelerator will colormap flash against an 8-bit underlay window unless precautions are taken to make sure that the colormaps of the two windows use the same colors in the same pixel locations. Creator series 3 has four hardware color LUTs whose allocation and sharing is managed by the Xserver.

When programming for the case where there is only one color LUT on a Creator accelerator, take precautions to share overlay and underlay colors on transparent overlay applications. Since the overlay visual is always a different visual from the underlay visual, a transparent overlay application always requires at least two separate colormaps: one for the overlay and one for the underlay. The overlay window is usually a child of the underlay window and the pixels are correlated (i.e., spatially congruent) by the application. In this situation, when the mouse pointer is inside the boundary of the underlay and overlay window pair, the overlay colormap will be installed in the hardware CLUT and the underlay colormap will not be installed. Thus, take care to ensure that underlay pixels display the correct colors when viewed through the overlay colormap. This can be done by allocating colors in the same position in both the underlay and overlay colormaps.

Comparing Creator with the ZX Accelerator

Unlike the ZX accelerator, the built-in factory default visual on the Creator accelerator is not an overlay. On the ZX accelerator, the default visual is the overlay 8-bit PseudoColor visual. But on the Creator accelerator, like the SX accelerator, it is the 8-bit underlay PseudoColor visual. Thus, if you want to create applications with pop-up windows that are non-damaging with underlay windows, you cannot simply use the default visual. Instead, applications should call XSolarisOvlSelectBestOverlay to find a non-damaging overlay visual. Refer to the Solaris documentation on the OVL extension to X.

Note -

XSolarisOvlSelectBestOverlay was first introduced in Solaris 2.4. If an application needs to run on Solaris 2.3 or earlier as well as on Solaris 2.4, define the external reference to this function as #pragma weak. The program can then check the value of this symbol. If this symbol has the value of 0, then the program is running on Solaris 2.3 or earlier. In this case, XSolarisOvlSelectBestOverlay cannot be called to find the overlay visual. Instead, the application can use XGetVisualInfo to find the first 8-bit visual with less than 256 colormap entries. However, this technique is specific to the Creator accelerator and is not portable to other devices.

Window Manager Implications

Because the Creator accelerator default visual is not an overlay, problems occur when overlay windows are not override-redirect (i.e., wrapped with a window manager decoration window). The Solaris-supported window managers olwm, mwm, and dtwm always wrap toolkit subwindows with decoration windows in the default visual. This occurs even if an application specifies a non-default visual for the pop-up window.

For example, when the default visual is 8-bit underlay PseudoColor, the window manager will wrap it with an 8-bit underlay decoration window even if an application specifies to a toolkit that a pop-up window is to be placed in the 8-bit overlay PseudoColor visual. Thus, the pop-up continues to damage other underlay windows, which is not the intended effect.

Use the following workarounds to this limitation:

Keep in mind that the overlay visual has less colormap entries than the underlay 8-bit visual. Thus, the default colormap may fill up sooner, which may lead to increased colormap flashing.