VDisplayJobDoneMessage VOpenServer VPackByteToBit VRemoveScale VReadMenucomFile VReadMenutreeFile VSleep VWriteMenucomFile VWriteMenutreeFileOne must call VCreateWindows before calling any of the following process interface functions:
VCancelEvents VSelectEventsOne must call functions VSetVisualClass first, and then VCreateWindows, and then VCreateColormap in the graphics interface before calling any function that requires a prior call to VOpenServer except
VCheckInterrupt VCreateColormap VCreateWindows VGetScreenSize VGetMenuInformation VGetPanelInformation VGetScaleInformation VGetScaleLayoutInformation VGetServerScreenInformation VSetScaleInformation VSetVisualClassIf one does not call
VOpenServer VSetVisualClass VCreateWindows VCreateColormapbefore calling a function requiring them, an error message will be written to the standard error stream, a core dump file will be produced and the process will exit.
Whenever any of the options in the button or dialog window are to be selected, one should determine the required events and then use VSelectEvents to select the desired events. Appropriate functions associated with these windows should be called to set up the options in these windows.
StaticGray GrayScale StaticColor PseudoColor TrueColor DirectColor.StaticGray, StaticColor and TrueColor are visual classes in which the devices have fixed color maps that cannot be changed via a program. StaticGray and GrayScale refer to devices with a gray scale color map i.e. the color cells are indexed by gray values and the color cells have gray values. PseudoColor and StaticColor refer to devices with a pseudocolor color map, i.e., the color cells are indexed by gray (scalar) values and the color cells have vector (R,G,B) values. TrueColor and DirectColor refer to devices with a truecolor color map. The colormap in these visual classes have three component maps, one for each of R, G, and B, in each of which the color cells are indexed by a scalar (the respective R, G, or B) value and the color cells have scalar (the respective R, G, or B components) values. Although the limitations due to the static nature of the color of StaticGray, StaticColor, and TrueColor visual classes can be overcome by appropriately designed software color maps, these have significant computational and storage overhead. For this reason and since devices belonging to these visual classes are not common, we have decided not to handle them in 3DVIEWNIX at present.
Some color cells and the associated colors of the colormap are reserved by the 3DVIEWNIX environment for defining the fixed color of various entities such as the background of the various windows and of the text and graphics displayed in them. The function VGetReservedColors and VGetFreeColocells should be called to find out the reserved colors and the free colorcells that are available. Whenever these entities are modified, VSaveColormap should be called to update the file COLOR.COM that always stores complete information regarding current reserved colorcells and colors (see APPENDIX C for full details of COLOR.COM). This file also stores complete current colormap information. Whenever a Process1 calls a Process2, Process1 should call VSaveColormap to store the current colormap in COLOR.COM file before exiting. After returning from Process2, Process1 should call VLoadColormap to restore colormap and reserved colors from COLOR.COM file.
A device may have multiple, permitted visual classes. If the highest visual class of the device is PseudoColor (meaning that the device can display at best a pseudocolor image) or DirectColor and if we want to display a truecolor image, then the function VTurnOnTruecolor should be called first. This call sets up a fixed truecolor map approximation using the available pseudocolor map for PseudoColor visual class, or sets up an identity color map for DirectColor visual class. No overlay facility is allowed when this approximation is used for PseudoColor visual class. When this display capability is no longer needed, function VTurnOffTruecolor should be called. This allows colormap to be reestablished for PseudoColor and DirectColor and the overlay facility will now become available for PseudoColor.
There are two ways to display gray and color images in the image window. One method is to use the function VDisplayGrayImage or VDisplayColorImage and the other is by using VPutImage. The first is slower than the second since all computations related to intensity scaling and colormap are done by the function. The second is relatively faster since it displays prepared images. The functions used for preparing images for display are VPrepareGrayImage and VPrepareColorImage.
Since hardware facilities for directly displaying overlay data are not common, X manages all overlay display via the colormap. This has the unfortunate consequence that the number of color values available have to be compromised to accomodate overlays, this number decreasing rapidly as the number of overlays required increases. The overlay facility is provided by allocating a unique bit of the color value field for each overlay. For example, an 8-bit PseudoColor display device will have only 64 color values left for mapping DISPLAY data values if two overlays are needed simultaneously. Overlay-related functions provide a convenient facility to automatically set up the color maps taking into consideration such factors as the reserved colors, the visual class information, etc., without the programmer requiring to handle these issues. The effect is that, from the programmer's point of view, the overlay facility available through these functions is very similar in convenience to hardware overlays, notwithstanding the dramatic reduction in available displayable colors due to overlays.
The function VTurnOnOverlay should be called prior to calling any overlay- related functions. The number of overlays used in a program is determined by the argument novl of VCreateWindows function. This number may be changed subsequently by calling VChangeNumberOfOverlays. The display due to the overlays can be turned off by calling VTurnOffOverlay. If novl is equal to 0 when VCreateWindows is called (and if the number of overlays is not changed subsequently) or if the overlays are not turned on prior to a call to an overlay function (such as VDisplayOverlay, VDisplayOverlayLine, etc.) the function returns an error.
Although sometimes VTurnOffOverlay and VEraseOverlay have the same effect, they behave differently. While VTurnOffOverlay temporarily turns off the display due to the overlay without altering the image, VEraseOverlay turns off the overlay by changing the image itself. Thus if VTurnOffOverlay was previously used to remove the overlay display, it can be brought back by calling VTurnOnOverlay. However, if VEraseOverlay was used previously, then to get the display back, VDisplayOverlay or whatever graphics functions were used to draw the overlay display should be called. If the overlay data are in 1 byte/pixel unpacked form they should be converted to 1 bit/pixel packed form by calling VPackByteToBit.
For the display of overlay, gray and color images, the rectangle representing the image border need not be entirely within the image window. If the rectangle is not properly contained in the image window but not entirely outside either, the values of the variables defining the location and size of the rectangle are considered valid and the display will be completed but an error code will be returned. If the rectangle falls entirely outside, the values are considered invalid and a fatal error results.
In this manual all interface function names have V as a prefix (for VIEWNIX) and the names are fully spelled out.