Using Starbase in X Windows

This section contains device specific information needed to run Starbase programs in X11 windows. If you need a general, device-independent explanation of using Starbase in X11 windows, refer to the "Using Starbase with the X Window System" chapter of Starbase Graphics Techniques.

To reduce the complexity of having multiple X server modes, the hphcrx48z drivers for X and Starbase only support one X server mode. Several other key features have been designed to improve the overall usability of the devices in the X11 windows environment, and to reduce interaction issues between the X11 user interface and graphics library APIs (such as Starbase), that provide direct hardware access (DHA).

Per-Window Double-Buffering

The HP Visualize-48 and HP Visualize-48XP support double-buffering in the images planes on a per-window basis. The HP Visualize-48 and HP Visualize-48XP graphics devices support 8/8 and 24/24 planes double-buffered for each of the Starbase color map modes (CMAP_NORMAL, CMAP_FULL, CMAP_MONOTONIC) in the image and overlay planes. Any X11 library drawing routines will render to the currently visible buffer of a window that has double-buffering enabled.

Note that Starbase uses the hpvmx device driver to perform double-buffering in software in the overlay planes. This double-buffering method is slower than the hardware double-buffering used in the image planes. Any X11 library drawing routines will render to the currently visible buffer of a window that has double-buffering enabled.

Available Color Map Entries

The HP Visualize-48 and HP Visualize-48XP have two hardware color maps in the overlay planes and four hardware color maps in the image planes.

If you query the X server for the number of entries in the default overlay visual's color map while you are using the default X server mode of the HP Visualize-48 and HP Visualize-48XP, the server will reply that there are 256 entries available. Although all 256 entries are available for use by an application, the last entry (index 255) is not writable because it is allocated by the X server.

Starbase Color Maps and X11 Read/Write Restrictions

The X color model defines read/write restrictions both on color maps and on individual entries in color maps. As of HP-UX 9.05, Starbase no longer overwrites read-only color maps or color map entries as defined in the X color model. Attempts to write to color map entries in read-only color maps (that is, for TrueColor, StaticColor, or StaticGray visuals) are silently ignored.

Accessing HP Color Recovery with X Windows

The HP Visualize-48 and HP Visualize-48XP support HP Color Recovery for shaded areas. When a depth 8 window is used, HP Color Recovery will generate a better picture by attempting to eliminate the graininess caused by dithering. Color Recovery is available on all depth 8 windows on the HP Visualize-48 and HP Visualize-48XP. For more information about HP Color Recovery, read the section "HP Color Recovery" found in this chapter.

The Starbase, HP PEX, and HP-PHIGS graphics libraries provide programmers who use these APIs with transparent access to the HP Color Recovery capability of the HP Visualize-48 and HP Visualize-48XP. If you are producing graphics using Xlib calls, then your application must perform some of the necessary processing. At server start-up, there is one property that is defined and placed on the root window if the HP_DISABLE_COLOR_RECOVERY environment variable has not been exported. This property is:

_HP_RGB_SMOOTH_MAP_LIST

The above property is of type RGB_COLOR_MAP and carries pointers to structures of type XStandardColormap. It may be interrogated with calls to XGetRGBColormaps. The property _HP_RGB_SMOOTH_MAP_LIST is a list of color maps that are associated with window visual IDs that support HP Color Recovery. When the XGetRGBColormaps routine searches throughout this list for a color map with a visual ID that matches your window's visual ID and it finds one, your application knows that your visual supports HP Color Recovery, and uses that color map for any HP Color Recovery window.

HP Color Recovery uses all 256 entries of one of the available color maps. The color visual used by HP Color Recovery emulates the 24-bit TrueColor visual. Thus, the colors red, green, and blue are typically declared as integers in the range from 0 to 255. Note that each window that uses HP Color Recovery will use the same color map.

For HP Color Recovery to produce the best results, the emulated 24-bit TrueColor data is dithered as explained below.

A pixel to be dithered is sent to the routine provided in this example. Note that the values of the variables RedValue, GreenValue and BlueValue are generated by an application. In this example, the color values are assumed to be in the range [0..255].

The given routine receives the color values and the X and Y window address (Xp and Yp) of the pixel. The X and Y address is used to access the dither tables. The values from the dither tables are added to the color values. After the dither addition, the resultant color values are quantized to 3 bits of red and green and 2 bits of blue. The quantized results are packed into an 8-bit unsigned char and then stored in the frame buffer. As the contents of the frame buffer are scanned to the CRT, a special section in the HP Visualize-48 and HP Visualize-48XP hardware then converts the 8-bit data stored in the frame buffer into a 24-bit TrueColor image for display.

Here is a routine that can be used to dither the 24-bit TrueColor data.

