Introduction

The Creator accelerators are in many ways 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:

• Multiple plane groups
• Hardware double buffering
• Non-interfering transparent overlays
• 3D acceleration
• Stereoscopic support

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 the section "Creator Visuals."

Like GX, SX, and ZX, the Creator accelerator supports multiple monitor video modes. See the section "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

Default Visual

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 - Another name for the Creator accelerator is FFB, the Fast Frame Buffer. This name is used in Creator software package names, loadable device pipeline module names, the name of the configuration program, and device man pages. Hence the name ffbconfig.

---

When starting OpenWindows, the user can specify an alternate default visual using the normal OpenWindows command line options. Any of the exported visuals can be selected as the default. For example, the user 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 is recommended to reduce colormap flashing.

List of Visuals

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

8-bit PseudoColor 8-bit StaticColor 8-bit GrayScale 8-bit StaticGray

8-bit TrueColor 8-bit DirectColor 8-bit StaticGray Linear

24-bit TrueColor 24-bit DirectColor 24-bit TrueColor Linear

8-bit PseudoColor Overlay

---

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 6-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 B, G, and R channels can either store 8-bit pixel data (in the red channel only) or it can store 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 of three different visual types (the 24-bit visuals). There is only one visual provided by the X channel: 8X PseudoColor.

Figure 6-1

The colormap_size of the underlay visuals is 256. The colormap_size of the overlay visual is 256 - maxwids.

Overlay/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 gets stored in the X channel.

The pixels of windows in the overlay visual do not interfere with the pixels of windows in the underlay visuals. However the pixels of windows in the underlay visuals do interfere with pixels of windows in the overlay visual. 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 of the pixel values in the 8X plane group display opaque colors and some of the codes are used as window IDs which control the display of pixels in the underlay visuals.

maxwids is an ffbconfig(1m) configuration option which specifies how many of the overlay pixel values are to be used as hardware window IDs. See "Hardware Window IDs." The minimum legal value for maxwids is 1. The default value is 32. Thus, the overlay visual is a partial visual--it has less than the usual 256 colormap entries. For colormaps of this visual, if the client renders with a pixel value greater or equal to the specified number of colormap entries no error will be generated and the colors displayed will be 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 which has 8-bit and 24-bit underlay visuals and a single 8-bit PseudoColor overlay visual. However, there are two primary differences.

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:

• 24-bit TrueColor Linear
• 8-bit StaticGray Linear

Both linear and non-linear visuals are present on the X11 screen visual list and these 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 whole 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. But on the Creator accelerator, this is possible.

Single Color LUT CG14 has two hardware color LUTs. One is used by the 8-bit underlay visuals and one is used by the 8-bit overlay visual. In contrast, the Creator accelerator has 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 care is taken to make sure that the colormaps of the two windows have the same colors in the same pixel locations.

Programmers should take care to share overlay and underlay colors when writing transparent overlay applications which are intended to run on the Creator accelerator. 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 kept correlated (i.e. spatially congruent) by the application. In this situation, when the mouse pointer is inside the boundary of the underlay/overlay window pair, the overlay colormap will be installed in the hardware CLUT and the underlay colormap will not be installed. Thus, care should be taken 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.

Comparison with the ZX Accelerator

Default Visual is not Overlay 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. This means that

applications that wish to create popup windows that are non-damaging with underlay windows 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 2.4, it is recommended that the external reference to this function be defined 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 code using it will not necessarily be portable to other devices.

---

