Visual

[ XITE Reference Manual | XITE home ]

Contents

Name

Visual, visualFromName, visualFromClass, visualNameToClass, visualClassToName, DepthToReducedPlanes, DepthOfVisual, VisualInfoFromClass, Pseudo8VisualInfo, Direct24VisualInfo, True24VisualInfo, InitializeVisualInfos, RequestedPlanes, PlanesToDepth, RequestedImageVisual - XITE module for handling X11 display visuals.

Syntax

 #include <xite/Visual.h>

 Visual *visualFromName( char* name,
    int planes );

 int visualNameToClass( char* name );

 Visual *visualFromClass( int visualClass,
    int planes );

 char *visualClassToName( int visualClass );

 XVisualInfo *VisualInfoFromClass(
    int visualClass, int planes );

 int DepthOfVisual( Visual* visual );

 int DepthToReducedPlanes( int depth,
    Visual* visual );

 int PlanesToDepth( int planes );

 XVisualInfo *True24VisualInfo( void  );

 XVisualInfo *Direct24VisualInfo( void  );

 XVisualInfo *Pseudo8VisualInfo( void  );

 int RequestedPlanes( XVisualInfo *visualInfo  );

 void RequestedImageVisual( Display* dpy,
    int screen, int* planes, Visual** visual );

 void InitializeVisualInfos( Display* dpy,
    int screen, char* imageVisualClass,
    XVisualInfo** imageVisualInfo );

Overview

The Visual module is used to gather information about the visual capabilities of the screen to which XITE X11 display programs send their graphical output (e.g.images). Such capabilities are characterized by the visual class and depth (number of planes of the visual).

XITE users who wish to make X11 display programs will mostly not need to call any of the functions in this module. Refer to the XITE ximage(3) toolkit for ways of initializing display programs. The toolkit uses functions from the Visual module.

Visuals

In X11, the visual class can be one of PseudoColor, DirectColor, TrueColor, StaticColor, GrayScale or StaticGray, but not all X servers or display hardware can support all of these.

One of the supported visuals is denoted the default visual. This is the visual type (with corresponding depth) which the X server (the display) is set up to use by default. You can find out what default visual type your X server is set up to use by issuing the Unix command xrdb -symbols in the login window on your workstation. Look for the word immediately following the text "-DCLASS=". This tells you the visual type. Also check the number immediately following the text "-DPLANES=". This tells you the depth of the visual.

You can also find out what other visual types and depths your display is capable of using, by issuing the Unix command xdpyinfo.

XITE X11 display programs can currently run only on displays with at least one of the following capabilities 

     Visual class      Depth
     -----------------------
     PseudoColor         8
     DirectColor        24
     TrueColor          24

You can either choose to use the default visual if it is among the above three, or you can request a preferred visual different from the default (but of course still among the above three). Whatever your choice is, the chosen visual will be called the requested or preferred visual in this documentation (and other XITE documentation).

The requested visual will be used for all image widgets and image-related (such as histogram or slice) widgets in the application. All textual widgets, such as control panels and menus, will use the default visual and depth, regardless of which visual was requested.

The image widgets in an XITE display program may contain a menubutton which can be used to create a copy of the original image with a different visual. In this way, one may create widgets with a different visual than the requested and compare images displayed with different visuals at the same time. The appearance of the menubutton can be controlled with an option and an application resource if the application is initialized with an ximage toolkit function. Refer to ximage(3) for more information.

XITE display programs were originally developed for PseudoColor 8-plane visuals. The behaviour may be inferior in some cases on the other two visuals.

For information on how to choose visual type for an XITE display program based on the ximage toolkit, refer to ximage_init(3) or ximageInit(3).

For more information about visual types, refer to Xlib Programming Manual for version 11, O'Reilly & Associates, chapter 7.

Functions

