test

Solaris Handbook for Sun Frame Buffers

Chapter 3 The Creator Window System

This chapter describes how the Solaris(TM) X11 window system is used with the Creator and Creator 3D Graphics Accelerators.

The Creator accelerators are a high performance combination of the GX, SX, ZX, and S24 display adaptors. Like the ZX graphics accelerator, the Creator accelerator provides advanced frame buffer capabilities such as:

Like the SX accelerator, the Creator accelerator is an X-channel architecture display adaptor. See "Creator Visuals".

Like the GX accelerator, the Creator accelerator provides accelerated X11 rendering operations and hardware cursor support. See "Cursor Management".

Like the S24 accelerator, the Creator accelerator provides both gamma corrected and uncorrected visuals. See "Creator Visuals".

Like GX, SX, and ZX, the Creator accelerator supports multiple monitor video modes. See "Device Configuration".

The Creator accelerator comes in two configurations: SB (Creator) and DBZ (Creator 3D). SB stands for "Single Buffer" and DBZ stands for "Double Buffer plus Z." Z values are per-pixel depth information. These configurations differ in the amount of video memory on the board. The Creator 3D accelerator provides additional memory for hardware double buffering and 3D rendering.

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

Graphic

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.

Hardware Color LUT Usage

The following visuals use a color LUT:

On the Creator accelerators where there is only one color LUT, the colormaps of these visuals colormap flash against each other. Refer to "Reducing Colormap Flashing"" for how to avoid colormap flashing.

The other Creator accelerator visuals don't use color LUT resources. Colormaps of these visuals never flash.

Reducing Colormap Flashing

The 24-bit TrueColor visual of the Creator accelerator can display over 16 million colors simultaneously without colormap flashing. Furthermore, the Creator rendering engine is optimized for 24-bit rendering. Consequently, it is very desirable for users and X client programmers to use this visual.

Notes to End Users

Even though 24-bit TrueColor offers fast rendering and no colormap flashing, the built-in factory default visual on the Creator accelerator is 8-bit PseudoColor. This was done to accommodate X applications that don't handle a 24-bit visual properly. It is better to have programs run and colormap flash than to not run at all. Fortunately, the majority of desktop applications do run properly with this visual.

Users who desire less colormap flashing on their desktop can run the window system with the default visual configured to 24-bit TrueColor. This is the recommended mode of running the window system on the Creator accelerator.

  1. To run OpenWindows in this mode, use the following command:


    openwin -dev /dev/fbs/ffb0 defdepth 24

  1. To run CDE in this mode, edit the /usr/dt/config/Xservers file and add "defdepth 24" to the appropriate X start-up command for your server.

Be aware of the following conditions when using this mode:

Notes to Programmers

X client programmers should strive to write programs that are 24-bit clean, so that they run properly when the default visual is 24-bit TrueColor.

A program might fail to be 24-bit clean for several reasons. Following are some programming practices to avoid:

Some programs only run in 8-bit depth because they have been ported from 8-bit-only systems and they have not been upgraded. Some programs might store their lists of pixels in a 256-element array. Other programs may require a modifiable colormap to perform colormap double buffering.

If your program requires 8-bit PseudoColor, check the depth and class of the default visual. If it's not the 8-bit PseudoColor visual, search the visual list until you find it.

On a multiple plane group device like the Creator accelerator, the depth of the window you are creating may not match the depth of the parent window (which is often the root window). Unless you specify an explicit border pixel value, the border pixel value of the window is inherited from the parent. If the depths differ, XCreateWindow will fail with a BadMatch error. Always use XCreatewindow rather than XCreateSimpleWindow and explicitly specify a border pixel value.

Test your applications under both "defdepth 8" and "defdepth 24" modes of the window system.

Hardware Window IDs

Each window requires a hardware Window ID (WID) to display the contents of its pixels.

Note -

Do not confuse the term Window ID used in this context with the X protocol term window ID. An X protocol window ID is an XID which uniquely identifies a window. A hardware window ID is a value rendered into the frame buffer that controls window appearance.