unsigned char dither_pixel_for_CR(RedValue,GreenValue,BlueValue,Xp,Yp)
int RedValue,GreenValueBlueValue,Xp,Yp;
{
static short dither_red[2][16] = {
  {-16,  4, -1, 11,-14,  6, -3,  9,-15,  5, -2, 10,-13,  7, -4, 8},
  { 15, -5,  0,-12, 13, -7,  2,-10, 14, -6,  1,-11, 12, -8,  3, -9} };
 
static short dither_green[2][16] = {
  { 11,-15,  7, -3,  8,-14,  4, -2, 10,-16,  6, -4,  9,-13,  5,-1},
  {-12, 14, -8,  2, -9, 13, -5,  1,-11, 15, -7,  3,-10, 12, -6,  0} };
 
static short dither_blue[2][16] = {
  { -3,  9,-13,  7, -1, 11,-15,  5, -4,  8,-14,  6, -2, 10,-16, 4},
  {  2,-10, 12, -8,  0,-12, 14, -6,  3, -9, 13, -7,  1,-11, 15, -5} };
 
int red, green, blue;
int x_dither_table, y_dither_table;
unsigned char pixel;
 
x_dither_table = Xp % 16;   /* X Pixel Address MOD 16 */
y_dither_table = Yp % 2;    /* Y Pixel Address MOD 2 */
 
red = RedValue;
green = GreenValue;
blue = BlueValue;
 
if (red >= 48) /* 48 is a constant required by this routine */
   red=red-16;
else
   red=red/2+8;
red += dither_red[y_dither_table][x_dither_table];
if (red > 0xff) red = 0xff;
if (red < 0x00) red = 0x00;
 
if (green >= 48) /* 48 is a constant required by this routine */
   green=green-16;
else
   green=green/2+8;
green += dither_green[y_dither_table][x_dither_table];
if (green > 0xff) green = 0xff;
if (green < 0x00) green = 0x00;
 
if (blue >= 112) /* 112 is a constant required by this routine */
   blue=blue-32;
else
   blue=blue/2+24;
blue += (dither_blue[y_dither_table][x_dither_table]<<1);
if (blue > 0xff) blue = 0xff;
if (blue < 0x00) blue = 0x00;
 
pixel = ((red &0xE0) | ((green &0xE0) >> 3) | ((blue &0xC0) >> 6));
 
return(pixel);
}

Backing Store

Backing store is only supported when rendering to overlay planes with the hpvmx driver. For image plane windows, you need to detect window exposure events and repaint the window when a previously obscured portion of a window is made visible.

The HP Visualize-48 and HP Visualize-48XP support backing store (also known as "retained raster") if acceleration is disabled. The backing store feature allows a window being rendered to by a direct hardware access (DHA) client to be "backed-up" to a virtual frame buffer whenever any portion of the window is obscured by another window. In this case, the application is not required to catch "expose events" from X11 and redraw the picture when occlusion occurs. In fact, no "expose events" will be generated if backing store is enabled.

Thus, when a window is placed on top of another window containing a complete image, the window system will save the contents of the latter window before displaying the obscuring window. Then, when the obscuring window is removed, the earlier contents of the occluded area plus any new rendering that has occurred in the occluded area during the cover-up will be restored. Since rendering to the virtual frame buffer is not as fast as rendering to the actual frame buffer in the occluded area, the performance will suffer, but only while the window is occluded.

Backing Store Exceptions

In general, those Starbase operations that draw to the display are also supported when drawing to backing store. The exceptions to this are:

Backing store with 24-plane visuals is not supported.
Backing store for the HP Visualize-48 and HP Visualize-48XP accelerators cannot be enabled.
Backing store will not work with certain gescape operations that access device-dependent features.
Backing store contents may be incorrect if you mix Xlib rendering with Starbase rendering to an 8/8 double-buffered window.

If these limitations on backing store support prove troublesome in your application, do not use backing store. Instead, detect window exposure events and repaint the window when a previously obscured portion of a window is made visible.

X11 Cursor

The X11 cursor (often called the sprite) is maintained by the display hardware and never interferes with the frame buffer contents in either the image or overlay planes.

Supported Visuals

The following table of Supported Visuals contains information for programmers using either Xlib graphics or Starbase. The table lists the image plane depths of windows and color map access modes that are supported for a given graphics device. It also indicates whether or not backing store (also known as "retained raster") is available for a given visual, and lists the double-buffer configurations supported by Starbase for this device driver.

Table 3-3 Supported Visuals

Device	Depth	Visual Class	Backing Store		Starbase Double-Buffer ^[1]
Device	Depth	Visual Class	Xlib	Starbase	Starbase Double-Buffer ^[1]
HP Visualize-48, HP Visualize-48XP	8 24	PseudoColor TrueColor DirectColor TrueColor	Yes^[2] Yes2 ^[2]	No^[3] No3 ^[3]	8/8 8/8 24/24 24/24
^[1]Double-buffering with less than 8 planes (4/4, 3/3, 2/2, 1/1) is supported for compatibility with previous devices, however, it is not recommended. The `write_enable` and `display_enable` masks are used to accomplish double-buffering with less than 8 planes in a depth 8 visual. Flashing may occur, however, as this kind of double-buffering cannot be done on a per window basis. Note that double-buffering with less than 8-planes is only supported in `CMAP_NORMAL`. ^[2]Xlib primitives are supported by backing store. Whenever backing store is not maintained, normal expose events are generated. ^[3]Backing store is only supported when rendering with the `hpvmx` driver.