Chapter 2 : Guidelines On The Use Of Functions


The following guidelines illustrate how the interface functions are to be used to program in the 3DVIEWNIX environment.

2.1 Initialization

Most of the functions in the graphics interface and some in the process interface require a prior call to the graphics interface function VOpenServer. One must call VOpenServer before calling any of the functions in the graphics interface except the following :

 
        VDisplayJobDoneMessage
        VOpenServer
        VPackByteToBit
        VRemoveScale
	VReadMenucomFile
	VReadMenutreeFile
	VSleep
	VWriteMenucomFile
	VWriteMenutreeFile
One must call VCreateWindows before calling any of the following process interface functions:
 
        VCancelEvents
        VSelectEvents
One 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
        VSetVisualClass
If one does not call
 
        VOpenServer
        VSetVisualClass
        VCreateWindows
        VCreateColormap
before 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.

2.2 Menu Handling

3DVIEWNIX allows division of menu items between processes in quite an arbitrary fashion. This implies that a process may have more than one menu item associated with it. If this is the case with a process, it should call VReadMenucomFile first to determine whether the submenu associated with the last menu item selected in a previous process that triggered the current process is horizontal or vertical. Accordingly, VDisplayMenu is to be called by this process. Of course, the process should call VSelectMenuItem to select further menu items from what is displayed. The selected menu may trigger another process, or some action within the same process or further submenu display, and so on. If the next menu selected is outside the realm of this process it should exit to the previous process. If a process has only one menu item associated with it, it should call VSelectMenuItem before it terminates to ensure that the process it returns to will be back in the menu selection mode.

2.3 Event Handling

X is an event-driven system, so one must call VSelectEvents to select events. When an event actually takes place, X will return all relevant information related to the event. X does not allow more than one client to select StructureRedirectMask, ResizeRedirectMask, or ButtonPressMask on the same window. Therefore, if Process1 calls Process2 and both need the ButtonPress event, then Process1 should call VCancelEvents to free all events except the Expose event before calling Process2. Process1 should call VCancelEvents before exiting. After returning from Process2, if Process1 still needs events it should call VSelectEvents.

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.

2.4 Color and Overlay

X allows associating with image intensity values in the DISPLAY data appropriate gray or color values that determine how an intensity value is displayed. This association is done via a color map. A colormap consists of a set of color cells each of which has a gray or color value assigned to it which can be modified. Based on the nature of the flexibility allowed in mapping the color values, X groups display devices into six categories called visual classes :
		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.

2.5 Error Handling

Most of the functions in the three interfaces have return values. If a function encounters a fatal error, the function will write the error message to the standard error stream, the control will exit from 3DVIEWNIX to the UNIX shell, and a core dump file will be produced. If the error is not fatal, the function returns an error code. The meaning of error codes for the 3DVIEWNIX environment is listed in Appendix A. The function VDecodeError enables interpreting the error and writing the error message into 3DVIEWNIX error message file called 3DVIEWNIX.ERR under the current user directory. There are certain kinds of errors in 3DVIEWNIX which are reported to the user in the dialog window message area. When these errors are encountered a bell is sounded and the message flashed in the dialog window. Functions encountering non-fatal errors do not return a value.

2.6 Files

Apart from the files that contain SCENE, STRUCTURE and DISPLAY data which form the input/output files, there are two types of files in 3DVIEWNIX related to the various interface functions. The first type represents the fixed files such as the specification files that are present at all times. The second type represents files that are generated during a 3DVIEWNIX session. Their main purpose is communication of information between processes. These files have been explained in Appendix C.

In this manual all interface function names have V as a prefix (for VIEWNIX) and the names are fully spelled out.


Note:

  1. Colormap : It is created in VCreateWindows but installed in VCreateColormap. This is done because some servers will not let us create more than one colormap. Some servers require the colormap to be created before the windows are created.
  2. Menu : All nodes in a level can be horizontal only if one of the items has a vertical or horizontal menu underneath it.
  3. rint : has been redefined in 3DVIEWNIX header files. Any program that includes math.h should do so before including the 3DVIEWNIX library.
  4. Pixmap : 3DVIEWNIX library avoids using temporary memory like pixmap as much as possible. Most of the time, the windows, tablets and buttons are refreshed by calling refresh functions within the 3DVIEWNIX library. However there is a pixmap associated with the dialog window. When the dialog window is unmapped, the contents of the dialog window are written to a pixmap. Similarly when the dialog is mapped again, the contents of the pixmap are written back to the window. If the pixmap cannot be created, a proper error code is returned.