Window Manager Implications The fact that the Creator accelerator default visual is not an overlay causes problems when overlay windows are not override-redirect (i.e. are 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. It does this even if an application specifies a non-default visual for the popup window.

For example, when the default visual is 8-bit underlay PseudoColor, even if an application specifies to a toolkit that a popup window is to be placed in the 8-bit overlay PseudoColor visual, the window manager will wrap it with an 8-bit underlay decoration window. Thus, the popup will continue to damage other underlay windows, which is contrary to the user's intention.

There are two ways to get around this limitation:

1. One way is to require the end user to configure the default visual to be the overlay visual. This may be done by typing the following before starting the window system:

/usr/sbin/ffbconfig -defoverlay true

But keep in mind that the overlay visual has less colormap entries than the underlay 8-bit visual. Thus, the default colormap may fill up quicker and this may lead to increased colormap flashing.

2. The other way is to rewrite the application to create override redirect pop-ups and manage them directly through Xlib, bypassing the toolkit.

Hardware Color LUT Usage

The Creator accelerator has a single hardware color LUT. The following visuals use this color LUT:

8-bit PseudoColor 8-bit StaticColor 8-bit GrayScale 8-bit TrueColor 8-bit DirectColor

24-bit DirectColor

8-bit PseudoColor Overlay

The colormaps of these visuals will colormap flash against each other. Refer to "Reducing Colormap Flashing" for a method of avoiding 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 has been optimized for 24-bit rendering. Consequently, it is very desirable for users and X client programmers to put their applications into this visual.

Advice 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 choice was made to accommodate X applications that don't properly handle a 24-bit visual. It is better to have programs run and colormap flash than to not run at all. Fortunately, the majority of desktop applications do properly run 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.

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

openwin -dev /dev/fbs/ffb0 defdepth 24

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

When using this mode, you should be aware of the following.

1. As mentioned above, some X applications may not be able to handle the 24-bit default. Most programs of this sort fail to run, issuing a BadMatch error message. Other programs may core dump or draw incorrect colors. If you encounter such an application, you can diagnose the problem by rerunning the application under the 8-bit PseudoColor default visual. If the program works, it is probably not able to handle a 24-bit TrueColor default visual. Contact the application supplier and request that the program be upgraded. In the meantime, you will need to use the factory default 8-bit PseudoColor visual mode until the application is fixed.

2. When the default visual depth is 24-bit, pixmaps and window backing store will occupy four times the space that they did with an 8-bit depth. This typically does not increase the working set of the server, but it does increase its swap space usage. If you run programs that use lots of pixmaps or backing store windows, you may want to consider staying in 8-bit mode.

Advice to Programmers

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

There are several reasons why a program might fail to be 24-bit clean. Here are some examples of programming practices to avoid:

1. Never automatically assume that the default visual is 8-bit PseudoColor.

   Some programs only run in 8-bit depth because they are ports from 8-bit only systems and there are not enough resources to upgrade them. Some programs might store their lists of pixels in a 256-element array. Other programs may require a modifiable colormap in order to perform colormap double buffering.

   It is strongly recommended that programs should be made 24-bit clean. But if your program really absolutely requires 8-bit PseudoColor, be sure to 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.

2. Don't inherit the border pixel from the parent.

   On a multiple plane group device like the Creator accelerator, the depth 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 window's border pixel value will be inherited from the parent. If the depths differ, XCreateWindow will fail with a BadMatch error. Thus, it is good programming practice to always to use XCreatewindow (rather than XCreateSimpleWindow) and to explicitly specify a border pixel value.

Programmers are strongly encouraged to test their 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 - The term Window ID used in this context should not be confused 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 which controls window appearance.

---

Some overlay pixel codes are treated as opaque pixels. These 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 via 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 rest of the WIDs are assigned on a first-come first-serve basis to windows that:

• Have a non-default visual, or
• Are double buffered, or
• Have a unique WID assigned to them for the purposes of hardware WID clipping. (This clipping technique is used by Sun's 3D rendering libraries).

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 a window of one of these types reduces the number of windows of other types that can be created. If all available WIDs have been 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 previous frame buffer contents 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 . 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 window 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 exactly what was requested. However, the colors of software cursors may be approximations of the colors requested.

---

Note - To work around a bug in existing Solaris Visual graphics libraries, which don't properly remove software cursors, 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 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 will reduce the number of other WID-consuming windows that can be created. See section "Hardware Window IDs." If no WID is available, MBX will fall 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 they will not be processed until any pending buffer flip is complete.

Device Configuration

The program /usr/sbin/ffbconfig allows the user to alter the Creator accelerator's monitor video mode, the default visual, the 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 has been configured in a stereo video mode.

When the "shared" OWconfig file is being updated via ffbconfig an error will occur 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 work-around is to log in to the remote machine in order to execute ffbconfig.

Performance Notes

Direct Xlib

Direct Xlib is not supported on the Creator accelerator. It is recommended that the X shared memory transport feature (new in Solaris 2.5) 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 next section for details.

X11perf -shmput<nn>

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 provided by the default shmsys configuration. The X11R5 version of x11perf version will actually core dump, while the X11R6 version will report an error and make no measurement.

You will need to increase the amount of shared memory to allow this test to run. To do this, 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. One example of this is the slow-down of the ShowMe Whiteboard "Snap Region" image drag operation while an active SunVideo stream is being rendered. This slow down effect does not occur on a TGX accelerator, which has pixel copy hardware.

Miscellaneous

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 they persist long enough for the user to notice them. 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 that 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 away. 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 moves away, 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 brief instant, 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.

---

On the SX frame buffer, the effect is hardly noticeable because it is harder for the human eye to notice a contrast difference between yellow and white. But on the Creator accelerator, the difference between cyan and white is more noticeable. Also the effect takes longer to go away when the dragged window is partially outside the imagetool window. This is because the Creator hardware has more rendering state to maintain than the SX frame buffer and 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. To avoid these effects, applications using this kind of window should use some other background mode instead. This allows the X server to repair damage as soon as possible after it occurs.