Some overlay pixel codes are treated as opaque pixels, which display visible colors. Other overlay pixel codes are used to control the display attributes of underlay windows. These codes are referred to as hardware window IDs (WIDs). Specifically, a certain number of codes at the high end of the colormap (toward 255) are used as WIDs. The actual number of WIDs is configurable through the ffbconfig -maxwids option. For each overlay code used as a WID, the number of overlay colormap entries is reduced by one. The default value of maxwids is 32, so there are 224 opaque pixel values in the overlay.

One hardware WID is always reserved for windows of the default visual. The remaining WIDs are assigned on a priority basis to windows that have the following characteristics:

Non-default visual windows can share a WID with other windows of the same visual. However, like unique WID windows, double buffered windows always require a unique dedicated WID.

Creating these types of windows reduces the number of other types of windows that can be created. If all available WIDs are assigned, the call to XCreateWindow will return a BadAlloc failure.

maxwids must be a power-of-two. Thus, legal values for maxwids are: 1, 2, 4, 8, 16, and 32. The default value of maxwids is 32.

Reducing maxwids increases the number of opaque color pixels in the overlay visual but reduces the number of XGL, double buffered, and non-default visual windows that the user can create.

Cursor Management

The Creator accelerator has a hardware cursor. The image of this cursor is directly mixed into the output video signal. A software cursor, on the other hand, must be rendered into the frame buffer and the contents of the previous frame buffer must be temporarily stored. A software cursor incurs more overhead than a hardware cursor. A hardware cursor provides optimal interactive response when moving the cursor.

The maximum size of the Creator hardware cursor is 64 x 64. Cursors with an image whose width or height is less than or equal to 64 use the hardware cursor. Otherwise, they are rendered as software cursors.

The software cursor on the Creator accelerator is rendered in the overlay plane group. Therefore, software cursors interfere with pixels of overlay windows but not with pixels of underlay windows.

An X11 cursor has a foreground and background color that the client application requests. The colors of hardware cursors are rendered exactly as they are requested. However, the colors of software cursors may be approximations of the requested colors.

Note -

A bug in existing Solaris Visual graphics libraries means that software cursors are not properly removed. To work around this bug, the cursor will, in the presence of any DGA-grabbed window, be forced to be a hardware cursor, even if this entails truncating the cursor image.

Hardware Double Buffering

Hardware double buffering is supported through MBX and XGL. MBX and XGL double buffering cannot both be used on a window at the same time.

Hardware double buffering is provided for 8R windows on all the Creator accelerator configurations. Hardware double buffering for 24-bit windows is only provided on the Creator/DBZ (Creator3D) configuration. 8X overlay windows are never hardware double buffered on any Creator accelerator configuration; 8X windows are always software double buffered.

Activating hardware double buffering through MBX consumes one WID. This reduces the number of other WID-consuming windows that can be created. See "Hardware Window IDs"." If no WID is available, MBX falls back to software buffering mode in which a copy from a back buffer pixmap to the window is used to flip the buffers.

In MBX, the buffer flips occur synchronously. That is, the server request does not return until the vertical retrace period of the monitor occurs and the buffer is flipped. X11 clients may continue to run and send requests to the server, but will not be processed until pending buffer flips are complete.

Device Configuration

Use the /usr/sbin/ffbconfig program to alter the Creator accelerator's monitor video mode, default visual, default linear order, and the number of WIDs. Refer to the ffbconfig(1m) man page for details.

Attempts to grab stereo through DGA are rejected unless the monitor is configured in a stereo video mode.

When the "shared" OWconfig file is being updated via ffbconfig, an error occurs if the /usr/openwin directory is remotely mounted. This occurs even though ffbconfig is a setuid root program. This is because in UNIX, the root user of the local machine is different from the root users on a remote machine. The workaround is to log in to the remote machine to execute ffbconfig.

Performance Notes

The following sections contain perfofrmance notes for the Creator Accelerator on various applications.

Direct Xlib

Direct Xlib is not supported on the Creator accelerator. The X shared memory transport feature (new in Solaris 2.5) should be used instead. To enable shared memory transport, set the following environment variables in the client environment:


setenv DISPLAY :0