InitializeVisualInfos initializes XITE X11 applications in terms of information about the visuals which screen on dpy is capable of supporting. imageVisualClass is the requested visual for the application. If the global variable multi_visual_e is False, only information about imageVisualClass and the default visual of the display will be determined (this may save memory on some X servers). The default is needed for non-image widgets. imageVisualClass must be one of the strings "PseudoColor", "DirectColor", "TrueColor" or NULL. In the latter case, choose a registered visual in the order PseudoColor 8-plane, DirectColor 24-plane, TrueColor 24-plane.

Pseudo8VisualInfo returns a reference to the registered XVisualInfo structure for a PseudoColor visual with depth 8. The visual information must have been initialized prior to this call.

Direct24VisualInfo returns a reference to the registered XVisualInfo structure for a DirectColor visual with depth 24. The visual information must have been initialized prior to this call.

True24VisualInfo returns a reference to the registered XVisualInfo structure for a TrueColor visual with depth 24. The visual information must have been initialized prior to this call.

DepthToReducedPlanes returns 7 for 8-bit PseudoColor and 21 for 24-bit DirectColor. Otherwise, returns depth. This function reflects that XITE image widgets can use a full colortable or a reduced version for display. If a full 256-entry colortable is used on an 8-bit PseudoColor display, the appearance of other windows on the screen may change in terms of color when the mouse pointer is inside the image window, depending on the display hardware. This is because the window with the mouse-pointer inside determines which colormap is installed in the hardware colormap. The contents of the hardware colormap determines the colors of all the windows on the screen. Some displays have more than one hardware colormap, in which case this "technicolor" effect is reduced.

If a reduced colortable is used on an 8-bit PseudoColor display, it means that only half of the entries in the 256-entry colormap is used by the image. Some of the reminaing entries are taken from the default colormap of the screen and some are used to enable overlays on the image.

On a PseudoColor 8-bit display, reduced-color display means that an original 256-entry colortable is subsampled to occupy only 128 (7 bit) colors. This is why DepthToReducedPlanes returns 7 in this cae. On a DirectColor 24-bit display, reduced-color display means that each primary is subsampled to occupy only 128 entries (three primaries, each with 7 bit gives 21 bit). This is why DepthToReducedPlanes returns 21 in this case. The number of colors in the latter case is reduced from approximately 16 million to approximately 2 million.

PlanesToDepth converts from a reduced-color value (number of planes) to a full-color value (depth), i.e. the reverse of DepthToReducedPlanes.

The names of the two previous functions reflect that we use the term depth about the depth of the visual and the term planes about the size of the reduced-color colormap introduced by XITE.

RequestedPlanes returns the number of planes for reduced-color display on the the visual given by visualInfo. If visualInfo is NULL, use the preferred/requested visual.

RequestedImageVisual returns in visual the preferred/requested visual. planes returns the number of planes for reduced-color display on this visual. If *visual is zero on entry, don't update it. Likewise, if *planes is zero on entry, don't update it.

visualFromName checks whether name is a legal name for a registered visual with XITE-depth planes. If it is, the visual is returned. If not, return NULL. If name is NULL, choose one of the registered visuals in the following order: PseudoColor, DirectColor, TrueColor. If planes is zero, don't consider its value when searching for a visual.

visualNameToClass returns one of the symbols PseudoColor, DirectColor, TrueColor, GrayScale or StaticGray for the corresponding strings "PseudoColor", "DirectColor", "TrueColor", "GrayScale" and "StaticGray" in name. If name is neither of these strings, -1 is returned.

visualClassToName is the reverse of visualNameToClass except that if visualClass is unknown, NULL is returned.

VisualInfoFromClass returns a reference to an XVisualInfo structure. visualClass must be one of the symbols PseudoColor, DirectColor, TrueColor, GrayScale or StaticGray. If planes is zero, don't consider its value when searching for a visual.

visualFromClass calls VisualOfVisualInfo and returns a reference to the Visual structure.

DepthOfVisual calls VisualInfoFromClass with planes equal to zero and returns the depth.

See also

InitializeVisual(3), xshow(1), ximage(3), ximageInit(3)

Author

Svein Bøe

Id

$Id: Visual.c,v 1.16 1997/05/30 10:32:26 svein Exp $