Solaris X Window System Developer's Guide

About Visuals

A display device can support one or more display formats. In the X window system, the display formats supported by the window server are communicated to client applications in the form of visuals. A visual is a data structure describing the display format a display device supports.

When an X11 client creates a window, it specifies the window's visual. The visual describes the display characteristics for each pixel in the window. In other words, a window's visual instructs the display device's video hardware how to interpret the value of the window's pixels.

For each display device configured into the system, there is an X11 screen. For each screen, a list of supported visuals is exported by the server to client applications. This list of visuals tells the client application which display formats are available for creating windows.

The visuals exported by the server for a display screen are not fixed; they depend on the screen's device handler. Since the exporting of visuals is under the control of the device handler, client applications must be prepared to deal with a wide variety of visuals, including visuals with depths other than those that have previously been common, such as 1, 8, and 24 bits. Visuals with depths of 4, 16, and odd depths may not be exported, and clients must be prepared to handle them.

Client applications can query the list of supported visuals for a screen by calling the Xlib routines XGetVisualInfo(3) or XMatchVisualInfo(3), and can query the list of supported visuals using the utility xdpyinfo(1). For general information on color and visuals in X11, see the X11 documentation listed in the preface to this manual.

Default Visual

For each X11 screen, one of the exported visuals for the screen is designated the default visual. The default visual is the visual assigned to the screen's root window, and this visual is the visual that most applications use to create their windows. When a client application starts, its windows are assigned the default visual unless the application specifies a different visual.

The built-in default visual is the visual hard-coded in the Solaris X server. For each screen, there is a default visual that depends on the characteristics of the display device for that screen. This is the default visual unless you specify a different default visual when you run openwin(1).

Users can change the default visual that window server advertises in the connection block. One reason for this is to force client programs that cannot run in the default visual to run in a specific visual. For example, on a 24-bit device that has the TrueColor visual as its default visual, an application that cannot run with 24-bit color may run on a PseudoColor visual.

For developers on multi-depth devices, changing the default visual is a useful way to test that your application works in different configurations. For information on how to change the default visual, see the xsun(1) man page. The default visual and the list of supported visuals exported by the server can be examined from X11 using XGetVisualInfo(3).

Visuals on Multi-Depth Devices

The Solaris X server supports devices that can display windows of more than one pixel depth simultaneously. These devices are called multi-depth devices. Since most of these devices are implemented with separate groups of bit planes for each depth, the term multiple plane group (MPG) device is often used for these devices.

For each depth, there might be one or more visuals exported. For most MPG devices, windows can be created using any of the exported visuals. For applications that prefer a TrueColor visual, the developer should determine whether the TrueColor visual is available, since it may be available even if PseudoColor is the default visual.

Hints for Windows Programming With Visuals

This section discusses various issues that may arise when programming X11 applications for devices that support more than one visual.

Default Visual Assumptions

A common mistake in programming an X11 client is to assume that the default visual has an indexed class (for example, PseudoColor or StaticColor). It is possible for the default visual to be 24-bit TrueColor on some devices. Clients expecting to run on these devices must be prepared to handle this type of default visual.

Other common programming mistakes with visuals are:

If the device does not support a visual requested by a client, the following error message is returned. In this error message, # represents the depth number requested, and n represents the requested display device. If this message is returned for a supported visual/device combination (as indicated in Table A–1), then an installation problem exists.


cannot provide a default depth #for device


In general, client applications may need to be modified to make them more portable in the presence of different default visual types.

Setting the Border Pixel

When creating a window with a visual that is not the default visual, applications must set the border_pixel value in the window attribute structure, or a BadMatch error occurs. This is a common programming error that may be difficult to debug. For information on setting the border pixel, see the XCreateWindow man page.

Note –

If you are experiencing improper graphics and double-buffering performance (such as lack of acceleration), OpenWindows might not have been installed as root.