setenv XSUNTRANSPORT shmem

setenv XSUNSMESIZE 512

Note -

The last line specifies a client request buffer size of 512 kilobytes. Different request buffer sizes can be specified. However, 512 is a good compromise between the transport speed and the system memory resources consumed.

Applications that rely on XPutImage and Direct Xlib for fast pixel transfer into the frame buffer should instead use the MITSHM extension function XShmPutImage on the Creator accelerator. This function provides the fastest transfer of pixels into the frame buffer when the client is on the same machine as the X server.

If you are using XShmPutImage to a 24-bit visual, you may need to increase the amount of allocated shared memory beyond the default amount. See "The X11perf Benchmark"" for details.

The X11perf Benchmark

If you are running the x11perf benchmark when the default server visual is 24-bit TrueColor, the -shmput<nn> tests will fail. This is because this test requires more shared memory than that provided by the default shmsys configuration. The X11R5 version of x11perf version will core dump, while the X11R6 version will report an error and make no measurement.

To run this test, you will need to increase the amount of shared memory.

  1. To increase the amount of shared memory, add the following line to /etc/system:


    set shmsys:shminfo_shmmax=8192000

No Creator Pixel Copy Hardware

The Creator accelerator does not have hardware for copying pixels within the frame buffer. Pixels are copied by reading the pixels into CPU registers and then writing them back to the frame buffer. Thus, pixel copies within the frame buffer are CPU-intensive. When the system is under heavy load, the performance of window dragging operations may suffer. For example, the ShowMe Whiteboard "Snap Region" image drag operation may slow down while an active SunVideo stream is being rendered. This effect does not occur on a TurboGX accelerator, which has pixel copy hardware.

Background None Window Transient Color Effects

Dragging the imagetool image palette window with mouse shift-left over the main imagetool window can leave areas of the main window temporarily cyan-colored. These areas are quickly repaired, but persist long enough to be noticed. The effect is particularly pronounced when the window being dragged is partially inside and partially outside the imagetool main window. These effects occur because the imagetool main window is an Xview WIN_TRANSPARENT window. This means the background of the corresponding X window is set to None. For this type of window, the server relies on the application to repair damaged areas after an occluding window is moved. This method of damage repair is inherently slow because the client must process damage events and send rendering requests.

The imagetool image palette window is an 8-bit window. The pixel data resides in the Creator accelerator 8-bit red channel. The background pixel value of this 8-bit window is a small number, typically 0x02. The data in the red channel doesn't damage data in the green and blue channels. The background of the main window was white (0xffffff) but when the 8-bit window occludes, the pixel values are 0xffff02.

When the 8-bit window occludes the area, it is viewed as an 8-bit window. But when the 8-bit window is moved, the server immediately changes the window ID values in this region, indicating that the region is now to be viewed as a 24-bit window. This happens before the background is repaired. So, for a moment, the old pixel values in this region (0xffff02) are viewed as a 24-bit pixel. This pixel value is viewed as pure blue + pure green, which forms cyan.

Note -

This effect can also be seen on the SX frame buffer, although the SX frame buffer stores its 8-bit windows in the blue channel, so the transient color is green + red, which appears as yellow.

This effect is not as noticeable on the SX frame buffer, because it is more difficult to detect a contrast difference between yellow and white. On the Creator accelerator however, the difference between cyan and white is more pronounced. The effect also takes longer to go away when the dragged window is partially outside the imagetool window. This occurs because the Creator hardware has more rendering state to maintain than the SX frame buffer; dragging outside the imagetool window causes the window manager to continuously update the imagetool window header. This causes text rendering operations to be interleaved with copy operations. And since both operations use different rendering state, the state must be continually loaded and reloaded into the Creator hardware context. Thus, the repair of the transient color regions in on Creator in this situation is slower than the SX.

This example has dealt specifically with imagetool, but this will happen with any X window whose background is set to None. A bug for this has been filed for imagetool (Bug id 1215303).

To summarize, transient color effects like the one described above will occur on any window that has Background set to None. Applications that use this type of window should use some another background mode to avoid these effects. The X server can then repair the damage soon after it occurs.