MAN page from Mandrake Other XITE-3.3-3.i386.rpm

VISUAL

Section: C Library Functions (3)
Updated: 16 Mar 1998
Index

NAME

Visual, visualFromName, visualFromClass, visualNameToClass,visualClassToName, DepthToReducedPlanes, DepthOfVisual,VisualInfoFromClass, Pseudo8VisualInfo, Direct24VisualInfo,True24VisualInfo, InitializeVisualInfos, RequestedPlanes,PlanesToDepth, RequestedImageVisual - XITE module forhandling 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 Visualmodule is used to gather information about thevisual capabilities of the screen to which XITE X11 displayprograms send their graphical output (e.g.images). Suchcapabilities are characterized by the visual class and depth(number of planes of the visual).

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

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 ofthese.

One of the supported visuals is denoted the default visual.This is the visual type (with corresponding depth) which the Xserver (the display) is set up to use by default. You can findout what default visual type your X server is set up to use byissuing the Unix command xrdb -symbolsin the login windowon your workstation. Look for the word immediately followingthe text "-DCLASS=". This tells you the visual type. Alsocheck 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 depthsyour display is capable of using, by issuing the Unix commandxdpyinfo.

XITE X11 display programs can currently run only on displayswith 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 amongthe above three, or you can request a preferred visualdifferent from the default (but of course still among theabove three). Whatever your choice is, the chosen visual willbe called the requestedor preferredvisual in thisdocumentation (and other XITE documentation).

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

The image widgets in an XITE display program may contain amenubutton which can be used to create a copy of the originalimage with a different visual. In this way, one may createwidgets with a different visual than the requested and compareimages displayed with different visuals at the same time.The appearance of the menubutton can be controlled withan option and an application resource if the application isinitialized with an ximagetoolkit function. Refer toximage(3)for more information.

XITE display programs were originally developed for PseudoColor8-plane visuals. The behaviour may be inferior in some caseson the other two visuals.

For information on how to choose visual type for an XITEdisplay program based on the ximagetoolkit, refer toximage_init(3)or ximageInit(3).

For more information about visual types, refer to XlibProgramming Manualfor version 11, O'Reilly & Associates,chapter 7.

FUNCTIONS

InitializeVisualInfosinitializes XITE X11 applicationsin terms of information about the visuals which screenon dpyis capable of supporting. imageVisualClassisthe requested visual for the application. If the globalvariable multi_visual_eis False, only information aboutimageVisualClassand the default visual of the displaywill be determined (this may save memory on some X servers).The default is needed for non-image widgets.imageVisualClassmust be one of the strings "PseudoColor","DirectColor", "TrueColor" or NULL. In the latter case, choosea registered visual in the order PseudoColor 8-plane,DirectColor 24-plane, TrueColor 24-plane.

Pseudo8VisualInforeturns a reference to the registeredXVisualInfo structure for a PseudoColor visual with depth 8.The visual information must have been initialized prior tothis call.

Direct24VisualInforeturns a reference to the registeredXVisualInfo structure for a DirectColor visual with depth 24.The visual information must have been initialized prior tothis call.

True24VisualInforeturns a reference to the registeredXVisualInfo structure for a TrueColor visual with depth 24.The visual information must have been initialized prior tothis call.

DepthToReducedPlanesreturns 7 for 8-bit PseudoColor and 21for 24-bit DirectColor. Otherwise, returns depth.This function reflects that XITE image widgets canuse a full colortable or a reduced version for display. If afull 256-entry colortable is used on an 8-bit PseudoColordisplay, the appearance of other windows on the screen maychange in terms of color when the mouse pointer is inside theimage window, depending on the display hardware. This isbecause the window with the mouse-pointer inside determineswhich colormap is installed in the hardware colormap. Thecontents of the hardware colormap determines the colors of allthe windows on the screen. Some displays have more than onehardware colormap, in which case this "technicolor" effect isreduced.

If a reduced colortable is used on an 8-bit PseudoColordisplay, it means that only half of the entries in the256-entry colormap is used by the image. Some of the reminaingentries are taken from the default colormap of the screen andsome are used to enable overlays on the image.

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

PlanesToDepthconverts from a reduced-color value (number ofplanes) to a full-color value (depth), i.e. the reverse ofDepthToReducedPlanes.

The names of the two previous functions reflect that we usethe term depth about the depth of the visual and the termplanes about the size of the reduced-color colormap introducedby XITE.

RequestedPlanesreturns the number of planes forreduced-color display on the the visual given by visualInfo.If visualInfois NULL, use the preferred/requested visual.

RequestedImageVisualreturns in visualthepreferred/requested visual. planesreturns the number ofplanes for reduced-color display on this visual.If *visualis zero on entry, don't update it. Likewise,if *planesis zero on entry, don't update it.

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

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

visualClassToNameis the reverse of visualNameToClassexcept that if visualClassis unknown, NULL is returned.

VisualInfoFromClassreturns a reference to an XVisualInfostructure. visualClassmust be one of the symbolsPseudoColor, DirectColor, TrueColor, GrayScale or StaticGray.If planesis zero, don't consider its value when searchingfor a visual.

visualFromClasscalls VisualOfVisualInfoand returnsa reference to the Visual structure.

DepthOfVisualcalls VisualInfoFromClasswith planesequal to zero and returns the depth.

AUTHOR

Svein Bře

ID

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

This document was created byman2html,using the manual pages.