This appendix discusses the following output devices and window systems that are supported by PV-WAVE.

Supported Output Devices and Window Systems

Device Name	See Page	Description
NULL	N/A	No graphic output
CGM	B-6	Computer Graphics Metafile generator
HP	B-8	Hewlett-Packard Graphics Language (HPGL) plotters
PCL	B-14	Hewlett-Packard Printer Control Language (PCL)
PM	B-18	Pixel Map output
PS	B-20	PostScript devices
REGIS	B-33	Regis graphics output devices
TEK	B-35	Tektronix or compatible terminals
WIN32	B-38	Microsoft Windows WIN32 driver
WMF	B-53	Windows Metafile
X	B-58	X Window System
Z	B-86	Z-buffer device

Window System Features

PV-WAVE utilizes the native window system by creating and using one or more largely independent windows, each of which can be used for the display of graphics and/or images. One color table is shared among these windows. Up to 32 separate windows can be active at any time. Windows are referenced using their index, which is an integer value between 0 and 31.

"Dithering" or halftoning techniques are used to display images with multiple shades of gray on monochrome displays displays that can only display white or black. This topic is discussed in the PV-WAVE User's Guide.

Graphic and image output is always directed to the current window. When a window system is selected as the current graphics device, the index number of the current window is found in the !D.Window system variable. This variable equals -1 if no window is open or selected. The WSET procedure is used to change the current window. WSHOW hides or displays a window. WDELETE deletes a window.

The WINDOW procedure creates a new window with a given index. If a window already exists with the same index, it is first deleted. The size, position, title, and number of colors may also be specified. If you access the display before creating the first window, PV-WAVE automatically creates a window with an index number of 0 and with the default attributes.

One of the features that distinguishes various window systems is how they handle the issue of backing store. When part of a window that was previously not visible is exposed, there are two basic approaches that a window system can take. Some keep track of the current contents of all windows and automatically repair any damage to their visible regions (retained windows). This saved information is known as the backing store. Others simply report the damage to the program that created the window and leave repairing the visible region to the program (non-retained windows). There are convincing arguments for and against both approaches. It is generally more convenient for PV-WAVE if the window system handles this problem automatically, but this often comes at a performance penalty. The actual cost of retained windows varies between systems and depends partially on the application.

The X Window and Microsoft Windows systems do not by default keep track of window contents. Therefore, when a window on the display is obscured by another window, the contents of its obscured portion is lost.

The window system drivers allow you to control backing store using the Retain keyword to the DEVICE and WINDOW procedures. Using Retain with DEVICE allows you to set the default action for all windows, while using it with WINDOW lets you override the default for the new window. The possible values for this keyword are summarized in the following table, and are described in greater detail following the table.

0 A value of 0 specifies that no backing store is kept. In this case, exposing a previously obscured window leaves the missing portion of the window blank. Although this behavior can be inconvenient, it usually has the highest performance because there is no need to keep a copy of the window contents.

1 (The Default) Setting the Retain keyword to 1 causes PV-WAVE to request that a backing store be maintained. If the window system decides to accept the request, it automatically repairs the missing portions when the window is exposed. X Windows may or may not, depending on the capabilities of the server and the resources available to it.

2 Specifies that PV-WAVE should keep a backing store for the window itself, and repair any window damage when the window system requests it. This option exists mainly for the X Window System. Under X, a pixmap (off-screen display memory) the same size as the window is created at the same time the window is created, and all graphics operations sent to the window are also sent to the pixmap. When the server requests PV-WAVE to repair freshly exposed windows, this pixmap is used to fill in the missing contents. Pixmaps are a precious resource in the X server, so backing pixmaps should only be requested for windows with contents that must absolutely be preserved.

If the type of backing store to use is not explicitly specified using the Retain keyword, PV-WAVE assumes Option 1 and requests the window system to keep a backing store.

xinit -- -bs -fn fixed 

CGM Output

Computer Graphics Metafile, or CGM, is a standard for storing graphics output. To direct graphics output from PV-WAVE to a CGM file, enter the command:

SET_PLOT, 'CGM'

This causes PV-WAVE to use the CGM driver for producing graphical output, including line plots, contour plots, surface plots, and raster images. Once the CGM driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling CGM Output with DEVICE Keywords on page -6. The default settings for the CGM driver are listed in the following table:

The CGM driver supports clear text and binary CGM output. To see the driver's current settings, enter:

INFO, /Device 

---

TIP: Run the MSWORD_CGM_SETUP procedure before importing a CGM file into Microsoft Word. For example:

---

      SET_PLOT, 'CGM' 
      DEVICE, File='myplot.cgm' 
      MSWORD_CGM_SETUP 
      PLOT, dist(20) 
      DEVICE, /Close 

The following keywords to the DEVICE procedure provide control over the CGM driver:

Clip Specifies that all coordinates will be reduced to fit within the VDC coordinate range. This keyword is primarily used with the Xoffset and Yoffset keywords to protect the metafile from containing coordinates which are outside the range of the VDC system.

Close Closes the current CGM output file.

Colors Specifies the number of colors in the color table. Be sure to specify the number of colors in the color table before any graphics output is written to the file.

Ct_Offset Specifies the location (or offset) of the first element in the color table. As with the Colors keyword, this value should be specified before any graphics output is written to the file.

Filename Specifies the name of the CGM output file to be opened. If the keyword is not specified, the default name wave.cgm is used.

Index_From_Zero If nonzero, maps the PV-WAVE colortable indices directly to the CGM color table indices. That is, the indices are mapped 0-0, 1-1, and so on. By default, the PV-WAVE to CGM color indices are mapped 0-1, 1-2, and so on. This keyword disables the Color and Ct_Offset keywords.

Metafile_Type Specifies the metafile type. Options are clear_text and binary. The default value is clear_text. The binary type is machine-specific and is more difficult to transfer.

Scale_Factor Includes a floating-point value in the metafile for the Scale Mode Metric command. This allows for CGM interpreters to scale the graphics output appropriately for "exact sizing". The metric scale-factor represents the distance (in millimeters) in the displayed picture this corresponds to one VDC unit.

Std_Cell_Array Specifies that images created with the binary output (CELL_ARRAY commands) are compliant with the CGM standard. Std_Cell_Array is enabled by default. Disabling this keyword may result in some non-standard cell array commands for odd-sized images. The non-standard cell array option is provided for downward compatibility.

Xoffset Specifies the number of horizontal coordinate units to offset the graphics output. Xoffset is specified by a positive normalized coordinate in the range {0.0...1.0}.

Yoffset Specifies the number of vertical coordinate units to offset the graphics output. Yoffset is specified by a positive normalized coordinate in the range {0.0...1.0}.

The CGM output file is automatically opened when the CGM driver is selected and PV-WAVE commands are issued that result in graphics output; there is no explicit OPEN command. If more than one CGM file is to be created, use the following command sequence:

SET_PLOT, 'CGM'

; Select the CGM driver for graphics output.

DEVICE, Filename='filename1'

; Open the first file.

...

; Graphics output commands here.

DEVICE, /Close

; Close the first file.

DEVICE, Filename='filename2'

; Open another file.

...

; Graphics output commands here.

DEVICE, /Close

; Close the second file, etc.

Note also that color table changes should be made every time a new CGM file is opened. In the absence of changes, the new CGM file contains the default color table, rather than the current color table.

To create and load a color table with four elements, black, red, green, and blue:

TVLCT, [0,255,0,0], [0,0,255,0], [0,0,0,255]

Drawing text or graphics with a color index of 1 results in black, 2 in red, 3 in green, and 4 in blue.

Images that are displayed with a black background on a monitor frequently look better in hardcopy form if the background is changed to white. This is easily accomplished with CGM output by issuing the statement, where A is the image variable:

A(WHERE(A EQ 0B)) = 255B

Changing the CGM Background Color

To set the background color for a CGM metafile, use the ERASE command with a color index. The index is used to define the background color. For example:

ERASE, 150

Binary CGM output is written to a fixed-length file with a record length of 512 bytes. To display the CGM metafile with Visual Numerics' VAX/OpenVMS Extended Metafile System, provide the CGM metafile filename in quotes followed by format 2, record 512.

For example,

CGM set metafile "cgmfile" format 2 record 512
CGM interpret

HPGL Output

HPGL (Hewlett-Packard Graphics Language) is a plotter control language used to produce graphics on a wide family of pen plotters.

To use HPGL as the current graphics device, issue the command:

SET_PLOT, 'HP'

This causes PV-WAVE to use HPGL for producing graphical output. Once the HPGL driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling HPGL Output with DEVICE Keywords on page -9. The default settings for the HPGL driver are given in the following table:

Use the statement:

INFO, /Device

to view the current HPGL driver settings.

The following keywords to the DEVICE procedure provide control over the HPGL driver:

Close_File PV-WAVE creates, opens and writes a file containing the generated graphics output. The Close_File keyword outputs any buffered commands and closes the file.

Eject In order to perform an erase operation on a plotter, it is necessary to remove the current sheet of paper and load a fresh sheet. The ability of various plotters to do this varies, so the Eject keyword allows you to specify what should be done. The following table gives the possible values:

Many HPGL plotters lack a sheet feeder, and require you to load the next page manually. Therefore, the default action is for PV-WAVE to not issue any page eject instructions. In this case, you must restrict yourself to generating only a single plot at a time.

If your plotter has a sheet feeder, you need to issue the command:

DEVICE, /Eject

to tell PV-WAVE that it should use the sheet feeder instead of placing the plotter off-line. If your plotter does not have a sheet feeder, but it does understand the HPGL NR command, use the command:

DEVICE, Eject=2

to place the plotter off-line at the start of every plot except the first one. This causes the plotter to wait between plots for you to replace the paper. When you put the plotter back on-line, the graphics commands for the new page are executed by the plotter. Consult the programming manual for your plotter to determine if this instruction is provided.

Filename By default all generated output is sent to a file named wave.hp. The Filename keyword can be used to change this default. If you specify a filename, the following occurs:

• If the file is already open (as happens if plotting commands have been directed to the file since the call to SET_PLOT), then the file is completed and closed as if Close_File had been specified.

• The specified file is opened for subsequent graphics output.

Inches By default, the Xoffset, Xsize, Yoffset, and Ysize keywords are specified in centimeters. However, if Inches is present and nonzero, these keywords are taken to be in inches instead.

Landscape PV-WAVE normally generates plots with portrait orientation (the x-axis is along the short dimension of the page). If Landscape is present, landscape orientation (the x-axis is along the long dimension of the page) is used instead.

Output Specifies a scalar string that is sent directly to the graphics output file without any processing, allowing you to send arbitrary commands to the file. Since PV-WAVE does not examine the string, it is your responsibility to ensure that the string is correct for the target device.

Polyfill Some plotters (e.g., HP7550A) can perform polygon filling in hardware, while others (e.g., HP7475) cannot. PV-WAVE therefore assumes that the plotter cannot, and generates all polygon operations in software using line drawing. Specifying a nonzero value for the Polyfill keyword causes PV-WAVE to use the hardware polygon filling. Setting it to zero reverts to software filling.

Different implementations of HPGL plotters may have different limits for the number of vertices that can be specified for a polygon region before the plotter runs out of internal memory. Since this limit can vary, the HPGL driver cannot check for calls to Polyfill that specify too many points. Therefore, it is possible for you to produce HPGL output that causes an error when sent to the plotter. To avoid this situation, minimize the number of points used. On the HP7550A, the limit is about 127 points. If you do generate output that exceeds the limit imposed by your plotter, you have to break that polygon filling operation into multiple smaller operations.

Plotter_On_Off There are some configurations in which an HPGL plotter is connected between the computer and a terminal. In this mode (known as eavesdrop mode), the plotter ignores everything it is sent and passes it through to the terminal the plotter is logically off. This state continues until an escape sequence is sent that turns the plotter logically on. At this point the plotter interprets and executes all input as HPGL commands. Another escape sequence is sent at the end of the HPGL commands to return the plotter to the logically off state.

Most configurations do not use eavesdrop mode, and the plotter is always logically on. However, if you are using this style of connection, you must use Plotter_On_Off to instruct PV-WAVE to generate the necessary on/off commands. If present and nonzero, Plotter_On_Off causes each output page to be bracketed by device control commands that turn the plotter logically on and off. Specifying a value of zero stops the issuing of such commands. You should only use this keyword before any output has been generated.

Portrait If Portrait is present, PV-WAVE generates plots using portrait orientation, the default.

Xoffset Specifies the x position on the page of the lower-left corner of output. Xoffset is specified in centimeters unless Inches is specified. (In some cases, offset is taken from the origin. See the Note at the end of this section for details.)

Xon_Xoff If present and nonzero, Xon_Xoff causes each output page to start with device control commands that instruct the plotter to obey xon/xoff (^S/^Q) style flow control. Specifying a value of zero stops the issuing of such commands. You should only use this keyword before any output has been generated. Such handshaking is the default. To turn it off, use the command:

DEVICE, Xon_Xoff=0

Often, it is not necessary to tell the plotter to obey flow control because the printing facilities on the system handle such details for you, but it is usually harmless.

Xsize Specifies the width of output PV-WAVE generates. Xsize is specified in centimeters unless Inches is specified.

Yoffset Specifies the y position on the page of the lower-left corner of output generated by PV-WAVE. Yoffset is specified in centimeters unless Inches is specified. (In some cases, offset is taken from the origin. See the Note following the keyword descriptions for details.)

Ysize Specifies the height of output generated by PV-WAVE. Ysize is specified in centimeters unless Inches is specified.

If you are plotting to an HP plotter in the series 757X, 758X, and 759X, you will need to specify the Xoffset and Yoffset from the origin instead of the lower-left corner of output. Because the default values for Xoffset and Yoffset are assume a lower-left corner origin, you will have to set these keywords to appropriate values whenever plotting to one of the above listed plotters. For example, to center a plot, use the following equations to find the offsets:

Xoffset = -(Xsize/2)
Yoffset = -(Ysize/2)

where Xsize and Ysize are the width and height, respectively, of the plot to be generated.

PV-WAVE is able to produce a wide variety of graphical output using HPGL.

Here is a list of what is supported:

• All types of vector graphics can be generated, including line plots, contours, surfaces, etc.

• HPGL plotters can draw lines in different colors selected from the pen carousel. It should be noted that color tables are not used with HPGL. Instead, each color index refers directly to one of the pens in the carousel.

• Some HPGL plotters can do polygon filling in hardware. Others can rely on the software polygon filling provided by PV-WAVE.

• It is possible to generate graphics using the hardware-generated text characters, although such characters do not give much improvement over the standard software fonts. To use hardware characters, set the !P.Font system variable to zero, or set the Font keyword to the plotting routines to zero. For more information on fonts, see the PV-WAVE User's Guide.

• Here is a list of what is not supported:

• Since HPGL is designed to drive pen plotters, it does not support the output of raster images. Therefore the TV and TVSCL procedures do not work with HPGL.

• Since pen plotters are not interactive devices, they cannot support such operations as cursors and windows.

The Linestyle graphics keyword allows you to specify any of 6 linestyles. This keyword is documented in Chapter 3, Graphics and Plotting Keywords.

HPGL is not able to support all of the standard PV-WAVE linestyles. The following table summarizes the differences between the PV-WAVE linestyles and those supported by HPGL.

HPGL Supported Linestyles

Index	Normal Line Style	HPGL Style
0	Solid	same
1	Dotted	same
2	Dashed	same
3	Dash Dot	The relative size of the dash and dot are different.
4	Dash Dot Dot Dot	Dash Dot Dot
5	Long Dashes	same

tr -d '/012' wave.hp   newwave.hp 

PCL Output

PCL (Printer Control Language) is used by Hewlett-Packard laser and ink jet printers to produce graphics output. This driver does not support the use of color and does not support the use of hardware fonts.

To direct graphics output to a PCL file, issue the command:

SET_PLOT, 'PCL'

This causes PV-WAVE to use the PCL driver for producing graphical output. Once the PCL driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling PCL Output with DEVICE Keywords on page -15. The default settings for the PCL driver are given in the following table:

By default, PCL writes black on white paper. The default color index when PCL is selected is 0. If the color index is set to 255 when PCL is selected, the result is white writing on white, which is invisible on white paper. Color tables are not used with PCL.

Use INFO, /Device to view the driver's current settings.

lpr -Plj250_q -v wave.pcl

PRINT /QUEUE=LJ250_Q /PASSALL WAVE.PCL

The following keywords to the DEVICE procedure provide control over the PCL driver:

Close_File PV-WAVE creates, opens and writes a file containing the generated graphics output. The Close_File keyword outputs any buffered commands and closes the file.

Filename By default all generated output is sent to a file named wave.pcl. The Filename keyword can be used to change this default. If you specify a filename, the following occurs:

• If the file is already open (as happens if graphics have been directed to the file since the call to SET_PLOT), then the file is completed and closed as if Close_File had been specified.

• The specified file is opened for subsequent graphics output.

Floyd If present and nonzero, selects the Floyd-Steinberg method of dithering. For information on this dithering method, see the PV-WAVE User's Guide.

Inches By default, the Xoffset, Xsize, Yoffset, and Ysize keywords are specified in centimeters. However, if Inches is present and nonzero, they are taken to be in inches instead.

Landscape PV-WAVE normally generates plots with portrait orientation (the x-axis is along the short dimension of the page). If Landscape is present, landscape orientation (the x-axis is along the long dimension of the page) is used instead.

Optimize It is desirable, though not always possible, to compress the size of the output file. Such optimization reduces the size of the output file, and improves I/O speed to the printer. There are three levels of optimization:

• 0 No optimization is performed. This is the default because it will work with any PCL device. However, users of devices which can support optimization should use one of the other optimization levels.

• 1 Optimization is performed using PCL optimization primitives. This gives the best output compression and printing speed. Unfortunately, not all PCL devices support it. On those that can't, the result will be garbage printed on the page.

The required sequences are: ESC*b0M (Select full graphics mode), ESC*b1M (Select compacted graphics mode 1), and ESC*b2M (Select compacted graphics mode 2). To determine if your printer supports the required escape sequences, consult the programmers manual for the device.

The HP LaserJet II does not support this optimization level. The DeskJet PLUS does.

• 2 PV-WAVE attempts to optimize the output by explicitly moving the left margin and then outputting non-blank sections of the page. This is primarily intended for use with the LaserJet II, which does not support optimization level 1.

Ordered Selects the Ordered Dither method of dithering when displaying images on a monochrome display. For information on this dithering method, see the PV-WAVE User's Guide.

Pixels By default, the Xoffset, Xsize, Yoffset, and Ysize keywords are specified in centimeters. However, if Pixels is present and nonzero, they are taken to be in pixels instead. Note that the selected resolution will determine how large a region is actually written on the page.

Portrait If Portrait is present, PV-WAVE will generate plots using portrait orientation, the default.

Resolution The resolution at which the PCL printer will print. PCL supports resolutions of 75, 100, 150, and 300 dots per inch. The default is 300 dpi. Lower resolution gives smaller output files, while higher resolution gives superior quality.

Threshold Specifies use of the threshold dithering algorithm. For information on this dithering method, see the PV-WAVE User's Guide.

Xoffset Specifies the x position on the page of the lower-left corner of output generated by PV-WAVE. Xoffset is specified in centimeters unless Inches or Pixels is specified.

Xsize Specifies the width of the PV-WAVE output. Xsize is specified in centimeters unless Inches or Pixels is specified.

Yoffset Specifies the y position on the page of the lower-left corner of output generated by PV-WAVE. Yoffset is specified in centimeters unless Inches or Pixels is specified.

Ysize Specifies the height of the PV-WAVE output. Ysize is specified in centimeters unless Inches or Pixels is specified.

Images that are displayed with a black background on a monitor frequently look better if the background is changed to white when displayed with PCL. This is easily done with the following statement, where A is the image variable:

A(WHERE(A EQ 0B)) = 255B

Pixel Map Output

The Pixel Map buffer allows you to create PV-WAVE graphical output in memory. This output buffer is useful for creating images using batch mode methods or background processes.

To direct graphics output to the PM buffer, enter the command:

SET_PLOT, 'PM'

This causes PV-WAVE to use the PM buffer driver for producing graphical output. Once the PM buffer driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling PM buffer Output with DEVICE Keywords on page -18.

Use INFO, /Device to view the driver's current settings.

The following keywords to the DEVICE procedure provide control of the PM buffer driver:

Close Deallocates the memory used by the buffers. The PM buffer device is reinitialized if subsequent graphics operations are directed to the device.

Get_Graphics_Function See the description of the Get_Graphics_Function keyword in X Window System on page -58.

Get_Write_Mask See the description of the Get_Write_Mask keyword in X Window System on page -58.

Set_Character_Size A two-element vector that changes the standard width and height of the vector-drawn fonts. The first element in the vector contains the new character width, and the second element contains the height. By default, characters are approximately 8-pixels wide, with 12 pixels between lines.

Set_Colors Sets the number of pixel values, !D.N_Colors. This value is used by a number of routines to determine the scaling of pixel data and the default drawing index. Allowable values range from 2 to 256, and the default value is 256. Use this parameter to make the PM buffer device compatible with devices with fewer than 256 color indices. The number of colors can be changed at any time without affecting any accumulated graphics present in the buffer (it does not delete the current buffer).

Set_Graphics_Function See the description of the Set_Graphics_Function keyword in X Window System on page -58.

The PM buffer allows you to use all graphics functions supported by the X driver.

Set_Resolution Two-element vector that sets the width and height of the buffers. The default size is 640-by-512. If this size is not the same as the existing buffers, the current buffers are destroyed and the device is reinitialized.

Set_Write_Mask See the description of the Set_Write_Mask keyword in X Window System on page -58.

SET_PLOT,'PM' 

; Switch output to the PM buffer.

DEVICE, Set_Resolution = [256,256], $

Set_Colors=128

; Make a 256x256 buffer with 128 colors.

LOADCT, 15 

; Load a color table.

SHADE_SURF, data 

; Make a plot.

TVLCT, r, g, b, /Get 

; Get the color table RGB values.

cmap =TRANSPOSE([[r],[g],[b]])

; Put RGB values into a colormap array.

imgarr = TVRD() 

; Read the image from the PM buffer.

stat = IMAGE_WRITE('output.gif', $

IMAGE_CREATE(imgarr, Colormap=cmap))

; Write the image and colormap to a GIF file.

DEVICE, /Close 

; De-allocate memory used by the device.

PostScript Output

PostScript is a programming language designed to convey a description of virtually any desired page containing text and graphics. It is widely available on laser printers and typesetters.

To direct graphics output to a PostScript file, enter the command:

SET_PLOT, 'PS'

This causes PV-WAVE to use the PostScript driver for producing graphical output. Once the PostScript driver is enabled via SET_PLOT, the DEVICE procedure controls its actions, as described in Controlling PostScript Output with DEVICE Keywords on page -22. The default settings for the PostScript driver are given in the following table.

Postscript Driver Default Settings

Setting	Default Value
Output file name	wave.ps
Mode	portrait, non-encapsulated, no color
Paper	letter
Horizontal offset	1.905 cm (3/4 in.)
Vertical offset	12.7 cm (5 in.)
Width	17.78 cm (7 in.)
Height	12.7 cm (5 in.)
Scale factor	1.0
Font size	14 pt.
Font	Times Roman
bits / image pixel	4

---

NOTE: All PostScript printers impose a limit on the number of vertices a polygon may contain. This limit (750 vertices for most printers) is checked, and an error message is printed if it is exceeded.

---

The following text formatting commands are new and can be used with the PostScript, WIN32, WMF, and X drivers:

Formatting Command	Description
!FB	Switch to the bold face of the current font.
!FI	Switch to the italic face of the current font.
!FU	Underline the current font.
!FN	Switch to the normal form of the current font.
!Pxx	Switch to point size xx of the current font, where xx is a two digit integer (01-99).

Refer to the PV-WAVE User's Guide for a comprehensive list of text formatting commands.

The following keywords to the DEVICE procedure provide control over the PostScript driver:

PostScript fonts are selected using DEVICE keywords. For example:

DEVICE, /Helvetica, /Bold

See Using PostScript Fonts on page -27 for a complete list of these keywords.

Bits_Per_Pixel PV-WAVE is capable of producing PostScript images with 1, 2, 4, or 8 bits per pixel. Using more bits per pixel gives higher resolution at the cost of generating larger files. Bits_Per_Pixel is used to specify the number of bits to use. The default number of bits is four.

The Apple Laserwriter is capable of only 32 different shades of gray (which can be represented by 5 bits). Thus, specifying 8 bits per pixel does not give 256 levels of gray as might be expected, only 32, at a cost of sending twice the number of bits to the printer. Often, 4 bits (16 levels of gray) will give acceptable results with a large savings in file size.

Close_File PV-WAVE creates, opens and writes a file containing the generated graphics output. The Close_File keyword outputs any buffered commands and closes the file.

Color Enables color PostScript output if present and nonzero. For details on using color PostScript devices see Using Color PostScript Devices on page -29.

Encapsulated Specifies that the PostScript produced by PV-WAVE is to be included in another PostScript document, such as one produced by T_EX, LAT_EX, FrameMaker, Microsoft Word, or Ventura Publisher.

By default PV-WAVE assumes that its PostScript-generated output will be sent directly to a printer. It therefore includes PostScript commands to center the plot on the page and to eject the page from the printer. These commands are undesirable if the output is going to be inserted into the middle of another PostScript document. If Encapsulated is present and nonzero, PV-WAVE does not generate these commands.

PV-WAVE follows the standard PostScript convention for encapsulated files. It assumes the standard PostScript scaling is in effect (72 points per inch). In addition, it declares the size, or bounding box, of the plotting region at the top of the output file. This size is determined when the output file is opened (when the first graphics command is given) by multiplying the size of the plotting region (as specified with the Xsize and Ysize keywords) by the current scale factor (as specified by the Scale_Factor keyword). Changing the size of the plotting region or scale factor once any graphics have been output will not be reflected in the declared bounding box, and will confuse programs that attempt to import the resulting graphics. Therefore, when generating encapsulated PostScript do not change the plot region size of scaling factor after issuing graphics commands. If you want to change these parameters, use the Filename keyword to start a new file.

To explicitly disable the encapsulated PostScript option, use DEVICE, encaps=0.

Epsi Produces an output file in encapsulated PostScript interchange (EPSI) format. When the Epsi keyword is present and nonzero, the Encapsulated keyword is automatically assumed. For detailed information on the Encapsulated keyword, see the description given previously in this section.

Like normal encapsulated PostScript files, EPSI files can be imported into many desktop publishing and word processing systems; however, EPSI format provides a previewing capability that allows an approximation of the printed PostScript output to be displayed on the screen. Previewed EPSI graphics are displayed in monochrome only.

---

TIP: EPSI images sometimes appear differently when printed than they do in windows on the screen. This occurs because the driver's EPSI bitmap size is fixed no matter what the size of the original PV-WAVE image, and the PV-WAVE image is scaled into this bitmap. In addition, printed PostScript files can take advantage of scalable pixels, while pixels on the screen are static. Try experimenting with the other DEVICE keywords when you specify /Epsi to see which combination gives the best results with your particular size image. The driver's EPSI bitmap size (888-by-635 pixels) works well in many cases.

---

Filename By default all generated output is sent to a file named wave.ps. The Filename keyword can be used to change this default. If you specify a filename, one or both of the following actions occur:

• If the file is already open (as happens if plotting commands have been directed to the file since the call to SET_PLOT), then the file is completed and closed as if Close_File had been specified.

• The specified file is opened for subsequent graphics output.

Font_Size Specifies the default height used for displayed text. Font_Size is given in points (a common unit of measure used in typesetting). The default size is 12 point text.

Get_Fontmap Returns a list of the current font map settings. If /Get_Fontmap is specified, the information is printed to the screen. If a variable name is specified (e.g., Get_Fontmap=varname), a string array is returned.

The information returned by Get_Fontmap is in the same form as the strings specified with Set_Fontmap. The only exception to this pattern is that the first string returned in a string array is labeled as font 0 and is the current default font.

Inches By default, the Xoffset, Xsize, Yoffset, and Ysize keywords are specified in centimeters. However, if Inches is present and nonzero, they are taken to be in inches instead.

Landscape PV-WAVE normally generates plots with portrait orientation (with the x-axis along the short dimension of the page). If Landscape is present, landscape orientation (with the x-axis is along the long dimension of the page) is used instead.

Output Specifies a scalar string that is sent directly to the graphics output file without any processing, allowing you to send arbitrary commands to the file. Since PV-WAVE does not examine the string, it is your responsibility to ensure that the string will be recognized by the target device.

Papername Specifies the size of paper to be used for printing. If you set the keyword value to `Letter', then standard 8.5x11-inch paper is used; `tabloid' is 11x17-inch paper (Default: `Letter')

Path_Points Lets you change the maximum number of points in any PostScript path. The PostScript Language Reference Manual defines this limit as "Maximum number of points specified in all active path descriptions, including the current path, clip path, and paths saved by save and gsave". The default value is 750 because that is the maximum that some printers can handle. The PostScript Language Reference Manual states that 1500 is a typical limit for Level 1 implementations. The maximum for any particular printer can depend on the PostScript implementation being used, the amount of memory in the printer itself and other software being used to access the printer. If you set Path_Points to a number larger than the default and your printer reports a PostScript memory error, then reduce the Path_Points number.

Portrait If Portrait is present, PV-WAVE generates plots using portrait orientation (the default).

Scale_Factor Specifies a scale factor applied to the entire plot. Its default value is 1.0, allowing output to appear at its normal size. Scale_Factor magnifies or shrinks the resulting output.

Set_Fontmap Associates specific font characteristics with a particular hardware font command. This keyword can be used to specify a single string containing the information for one font, or an array of strings containing the information for multiple fonts.

For example, to associate 16 point Helvetica italic with font command !5, use the following DEVICE call:

DEVICE, Set_Fontmap='5 Helvetica-Oblique, 16'

Now, whenever the !5 font command appears in a text string, the text output appears in 16 point Helvetica italic. This keyword only affects hardware fonts (that is, when !P.Font=0).

User_Font A scalar string that gives the name of a PostScript font to use. This font name must be specified exactly as the PostScript interpreter expects it, with the correct case and spelling. User_Font lets you use fonts not known to PV-WAVE.

Xoffset Specifies the x position on the page of the lower-left corner of output generated by PV-WAVE. By default, Xoffset is specified in centimeters unless the Inches keyword is specified. Scale_Factor does not affect the value of Xoffset.

Xsize Specifies the width of output. By default, Xsize is specified in centimeters unless the Inches keyword is specified Scale_Factor modifies the value of Xsize. Hence, the statement:

DEVICE, /Inches, Xsize=7.0, Scale_Factor=0.5

results in a real width of 3.5 inches.

Yoffset Specifies the y position on the page of the lower-left corner of output generated by PV-WAVE. By default, Yoffset is specified in centimeters unless the Inches keyword is specified. Scale_Factor does not affect the value of Yoffset.

Ysize Specifies the height of output. By default, Ysize is specified in centimeters unless the Inches keyword is specified. Scale_Factor modifies the value of Ysize. Hence, the statement:

DEVICE, /Inches, Ysize=5.0, Scale_Factor=0.5

results in a real width of 2.5 inches.

By default, PV-WAVE uses software characters for annotating plots (i.e., !P.Font is -1). These characters are of good quality and are extremely flexible. However, if this flexibility is not required, higher quality characters are available via PostScript fonts. In order to get PV-WAVE to use the PostScript fonts, do one of the following:

• Set !P.Font to 0 by entering:

!P.Font = 0

• Use the Font keyword with the plotting and graphics procedures to specify font 0. For example:

PLOT, temps, Title='Average Temp', Font=0

The default PostScript font is 12-point Helvetica. To change this font, use the DEVICE procedure keywords, as shown in the following table. Note that not all fonts may be available on a particular device.

When using PostScript fonts, commands may be inserted into the text in order to specify positioning and special characters. These commands are described in the following table. They are similar to the commands provided for the standard software characters.

PostScript Text Positioning Commands

Command	Description
!A	Shift above the division line.
!E	Shift up to the exponent level and decrease the character size by a factor of 0.44.
!MX	Insert a bullet character.
!N	Shift back to the normal level and original character size.
!B	Shift below the division line.
!I	Shift down to the index level and decrease the character size by a factor of 0.44.
!!	Display the ! symbol.

If you have a color PostScript device you can enable the use of color with the statement:

DEVICE, /Color

Enabling color also enables the color tables. Text and graphic color indices are translated to RGB by dividing the red, green, and blue color table values by 255. As with most display devices, color indices range from 0 to 255. Zero is normally black and white is normally represented by an index of 255.

As with black and white PostScript, images may be output with 1, 2, 3, 4 or 8 bits, yielding 1, 2, 16, or 256 possible colors. In addition, images can be either pseudo-color or true color. For a thorough comparison of pseudo-color and true color, see the PV-WAVE User's Guide.

Images that are displayed with a black background on a monitor frequently look better if the background is changed to white when displayed with PostScript. This is easily done with the following statement, where A is the image variable:

A(WHERE(A EQ 0B)) = 255B

The combination of PV-WAVE and the PostScript page description language gives you a powerful tool for creating publication-quality documents with text, graphics, and images arranged together on the page. Three examples of how to insert PostScript output into text documents follow, but these are not exclusive. Consult your word processing or desktop publishing manual to see how your software handles encapsulated PostScript files.

Inserting PV-WAVE Plots into LATEX Documents

LAT_EX is a special version of the T_EX page formatting language developed by Donald E. Knuth for producing publication-quality documents. LAT_EX was developed by Leslie Lamport to make the T_EX language easier to use. Although T_EX is released into the public domain, commercial versions of T_EX are supported by private vendors. One such vendor is ArborText, Inc., of Ann Arbor, Michigan. The examples below describe how Visual Numerics has used ArborText's T_EX, LAT_EX, and DVILASER/PS software on Sun workstations to incorporate PV-WAVE graphs and images into publication-quality documents.

Figure B-2 is an example of a PV-WAVE-generated PostScript plot that has been inserted into a LAT_EX document. It was produced with the following statements:

SET_PLOT, 'PS'

; Select the PostScript driver.

DEVICE, /Encapsulated, Filename='pic1.ps'

; Use ENCAPSULATED because output is for use with LATEX.

x = FINDGEN(200)
PLOT, 10000 * SIN(x/5) / EXP(x/100), $
    Linestyle=2, Title='PV-WAVE ' + $
    'PostScript plot', Xtitle='Point Number', $
    Ytitle='Y Axis Title', Font=0

; Plot the sine wave. Set the font to hardware font.

OPLOT, 10000 * COS(x/5) / EXP(x/100), Linestyle=4

; Add the cosine.

XYOUTS, 100, -6000, 'Sine', Font=0 

; Annotate the plot.

OPLOT, [120, 180], [-6000, -6000], Linestyle=2

; Annotate the plot

XYOUTS, 100, -8000, 'Cosine', Font=0

; Annotate the plot

OPLOT, [120, 180], [-8000, -8000], Linestyle=4

Note the use of the Encapsulated keyword in the call to DEVICE. This is what allows you to import the file into a LAT_EX document. Simply omit the Encapsulated keyword from the call to DEVICE if you want to produce a plot that can be printed directly.

Any kind of PostScript plot can be included in LAT_EX documents. In Figure B-3, a PV-WAVE PostScript image has been included. In this case, the same image is reproduced four times. Each time, a different number of bits are used per image pixel. The illustration was produced with the following statements:

SET_PLOT, 'PS'
DEVICE, /Encapsulated, Filename='pic4.ps'
OPENR, 1, !Dir+'/data/mandril.img'

; Open image file.

a = BYTARR(256, 256, /Nozero)

; Variable to hold image.

READU, 1, a

; Input the image.

CLOSE, 1

; Done with the file.

FOR i = 0,3 DO BEGIN

; Output the image four times.

DEVICE, Bits_Per_Pixel=2^i

; Use 1, 2,4, and 8 bits per pixel.

TV,a,i ,Xsize=2.5, Ysize=2.5, /Inches

; Output using TV with position numbers 0, 1, 2, and 3.

ENDFOR

The LAT_EX Insertplot Macro

The following LAT_EX macro, named insertplot, is used to insert PV-WAVE-generated PostScript files into LAT_EX documents. The definition of this macro depends upon the T_EX DVI to PostScript translation program used and is therefore not portable between various DVI programs.

However, given familiarity with T_EX it is relatively easy to modify the macro to suit the various DVI programs encountered in practice. The insertplot macro is as follows:

% Insert a PostScript plot made by 
% PV-WAVE into a LATEX document: 
% For the ArborText program dvips.
%
% This macro creates a captioned figure
% of the specified size and uses the 
% \special command to insert the Post
% Script.
%
% Usage: \insertplot{file}{caption}
% {label}{width}{height} 
% file = name of file containing the PostScript.
% caption = caption of figure
% label = latex \label{} for figure to
% be used by \ref{} macro.
% width = width of figure, in inches.
% height = height of figure, in inches.
% 
% Insert a plot.
\newcommand{\insertplot}[5]{%
% Usage: \insertplot{file}{caption}
% {label}{width in inches}{height}
\begin{figure}%
\hfill\hbox to 0.05in{\vbox to #5in{\vfil%
\inputplot{#1}{#4}{#5}%Include the plot
% file 
}\hfill}%
\hfill\vspace{-.1in}% Fudge factor to 
% tighten things up a bit. 
\caption{#2}\label{#3}
\end{figure}}
%
%
%	Include a PostScript File, this varies 
%	according to the DVI program: Usage:
%	\inputplot{filename}{width}{height}
%	When called from insertplot, the current
%	position is at the bottom CENTER of the
%	figure box.
\newcommand{\inputplot}[3]{%
%	Output PostScript commands to scale 
%	default sized (7 wide by 5 high) PV-WAVE
%	plot into the specified size. Also
%	set origin to the current point less
%	half the width of the box, centering the
%	box above the current point.
\special{ps:: gsave #2 -36 mul 0 rmoveto 
currentpoint translate #2 7.0 div #3 5.0 
div scale}%
\special{ps: plotfile #1}\special{ps::
 grestore}}
%
%

Regis Output

PV-WAVE provides Regis graphics output for the Digital VT240, VT330, and VT340 series of terminals. To output graphics to such terminals, enter the command:

SET_PLOT, 'REGIS'

This causes PV-WAVE to use the Regis driver for producing graphical output. Once the Regis driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in the next section, Controlling Regis Output with DEVICE Keywords.

The following keywords to the DEVICE procedure provide control over the Regis driver:

Average_Lines Controls the method of writing images to the VT240. If this keyword is set, as it is by default, even and odd pairs of image lines are averaged and written to a single line. If clear, each image line is written to the screen (see the discussion below).

This keyword has no effect when using a VT300 series terminal.

Close_File PV-WAVE creates, opens, and writes a file containing the generated graphics output. The Close_File keyword outputs any buffered commands and closes the file.

Filename By default all generated output is sent to a file named wave.regis. The Filename keyword can be used to change this default. When you specify a filename, the following occurs:

• If the file is already open (as happens if graphics have been directed to the file since the call to SET_PLOT), then the file is completed and closed as if Close_File had been specified.

• The specified file is opened for subsequent graphics output.

Plot_To Directs the Regis output that would normally go to the user's terminal to the specified I/O unit. The logical unit specified should be open with write access to a device or file.

Do not use the interactive graphics cursor when graphic output is not directed to your terminal. To direct the graphic data to both the terminal and the file, set the unit to the negative of the actual unit number. If the specified unit number is zero, then Regis output to the file is stopped.

Tty Directs output to both a file and the terminal.

VT240 Sets driver for VT240 series terminals.

VT241 Same as VT240.

VT340 Sets driver for VT340 series terminals (the default).

VT341 Same as VT340.

The default setting for Regis output is: VT340, 16 colors, 4 bits per pixel.

• Four colors are available with VT240 and VT241 terminals, sixteen colors are available with the VT330 and VT340.

• Thick lines are emulated by filling polygons. There may be a difference in linestyle appearance between thick and normal lines.

• Image output is slow and poor quality, especially on the VT240 series.

• The VT240 is only able to write pixels on even numbered screen lines. PV-WAVE offers two methods of writing images to the VT240:

Even and odd pairs of rows are averaged and written to the screen. An n, m image will occupy n columns and m screen rows. If this method is selected, graphics and image coordinates coincide. This method is the default: Average_Lines=1. Routines that rely on a uniform graphics and image coordinate system, such as SHADE_SURF, will only work in this mode.

Each line of the image is written to the screen, displaying every image pixel. An n, m image occupies 2m lines on the screen (Average_Lines=0). Graphics and image coordinates coincide only at the lower left corner of the image.

• Pixel values may not be read back from the terminal, rendering the TVRD function inoperable.

Tektronix Terminals

The Tektronix 4000 (4010, 4014, etc.), 4100 and 4200 series of graphics terminals (and the multitude of terminals and microcomputers that emulate them) are among the most common graphics devices available. To use PV-WAVE graphics with such terminals, enter the command:

SET_PLOT, 'TEK'

This causes PV-WAVE to use the Tektronix driver for producing graphical output.

The following keywords to the DEVICE procedure provide control over the Tektronix driver:

Colors The number of colors supported by the terminal. Only used with 4100 series terminals. For example, if your terminal has 4-bit planes, the number of colors is 2⁴ -16:

DEVICE, Colors=16

Valid values of this parameter are: 2, 4, 8, 16, or 64; other values cause problems. Some Tektronix terminals do not operate properly if this parameter does not exactly match the number of colors available in the terminal hardware.

This parameter sets the field !D.N_Colors, which affects the loading of color tables via the Standard Library procedures, the scaling used by the TVSCL procedure, and the number of bits output by the TV procedure to the terminal. It also changes the default color, !P. Color, to the number of colors minus one.

Gin_Chars The number of characters PV-WAVE reads when accepting a GIN (Graphics Input) report. The default is 5. If your terminal is configured to send a carriage return at the end of each GIN report, set this parameter to 6. If the number of GIN characters is too large, the CURSOR procedure will not respond until two or more keys are struck. If it is too small, the extra characters sent by the terminal will appear as input to the next PV-WAVE prompt.

Plot_To Directs the Tektronix graphic output that would normally go to the user's terminal to the specified I/O unit. The logical unit specified should be open with write access to a device or file. Save graphic output in files for later playback, redirection to other terminals, or to devices that accept Tektronix graphic commands.

Do not use the interactive graphics cursor when graphic output is not directed to your terminal. To direct the graphic data to both the terminal and the file, set the unit to the negative of the actual unit number. If the specified unit number is zero, then Tektronix output to the file is stopped.

Reset_String The string used to place the terminal back into the normal interactive mode after drawing graphics. Use this parameter, in conjunction with the Set_String keyword, to control the mode switching of your terminal. For example, the GraphON 200 series terminals require the string ESC2 to activate the alphanumeric window after drawing graphics. The call to set this is:

DEVICE, Reset=string(27b) + '2'

If the 4100 series mode switch is set, using the keyword Tek4100, the default mode re-setting string is ESC%!1, which selects the ANSII code mode.

Set_String The string used to place the terminal into the graphics mode from the normal interactive terminal mode. If the 4100 series mode switch is set, using the keyword Tek4100, the default graphic mode setting string is ESC%!0, which selects the Tektronix code mode.

Tek4014 If nonzero, specifies that coordinates are to be output with full 12-bit resolution. If this keyword is not present or is zero, 10-bit coordinates are output. By default, PV-WAVE sends 10-bit coordinates. 12-bit coordinates are compatible with most terminals, even those without the full resolution, but require more characters to send.

Tek4100 Indicates that the terminal is a 4100 series terminal. The use of color, ANSII and Tektronix mode switching, hardware line styles, and pixel output with the TV procedure is supported with 4100 series terminals. Also, text is output differently.

The default setting for Tektronix output is: 10-bit coordinates, 4000 series terminals, and no use of color.

Once the Tektronix driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, and to configure PV-WAVE for the specific features of your terminal. See Controlling Tektronix Output with DEVICE Keywords on page -36 for more information. If you never call the DEVICE procedure, PV-WAVE assumes a standard Tektronix 4000 series compatible terminal.

The 4200 series is upwardly compatible with the 4100 series; all references to the 4100 series also include the 4200 series. To set up PV-WAVE for use with a 4100 series compatible terminal with n colors:

SET_PLOT, 'TEK'
DEVICE, /TEK4100, Colors = n 

The number of colors should be set to 2^B where B is the number of bit planes in your terminal. If you use a Tektronix compatible terminal that requires calling the DEVICE procedure for configuration, you should probably create and use a start-up procedure that calls the DEVICE procedure, see the section on modifying your environment in the PV-WAVE Programmer's Guide.

The line drawing procedures work with all models. Color and the display of images (albeit very slowly and frequently of a poor quality because of the low number of colors) is usable only with 4100 series terminals. Hardware polygon fill works only on the 4100 series.

Because of the tremendous variation among the requirements and abilities of these terminals, it is crucial that you configure PV-WAVE properly for your terminal.

Because of hardware restrictions, you will encounter the following limitations when using Tektronix and Tektronix-compatible terminals with PV-WAVE:

• Pixel coordinates do not match the coordinates used by the rest of the graphic procedures. This is because no two models of Tektronix terminals are alike. The graphics procedures use the default coordinate system of 1024-by-780, or 4096-by-3120 in the 12-bit mode. The size of the pixel memory and coordinate system vary widely between models. The Position parameter for the TV and TVSCL procedures does not work.

• The cursor cannot be positioned from the computer, meaning the TVCRS procedure may not be used in the Tektronix mode.

• Pixel values may not be read back from the terminal, rendering the TVRD function inoperable.

WIN32 is the default driver for PV-WAVE running under Microsoft Windows. This driver controls graphics output from PV-WAVE to the Windows workspace.

To enable WIN32 as the current graphics device, enter the following command:

SET_PLOT, 'WIN32'

This causes PV-WAVE to use the WIN32 driver for producing subsequent graphics output. Once the WIN32 driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling the WIN32 Driver with DEVICE Keywords below.

Use the command:

INFO, /Device 

to view the current WIN32 driver settings.

The following text formatting commands are new and can be used with the PostScript, WIN32, WMF, and X drivers. These commands can only be used when hardware fonts are enabled (!P.Font=0).

Formatting Command	Description
!FB	Switch to the bold face of the current font.
!FI	Switch to the italic face of the current font.
!FU	Underline the current font.
!FN	Switch to the normal form of the current font.
!Pxx	Switch to point size xx of the current font, where xx is a two digit integer (01-99).

Refer to the PV-WAVE User's Guide for a comprehensive list of text formatting commands.

The following keywords to the DEVICE procedure provide control over the WIN32 driver:

Close_Display Deletes all generated windows from the Windows workspace and returns PV-WAVE to the initial graphics state.

Copy Copies a rectangular area of pixels from one region of a window to another. The argument of Copy is a six- or seven-element array: [X_s, Y_s, N_x, N_y, X_d, Y_d, W], where: (X_s, Y_s) is the lower-left corner of the source rectangle, (N_x, N_y) are the number of columns and rows in the rectangle, and (X_d, Y_d) is the coordinate of the destination rectangle. Optionally, W is the index of the window from which the pixels should be copied to the current window. If it is not supplied, the current window is used for both source and destination. Copy can be used to increase the pace of animation. This is described in Using Pixmaps to Improve Application Performance on page -75.

Cursor_Crosshair Selects the crosshair cursor type.

Cursor_Image Specifies the cursor pattern. The value of this keyword must be a 16-line by 16-column bitmap, contained in a 16-element short integer vector. Each line of the bitmap must be a 16-bit pattern of ones and zeros, where one (1) is white and zero (0) is black. The offset from the upper-left pixel to the point that is considered the "hot spot" can be provided via the Cursor_XY keyword.

Cursor_Original Selects the Windows default cursor the cursor in use by the window manager when PV-WAVE starts. This cursor pattern is used by default.

Cursor_Wait Specifies the wait cursor, usually an hourglass icon.

Cursor_XY A two-element integer vector giving the x, y pixel offset of the cursor "hot spot", the point which is considered to be the mouse position, from the upper-left corner of the cursor image. This parameter is only applicable if Cursor_Image is provided. The cursor image is displayed top-down in other words, the first row is displayed at the top.

Direct_Color When specified with a Depth value, selects the DirectColor visual with Depth bits per pixel. For example:

Direct_Color=24

The Direct_Color keyword has effect an only if no windows have been created. The Direct_Color and True_Color keywords are essentially synonymous when used with the WIN32 driver: they perform identical functions.

Font Specifies the name of the font used when the hardware font is selected (that is, when !P.Font=0). For example, to select the font 14 point New Times Roman bold, use the following DEVICE call:

DEVICE, Font='Times New Roman, 14, bold' 

Windows provides the Character Map accessory tool that can be used by all applications to show the fonts available on your system.

TrueType hardware fonts can be rotated but not projected. When generating 3D plots, it is best to use the software characters because PV-WAVE can draw them in perspective with the rest of the plot. For more information on software fonts, see the PV-WAVE Programmer's Guide.

Get_Fontmap Returns a list of the current font map settings. If /Get_Fontmap is specified, the information is printed to the screen. If a variable name is specified (e.g., Get_Fontmap=varname), a string array is returned.

The information returned by Get_Fontmap is in the same form as the strings specified with Set_Fontmap. The only exception to this pattern is that the first string returned in a string array is labeled as font 0 and is the current default font.

Get_Graphics_Function Returns the value of the current graphics function (set with the Set_Graphics_Function keyword). This keyword can be used to save the value of the current graphics function, change it temporarily, and then restore it. See the example in the section Using Graphics Functions to Manipulate Color on page -82.

Get_Window_Position Places the x and y device coordinates (relative to the lower-left corner of the display) of the window's lower-left corner into a named variable.

Get_Write_Mask Specifies the name of a variable to receive the current value of the write mask. For example:

DEVICE, Get_Write_Mask=mask

For more information on the write mask, refer to Using the Write Mask and Graphics Functions to Manipulate Color on page -81.

Max_Lines Sets the maximum number of identical line segments that will be cached before forcing a screen redraw. The WIN32 driver uses an internal cache for drawing line segments. Instead of drawing each line individually, lines with common characteristics are drawn as a group. This feature increases drawing efficiency and rendering speed. To disable Max_Lines, set the keyword equal to one. (Default: 500 lines.)

Max_Pens Sets the maximum number of pens that will be cached before forcing a screen redraw. (Default: 10 pens, each of which can hold 500 line segments.) To disable Max_Pens, set the keyword equal to one.

Pseudo_Color When specified with a Depth value, selects the PseudoColor visual with Depth bits per pixel. For example:

Pseudo_Color=8

The Pseudo_Color keyword has an effect only if no windows have been created.

Set_Character_Size A two-element vector that changes the standard width and height of the vector-drawn fonts. The first element in the vector contains the new character width, and the second element contains the height. By default, character size is set to the size of the default hardware font.

Set_Fontmap Associates specific font characteristics with a particular hardware font command. This keyword can be used to specify a single string containing the information for one font, or an array of strings containing the information for multiple fonts.

For example, to associate 16 point Helvetica italic with font command !5, use the following DEVICE call:

DEVICE, Set_Fontmap='5 Helvetica, 16, italics'

Now, whenever the !5 font command appears in a text string, the text output appears in 16 point Helvetica italic. This keyword only affects hardware fonts (that is, when !P.Font=0).

Set_Graphics_Function Windows allows applications to specify the Graphics Function. This is a logical function which specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. The complete list of possible values is given in the following table. The default graphics function is GXcopy, which causes new pixels to completely overwrite any previous pixels.

Set_Write_Mask Sets the write mask to the specified value. Under Windows, the write mask can range from 0 to 255. For more information on the write mask, refer to Using the Write Mask and Graphics Functions to Manipulate Color on page -81.

True_Color When specified with a Depth value, selects the TrueColor visual with Depth bits per pixel. For example:

True_Color=24

The True_Color keyword has an effect only if no windows have been created. The Direct_Color and True_Color keywords are essentially synonymous when used with the WIN32 driver: they perform identical functions.

Window_State Returns an array containing values indicating the status for all available PV-WAVE windows. Each element of the array contains a value equal to the sum of the following values:

In the following example, the fourth element of winarray contains the value 3, or 1 + 2. This indicates that the window is active and backing store is active.

WINDOW, 3

; Open window 3.

DEVICE, Window_State=winarray
PRINT, winarray

Resizing Graphics

Prior to Version 6.0 of PV-WAVE for Microsoft Windows, it was necessary to use special keywords so that displayed graphics would resize whenever the user resized a window using its border. This is no longer the case. Window resizing is now the default behavior and is automatically provided for all normal PV-WAVE graphics windows.

A Windows metafile is used to retain graphics in a window. The metafile is "replayed" into the graphic window whenever the window is resized. Metafiles are also used when you print the window. If you expect that your graphics might be subject to resizing, you should be aware of two limitations inherent in metafiles.

Metafiles are limited by the resolution of the graphics window in which you initially constructed a plot. So if you draw a plot to a small (low-resolution) window and then resize that window to full screen, you will likely see "aliasing" effects due to the low resolution of the original plot. For example, you might see "stairsteps" in diagonal lines or squared-off corners in small arcs or circles. You will see the same kinds of effects if you print the plot to a printer that has a higher resolution that your graphics window.

You can solve this problem by plotting to a high-resolution (large) window when you intend to make high-resolution plots. If you do not wish to view this large window (or you need to make it larger than your display) then you can use the /Pixmap keyword with the WINDOW command to make the window invisible.

Another problem with metafiles is that they cannot reproduce a "dot" (a single-pixel point). So, if you use, for example, Psym=3 (a dot) in a PLOT command, it will appear on the screen, but when you resize the window or print the graph, the dot will disappear. This is because these pixels are treated differently by the metafile. (Note that this problem does not affect images, such as those you might dispay with the TV procedure, for example.)

To solve the disappearing-dot problem, you can turn off metafiles by using the /NoMeta keyword with the WINDOW command. This results in a bitmap (DIB file) being used for repainting and printing. Since bitmaps are not resizable, pixels can't be lost. But keep in mind that when the graphic is printed, it will be scaled to fit the printed region, so you will see effects such as wider lines and possibly boxes in place of dots. This problem can also be solved by using a higher resolution window for the initial plot.

The following commands operate upon the contents of graphics windows. Most of these commands allow for the interchange of graphics between PV-WAVE and other graphics applications.

For detailed information on these commands, see their individual descriptions in the PV-WAVE Reference Volume 2.

• WCOPY Copies the contents of a graphics window onto the Clipboard.

• WPASTE Pastes the contents of the Clipboard into a graphics window.

• WREAD_DIB Loads a Device Independent Bitmap (DIB) from a file directly into a specified graphics window.

• WREAD_META Loads a Windows enhanced metafile (EMF) into a specified graphics window. Note that EMF graphics are designed to be used only with 32-bit applications; they cannot be pasted into a 16-bit application.

• WWRITE_DIB Saves the contents of a graphics window into a file as a Device Independent Bitmap (DIB).

• WWRITE_META Saves the contents of a graphics window into a file as a Windows enhanced metafile (EMF). Note that EMF graphics are designed to be used only with 32-bit applications; they cannot be pasted into a 16-bit application.

• WPRINT Prints the contents of the specified graphics window.

This section discusses how color tables and color palettes are handled by the WIN32 driver. For general information on color tables and how PV-WAVE handles color, see the PV-WAVE Programmer's Guide.

Windows Video Modes

Windows graphics output depends on a piece of software called a video driver that provides an interface between Windows Graphics Device Interface (GDI) calls and the video hardware installed in the computer. This software is usually provided by the manufacturer of the video card. Depending on the capabilities of the hardware, video drivers usually support several video modes. A video mode is a combination of screen resolution, color depth and refresh rate.

Screen resolution is usually expressed in terms of the number of horizontal and vertical pixels displayed on the screen. Common resolutions are 640x480 (VGA), 800x600, 1024x768, and 1280x1024. Higher resolutions require more memory on the video card and a more capable monitor.

Color depth refers to the number of colors that can be displayed at once on the screen. This is usually one of 16, 256, 65636 (16-bit), or 16777216 (24-bit) and is directly related to the number of bits of video memory required to store the color information for a single pixel. In combination with the resolution, this determines what video modes are available for a given amount of memory on a video card. For instance, 1024x768 resolution with 256 colors requires 768KB of memory and so should be available on most video cards with at least 1 MB of video RAM while the same resolution with 24 bits of color information would require 2304KB and would not be available unless the video card has more than 2MB of video memory.

Refresh rate refers to how quickly the video card transfers information to the monitor and is not relevant to this discussion.

PV-WAVE inherently uses an 8-bit pseudo-color model. Color values are represented as an index into the current color table. The color table consists of three byte arrays that have 256 elements; the arrays represent the relative amounts of red, green and blue in a particular color. When a particular value is placed in a PV-WAVE graphics window (by the TV procedure, for instance) the graphics driver determines what color to display by using the value as an index into the color table arrays. When the color table changes (via the LOADCT procedure, for instance) the color represented by a particular value is likely to be different and, if so, will result in a new color being displayed in the graphics window.

In PV-WAVE's WIN32 graphics driver, the contents of a graphics window are stored in a DIB (Device Independent Bitmap) created using the DIB_RGB_COLORS format. This means that the window image is stored in an exact parallel to PV-WAVE's color model: an array of 8-bit values that act as indices into a color table which contains 8 bits each of red, green, and blue color information.

When a graphics window is painted, the DIB section is transferred from normal memory to video memory where it appears on the screen. This operation is called a blit. As part of the blit operation, the video driver and Windows determine how to map the pixel information in the DIB into the current video mode. This is usually a highly optimized operation in the video driver.

The way a pixel value in the DIB gets mapped to a color on the video screen depends on the current color depth that the video driver is using. In general, Windows will map a given pixel color to the closest matching RGB value that the video driver can display. This is likely to be an unsatisfactory match for a driver in 16 color VGA mode, while a driver in 24-bit mode will be able to match any requested color exactly.

When Windows is using a video mode with 256 colors, pixel values in video memory represent an index into a palette (as opposed to directly representing the color as is the case in 16- and 24-bit modes). A palette serves exactly the same function as PV-WAVE's color table it allows the selection of a subset of the 16 million colors that can be represented by the RGB triple.

The palette is controlled by the application that the user is currently using the foreground application. With certain exceptions (discussed below), the foreground application can set the palette to represent whatever set of colors it wants. Background applications try to render their data as best they can given that the foreground application controls the palette; this often results in "flashing" as applications redraw their data when they move from background to foreground. When PV-WAVE is the foreground application, it directly maps the current color table to the Windows palette.

The exception is that Windows reserves the top and bottom 10 entries in the palette (for a total of 20 colors) for the system colors used to draw controls and window decorations. This results in less distraction for the user since only the contents of application windows will flash while window frames and controls will not.

The PV-WAVE WIN32 Driver in 256 Color Mode

The penalty for non-flashing window frames is that only 236 colors are available to PV-WAVE while it needs 256 to represent the color table. Earlier versions of the WIN32 driver used the color limiting mechanisms implemented to support the X driver to reduce the color table size to 236. The drawback to this approach is that it makes PV-WAVE's behavior dependent on the current video mode the same program will give different results with a different video mode. It also caused performance problems since it was necessary to continuously transform data transferred to and from the screen.

With PV-WAVE Version 6.0, the WIN32 driver always indicates that PV-WAVE has 256 colors available; if it needs to display in a palletized video mode, 20 colors evenly distributed through the color table are not mapped to the palette. The other 236 colors will be exactly represented but the 20 unmapped colors will map to the closest match available in the palette, either among the 236 PV-WAVE colors or the 20 system colors. For most of the PV-WAVE color tables, the closest match is immediately adjacent in the color table and the unmapped colors are very difficult to notice. Any discrepancy is purely visual; all PV-WAVE operations, including TV and TVRD, set and return the proper color and these operations return consistent results regardless of the current video model.

Windows can direct graphics to either windows or bitmaps:

• Windows Windows are the usual windows that appear on the screen and contain graphics. Drawing to a window produces a viewable result.

• Bitmaps Bitmaps are areas of invisible graphics memory. Drawing to a bitmap simply updates the bitmap memory.

Bitmaps are useful because it is possible to write graphics to a bitmap and then copy the contents of the bitmap to a window where it can be viewed. The process works by placing the desired images into bitmap memory and then copying them in succession to a visible window.

Creating a Bitmap

To create a bitmap, use the Bitmap keyword with the WINDOW procedure. For example, to create a 1280-by-1280 bitmap in window 1:

WINDOW, 1, /Bitmap, Xsize=1280, Ysize=1280

Once they are created, bitmaps are treated just like normal windows, although some operations (WSHOW, for instance) don't have any noticeable effect when applied to a bitmap. Note also that the bitmap's resolution does not have to be restricted to the size of the display's resolution.

Example Animating a Series of Bitmap Images

The following example shows how animation can be performed using bitmap memory. It uses a series of 15 heart images taken from the file abnorm.dat. (This file is located in the data subdirectory of the main PV-WAVE directory.) It creates a bitmap and writes all 15 images to it. It then uses the Copy keyword of the DEVICE procedure to copy the images to a visible window. Pressing any key causes the animation to halt:

PRO animate_heart

; This procedure animates a series of heart data.

OPENR, u, !Data_Dir+'abnorm.dat',/Get_Lun

; Open the file containing the images.

frame = ASSOC(u, BYTARR(64, 64))

; Associate a file variable with the file. Each heart image is 64-by-64 pixels.

WINDOW, 0, /Bitmap, Xsize=7680, Ysize=512

; Window 0 is a bitmap large enough to hold one double-sized
; image tall and 15 double-sized images wide. The resized
; images will be placed in this bitmap.

FOR i = 0, 15-1 DO TVSCL, $
    REBIN(SMOOTH(frame(i), 3), 512, 512), i

; Write each image to bitmap memory. SMOOTH is used to
; improve the appearance of each image and REBIN is used to enlarge each image 
to the final display size.

FREE_LUN, u

; Close the image file and free the file unit.

WINDOW, 1, Xsize=512, Ysize=512, Title='Heart'

; Window 1 is a visible window that is used to display the
; animated data, creating the appearance of a beating heart.

i = 0L

; Load the current frame number.

WHILE GET_KBRD(0) EQ '' DO BEGIN 
DEVICE, Copy=[i * 512, 0, 512, 512, 0, 0, 0]

; Display frames until any key is pressed. Copy the next image
; from the bitmap to the visible window.

i = (i + 1) MOD 15

; Keep track of total frame count.

ENDWHILE
END

The write mask can be used to superimpose (overlay) one graphics pattern over another when plotting to a graphics window, allowing you to create special effects.

Another possible application for the write mask is to simultaneously manage two 4-bit-deep images in a single graphics window instead of a single 8-bit-deep image. You could use the write mask to control whether the current graphics operation operates on the "top" image or the "bottom" image.

Using Graphics Functions to Manipulate Color

The WIN32 driver provides two keywords for inquiring and manipulating the graphics function Get_Graphics_Function and Set_Graphics_Function.

The value of the Set_Graphics_Function keyword controls the logical graphics function; this function specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. To see a complete list of graphics function codes, refer to the Set_Graphics_Function keyword description in the section X Window System.

In the following example, POLYFlLL is used to select the area to be inverted. Colors represented by color index 1 are XORed with the image currently displayed in that area.

DEVICE, Get_Graphics=oldg, Set_Graphics=6

; Set graphics function to exclusive or (GXxor), saving the old
; function.

POLYFILL, [[x0,y0], [x0,y1], [x1,y1], [x1,y0]], /Device, Color=1
DEVICE, Set_Graphics_Function=oldg

; Restore the previous graphics function.

The default value for the Set_Graphics_Function keyword is GXcopy, which means that the source graphics from the current operation get copied into the window, destroying any graphics that were previously displayed there.

Interaction Between the Set_Write_Mask and the Set_Graphics_Function Keywords

You use the Set_Write_Mask keyword to specify the planes whose bits you are manipulating or the plane you want to use for the special effects. The way the two graphics patterns are combined depends on the value you provide for the Set_Graphics_Function keyword. For example, you could use the following commands:

DEVICE, Set_Graphics_Function=6
DEVICE, Set_Write_Mask=8

to extract the fourth bit (the binary equivalent of the decimal value 8) of the image in the current graphics window. The extracted plane is XORed (XOR is the graphics function specified by setting the Set_Graphics_Function keyword equal to 6) with the source pattern (the result of the current graphics operation). After the graphics function is implemented, the result is drawn in the current graphics window using whichever color(s) in the color table match the resultant value(s).

The graphics functions specified by the Set_Graphics_Function keyword operate individual colors, not on hardware pixel values as they do with the X driver.

The PV-WAVE WINDOW procedure has two keywords, Get_Win_Id and Set_Win_Id that provide access to the WIN32 window handle associated with a PV-WAVE graphics window.

Get_Win_Id returns the HWND that was returned from the WIN32 CreateWindow API call. If you are making PV-WAVE calls from another application via a connectivity mechanism, you can use this keyword to get the window handle and then use the handle as an argument to an API call like HideWindow. You can also use the handle if you need to subclass a PV-WAVE graphics window for any reason.

Set_Win_Id causes PV-WAVE to use a window that already exists as a graphics window. For instance, you might have created a window in a Visual Basic form in which you would like PV-WAVE to display graphics. You can do this by passing PV-WAVE the window handle of the existing window at runtime using the Set_Win_Id keyword. PV-WAVE will subclass the window referred to by the handle when the keyword is used with a WINDOW command. When the driver is closed or when PV-WAVE exits, subclassing is removed.

See the WIN32 Programmer's Reference for more information about window handles and subclassing.

WMF Driver

The WMF driver creates Windows Enhanced Metafile output. The output can be saved either to a file or sent directly to a printer.

The WMF driver is a 24-bit device. For more information on 24-bit color and the WMF driver, see Handling 24-bit Color.

To enable WMF as the current graphics device, enter the following command:

SET_PLOT, 'WMF' 

This causes PV-WAVE to use the WMF driver for producing subsequent graphics output. Once the WMF driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling the WMF Driver with DEVICE Keywords below.

Use the command:

INFO, /Device 

to view the current WMF driver settings.

The following steps can be used to send Windows Metafile output directly to a Windows printer:

      SET_PLOT, 'WMF' 

      DEVICE, /Print 

printer = WIN32_PICK_PRINTER()

- or -

      DEVICE, Set_Printer='printer_name' 

Step 5 Close the Windows Metafile and the output is sent to the printer:

      DEVICE, /Close_File 

The WMF driver is a 24-bit device. Colors specified with this device must conform to the PV-WAVE 24-bit color convention, which is a PV-WAVE long integer with the red, green, and blue color values occupying the lower three bytes, in order, from the least significant byte. For instance, color values less than 256 are considered to be shades of red. If the Pseudo_Color keyword is set to 8, color values less than 256 are taken to be indices into the PV-WAVE color map. Colors greater than 256 are still interpreted as 24-bit colors.

Because the WMF driver is a 24-bit device, you need to specify application colors as RGB values in hexadecimal notation, rather than as an index into a color table.

To ensure that colors display correctly on all types of devices, we recommend that you use the WoColorConvert function whenever you specify a color index in your code.

WoColorConvert returns the RGB color value on 24-bit devices and the color table index on 8-bit devices. By using WoColorConvert with all color index values in your code, you ensure that your application colors will appear properly on all types of devices.

For example:

TEK_COLOR 
PLOT, DIST(10), Color=WoColorConvert(5) 

If your code might be used with 8 and 24-bit displays, and/or the WMF driver, we recommend you use the WoColorConvert function to ensure that colors display correctly.

The following text formatting commands are new and can be used with the PostScript, WIN32, WMF, and X drivers. These commands can only be used when hardware fonts are enabled (!P.Font=0).

Formatting Command	Description
!FB	Switch to the bold face of the current font.
!FI	Switch to the italic face of the current font.
!FU	Underline the current font.
!FN	Switch to the normal form of the current font.
!Pxx	Switch to point size xx of the current font, where xx is a two digit integer (01-99).

Refer to the PV-WAVE User's Guide for a comprehensive list of text formatting commands.

The following keywords to the DEVICE procedure provide control over the WMF driver:

Close_File Closes the currently open Windows Metafile. If the Print keyword was specified, the file will be sent directly to the selected printer.

Direct_Color If set to 24, the WMF driver interprets all colors as 24-bit. For the WMF driver, this keyword is synonymous with the True_Color keyword. (Example: Direct_Color=24)

Filename Specifies the name of a file to save the Windows Metafile output in. This keyword must be used prior to any graphics commands. If a graphics command is used and neither the Print nor Filename keyword has been specified, a Windows File Selector will be displayed.

Font Specifies the name of the font used when the hardware font is selected (that is, when !P.Font=0). For example, to select the font 14 point New Times Roman bold, use the following DEVICE call:

DEVICE, Font='Times New Roman, 14, bold' 

WAVE DEVICE, Font=WIN32_PICK_FONT()

the Font dialog box appears. Pick the font and font characteristics that you wish to use, and click OK. The font that you selcct is automatically set by the DEVICE command.

Get_Fontmap Returns a list of the current font map settings. If /Get_Fontmap is specified, the information is printed to the screen. If a variable name is specified (e.g., Get_Fontmap=varname), a string array is returned.

The information returned by Get_Fontmap is in the same form as the strings specified with Set_Fontmap. The only exception to this pattern is that the first string returned in a string array is labeled as font 0 and is the current default font.

Get_Graphics_Function See the description of the Get_Graphics_Function keyword in X Window System on page -58.

Get_Write_Mask See the description of the Get_Write_Mask keyword in X Window System on page -58.

Inches By default, the Xoffset, Xsize, Yoffset, and Ysize keywords are specified in centimeters. However, if Inches is present and nonzero, these keywords are taken to be in inches instead.

Landscape PV-WAVE normally generates plots with portrait orientation (the x-axis is along the short dimension of the page). If Landscape is present, landscape orientation (the x-axis is along the long dimension of the page) is used instead. This keyword only works if /Print is used.

Max_Lines Sets the maximum number of identical line segments that will be cached before forcing a screen redraw. The WIN32 driver uses an internal cache for drawing line segments. Instead of drawing each line individually, lines with common characteristics are drawn as a group. This feature increases drawing efficiency and rendering speed. To disable Max_Lines, set the keyword equal to one. (Default: 500 lines.)

Max_Pens Sets the maximum number of pens that will be cached before forcing a screen redraw. (Default: 10 pens, each of which can hold 500 line segments.) To disable Max_Pens, set the keyword equal to one.

Portrait If Portrait is present, PV-WAVE generates plots using portrait orientation, the default. This keyword only works if /Print is used.

Print If present and non-zero, specifies that output should be sent directly to the selected Windows printer when the Windows Metafile is closed. As described in Sending PV-WAVE Output Directly to a Printer, either the Set_Printer keyword or the WIN32_PICK_PRINTER function can be used to select a destination printer. If neither is used, the default Windows printer is used. The Print keyword must be specified before any output is made to the Windows Metafile.

Pseudo_Color If set to 8, the WMF driver interprets 8-bit color values (that is, color values less than 256) as color map indices rather than as 24-bit colors. (Example: Pseudo_Color=8)

Set_Character_Size A two-element vector that changes the standard width and height of the vector-drawn fonts. The first element in the vector contains the new character width, and the second element contains the height. By default, character size is set to the size of the default hardware font.

Set_Fontmap Associates specific font characteristics with a particular hardware font command. This keyword can be used to specify a single string containing the information for one font, or an array of strings containing the information for multiple fonts.

For example, to associate 16 point Helvetica italic with font command !5, use the following DEVICE call:

DEVICE, Set_Fontmap='5 Helvetica, 16, italics'

Now, whenever the !5 font command appears in a text string, the text output appears in 16 point Helvetica italic. This keyword only affects hardware fonts (that is, when !P.Font=0).

Set_Graphics_Function See the description of the Set_Graphics_Function keyword in X Window System on page -58.

Set_Write_Mask See the description of the Set_Write_Mask keyword in X Window System on page -58.

Under Windows, the write mask can range from 0 to 255.

Thickness Specifies the thickness (in millimeters) of lines drawn into the Windows Metafile. The default thickness is 2.

True_Color If set to 24, the WMF driver interprets all colors as 24-bit. For the WMF driver, this keyword is synonymous with the Direct_Color keyword. (Example: True_Color=24)

Xoffset Specifies the x position on the page of the lower-left corner of output. Xoffset is specified in centimeters unless Inches is specified. This keyword only works if /Print is used.

Xsize Specifies the width of output PV-WAVE generates. Xsize is specified in centimeters unless Inches is specified.

Yoffset Specifies the y position on the page of the lower-left corner of output generated by PV-WAVE. Yoffset is specified in centimeters unless Inches is specified. This keyword only works if /Print is used.

Ysize Specifies the height of output generated by PV-WAVE. Ysize is specified in centimeters unless Inches is specified.

X Window System

PV-WAVE uses the X Window System to provide an environment in which you can create one or more independent windows, each of which can be used for the display of graphics and/or images.

The X Window System is the default windowing system for UNIX and OpenVMS PV-WAVE platforms.

In X there are two basic cooperating processes, clients and servers. A server usually consists of a display, keyboard, and pointer (such as a mouse) as well as the software that controls them. Client processes (such as PV-WAVE) display graphics and text on the screen of a server by sending X protocol requests across the network to the server. Although in the simplest case, the server and client reside on the same machine, this network-based design allows more elaborate configurations.

When you use X, the environment variable $DISPLAY (UNIX) or the logical DECW$DISPLAY (DECwindows Motif) must be set properly. Otherwise, PV-WAVE may appear to "hang". The following command allows PV-WAVE windows to appear on the local display (the current workstation). Enter one of these commands at the prompt of the current workstation before you start PV-WAVE, depending on whether you are using UNIX or OpenVMS (DECwindows Motif):

(UNIX)setenv DISPLAY nodename:0.0

(OpenVMS)SET DISPLAY /CREATE /NODE=nodename -/SCREEN=0.0 /TRANSPORT=transport_type

You must also be sure that an X server is running on the host machine specified with the $DISPLAY environment variable or DECW$DISPLAY logical, and that the machine PV-WAVE is running on has permission to communicate with that X server. Refer to the documentation for your X-compatible window manager to learn how to modify your X server's permissions list.

To use X as the current graphics device, enter the following command:

SET_PLOT, 'X'

This causes PV-WAVE to use X for producing subsequent graphical output. Once the X driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling the X Driver with DEVICE Keywords on page -61.

Use the command:

INFO, /Device

to view the current X driver settings.

If you wish to include a graphical user interface (GUI) with a PV-WAVE application that you are writing for use with the X Window System, you have several choices:

• WAVE Widgets A versatile, easy-to-use set of functions for creating Motif GUIs for PV-WAVE applications. WAVE Widgets are designed for PV-WAVE developers with little or no experience using the Motif GUI toolkits. See the PV-WAVE GUI Application Developer's Guide for detailed information on the Widget Toolbox functions.

• Widget Toolbox A set of highly flexible PV-WAVE functions used to create Motif Graphical User Interfaces (GUIs) for PV-WAVE applications. The Widget Toolbox functions call Motif routines directly, and are designed primarily for developers who are already experienced using either Motif. See the PV-WAVE GUI Application Developer's Guide for detailed information on the Widget Toolbox functions.

• C-based Applications PV-WAVE can be used to add visual data analysis capability to an existing C application. The application interface can be developed in C, and, via interapplication communication functions, the C application can call PV-WAVE to perform data processing and display functions.

---

UNIX and OpenVMS Users: For more details on interapplication communication, refer to the PV-WAVE GUI Application Developer's Guide.

---

The following text formatting commands are new and can be used with the PostScript, WIN32, WMF, and X drivers. These commands can only be used when hardware fonts are enabled (!P.Font=0).

Formatting Command	Description
!FB	Switch to the bold face of the current font.
!FI	Switch to the italic face of the current font.
!FU	Underline the current font.
!FN	Switch to the normal form of the current font.
!Pxx	Switch to point size xx of the current font, where xx is a two digit integer (01-99).

Refer to the PV-WAVE User's Guide for a comprehensive list of text formatting commands.

The following keywords to the DEVICE procedure provide control over the X driver:

Bypass_Translation When this keyword is set, the translation table is bypassed and color indices can be directly specified. Pixel values read via the TVRD function are not translated if this keyword is set, and thus the result contains the actual (hardware) pixel values present in the display. By default, the translation table is used with shared color tables. When displays with static (read-only) visual classes and with private color tables are used, the translation table is always bypassed. For more information about the translation table, refer to Color Translation Table on page -74.

Close_Display Causes PV-WAVE to sever the connection with the X server. This has the effect of deleting all generated windows from the screen of the server, and returns PV-WAVE to the initial graphics state. One use for this option is to change the number of colors used. See the section, When Color Characteristics are Determined on page -73, for details.

Copy Copies a rectangular area of pixels from one region of a window to another. The argument of Copy is a six- or seven-element array: [X_s, Y_s, N_x, N_y, X_d, Y_d, W], where: (X_s, Y_s) is the lower-left corner of the source rectangle, (N_x, N_y) are the number of columns and rows in the rectangle, and (X_d, Y_d) is the coordinate of the destination rectangle. Optionally, W is the index of the window from which the pixels should be copied to the current window. If it is not supplied, the current window is used for both source and destination. Copy can be used to increase the pace of animation. This is described in Using Pixmaps to Improve Application Performance on page -75.

Cursor_Crosshair Selects the crosshair cursor type. The crosshair cursor style is the default.

Cursor_Image Specifies the cursor pattern. The value of this keyword must be a 16-line by 16-column bitmap, contained in a 16-element short integer vector. Each line of the bitmap must be a 16-bit pattern of ones and zeros, where one (1) is white and zero (0) is black. The offset from the upper-left pixel to the point that is considered the "hot spot" can be provided via the Cursor_XY keyword.

Cursor_Original Selects the default cursor for the window system. Under X, it is the cursor in use by the window manager when PV-WAVE starts.

Cursor_Standard Selects one of the predefined cursors provided by X. The available cursor shapes are defined in the file:

(UNIX)/usr/include/X11/cursorfont.h

(OpenVMS)DECW$INCLUDE:CURSORFONT.H

In order to use one of these cursors, select the number of the font and provide it as the value of the Cursor_Standard keyword. For example, the cursorfont.h file gives the value of Xc_Cross as being 30. In order to make that the current cursor, use the statement:

DEVICE, Cursor_Standard=30

Cursor_XY A two-element integer vector giving the x, y pixel offset of the cursor "hot spot", the point which is considered to be the mouse position, from the upper-left corner of the cursor image. This parameter is only applicable if Cursor_Image is provided. The cursor image is displayed top-down in other words, the first row is displayed at the top.

Direct_Color When specified with a Depth value, selects the DirectColor visual with Depth bits per pixel. For example:

Direct_Color=12

The Direct_Color keyword has effect only if no windows have been created.

Floyd If present and nonzero, selects the Floyd-Steinberg dithering method. For more information on this dithering method, the PV-WAVE User's Guide.

Font Specifies the name of the font used when the hardware font is selected. For example, to select the font 8X13:

DEVICE, Font='8X13'

Usually, the window system provides a directory of font files that can be used by all applications. List the contents of that directory to find the fonts available on your system. The size of the font selected also affects the size of software-drawn text (e.g., the Hershey fonts). On some machines, fonts are kept in subdirectories of:

(UNIX)/usr/lib/X11/fonts

(OpenVMS)SYS$SYSROOT:[SYSCOMMON.SYSFONT]

Get_Fontmap Returns a list of the current font map settings. If /Get_Fontmap is specified, the information is printed to the screen. If a variable name is specified (e.g., Get_Fontmap=varname), a string array is returned.

The information returned by Get_Fontmap is in the same form as the strings specified with Set_Fontmap. The only exception to this pattern is that the first string returned in a string array is labeled as font 0 and is the current default font.

Get_Graphics_Function Returns the value of the current graphics function (set with the Set_Graphics_Function keyword). This can be used to remember the current graphics function, change it temporarily, and then restore it. For an example, see the example in the section Using Graphics Functions to Manipulate Color on page -82.

Get_Visuals Displays the list of currently available visual classes. If a named variable is specified with this keyword, the information is stored in a 2D array of long values. The size of first dimension is 8, and the index is defined in the following table:

The value of visual class item above is shown in the following table:

The second dimension of the 2D array represents the number of available visual classes.

Get_Window_Position Places the x and y device coordinates of the window's lower-left corner into a named variable.

Get_Write_Mask Specifies the name of a variable to receive the current value of the write mask. For example:

Get_Write_Mask=mask 

For more information on the write mask, refer to Using the Write Mask and Graphics Functions to Manipulate Color on page -81.

List_Fonts Returns a list of the available X fonts. If /List_Fonts is specified, the information is printed to the screen. If a variable name is specified (e.g., List_Fonts=varname), a string array is returned. This keyword works like the UNIX command xlsfonts. If the Pattern_Font keyword is used to specify a pattern, that pattern is used to filter the list of fonts returned by List_Fonts; otherwise, List_Fonts returns all available fonts.

Ordered If present and nonzero, selects the Ordered method of dithering. For more information on dithering, see the PV-WAVE User's Guide.

Pattern_Font Specifies a pattern that is used to filter the fonts that are returned by the List_Font keyword. For example, to list all the fonts in the adobe foundry, enter this command:

DEVICE, /List_Fonts, Pattern='-adobe-*'

DEVICE, /List_Fonts, Pattern_Font='-*-*-*-*-*-*-0-0-*-*-*-0-*-*'

DEVICE, /List_Fonts, $
Pattern_Font='-*-*-*-*-*-*-[1 0 0 1]-*-*-*-*-*-*-*'

In this case, the matrix is specified in the 7th field. All other fields contain the wildcard symbol (*).

Pseudo_Color When specified with a Depth value, selects the PseudoColor visual with Depth bits per pixel. For example:

Pseudo_Color=8

The Pseudo_Color keyword has effect only if no windows have been created.

Retain Specifies the default method used for backing store when creating new windows. This is the method used when the Retain keyword is not specified with the WINDOW procedure. Backing store is discussed in more detail in the subsection, How Is Backing Store Handled? on page -2. The possible values for this keyword are summarized in Possible Values for the Retain Keyword on page -3.If Retain is not used to specify the default method, method 1 (server-supplied backing store) is used.

Set_Character_Size A two-element vector that changes the standard width and height of the vector-drawn fonts. The first element in the vector contains the new character width, and the second element contains the height. By default, character size is set to the size of the default hardware font.

Set_Fontmap Associates specific font characteristics with a particular hardware font command. This keyword can be used to specify a single string containing the information for one font, or an array of strings containing the information for multiple fonts.

For example, to associate 14 point Times bold with font command !5, use the following DEVICE call and the complete X driver font name:

Set_Fontmap='5 -adobe-times-bold-r-normal-*-14-*-*-*-*-*-*-*'

Now, whenever the !5 font command appears in a text string, the text output appears in 14 point Times bold. This keyword only affects hardware fonts (that is, when !P.Font=0).

Set_Graphics_Function X allows applications to specify the Graphics Function. This is a logical function which specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. The complete list of possible values is given in the following table. The default graphics function is GXcopy, which causes new pixels to completely overwrite any previous pixels.

Set_Write_Mask Sets the write mask to the specified value. For an n-bit system, the write mask can range from 0 to 2ⁿ - 1. For more information on the write mask, refer to Using the Write Mask and Graphics Functions to Manipulate Color on page -81.

Static_Color When specified with a Depth value, selects the StaticColor visual with Depth bits per pixel. This keyword has effect only if no windows have been created.

Static_Gray When specified with a Depth value, selects the StaticGray visual with Depth bits per pixel. This keyword has effect only if no windows have been created.

Threshold Specifies use of the threshold dithering algorithm the simplest dithering method. For more information on this dithering method, see PV-WAVE User's Guide.

Translation Using the shared colormap (which is normally recommended) causes PV-WAVE to translate between color indices (which always start with zero and are contiguous) and the pixel values actually present in the display. The Translation keyword specifies the name of a variable to receive the translation vector. To read the translation table:

DEVICE, Translation=Transarr

The result is a 256-element byte vector, Transarr. Element zero of Transarr contains the pixel value allocated for the first color in the colormap, and so forth.

For more information on the translation table, refer to Color Translation Table on page -74.

True_Color When specified with a Depth value, selects the TrueColor visual with Depth bits per pixel. For example:

True_Color=12

The True_Color keyword has effect only if no windows have been created.

VisualID If specified with the visual class ID number, selects the visual class with visual class with given ID number.

Window_State Returns an array containing values indicating the status (open = 1, closed = 0) for all available PV-WAVE windows. For example:

WINDOW, 3

; Open window 3.

DEVICE, Window_State=winarray
PRINT, winarray

Visuals specify how the hardware deals with color. The X server of your display may provide colors or only gray scale (black and white), or both. The color tables may be changeable from within PV-WAVE (read-write), or they may be static (read-only). The value of each pixel may be mapped to any color (Undecomposed Colormap), or certain bits of each pixel are dedicated to the red, green, and blue primary colors (Decomposed Colormap).

The X server provides six visual classes read-write and read-only visuals for three types of displays: Gray Scale, Undecomposed Color, and Decomposed Color. The names of the visual classes are listed in the following table:

PV-WAVE supports all six types of visual classes, although not at all possible depths (e.g., 4-bit, 8-bit, 24-bit).

X servers from different manufacturers will each have a default visual class. Many servers may provide multiple visual classes. For example, a server with display hardware that supports an 8-bit deep, undecomposed, writable color map (PseudoColor), may also easily support StaticColor, StaticGray, and GrayScale visual classes.

When opening the display, PV-WAVE asks the display for the following visual classes, in order, until a supported visual class is found:

1. DirectColor, 24-bit2. TrueColor, 24-bit3. PseudoColor, 8-bit, then 4-bit 4. StaticColor, 8-bit, then 4-bit 5. GrayScale, any depth6. StaticGray, any depth

You can override this default choice by using the DEVICE procedure to specify the desired visual class and depth before you create a window.

For example, if you are using a display that supports both the 24-bit deep DirectColor visual class, and an 8-bit deep PseudoColor visual class, PV-WAVE will select the 24-bit deep DirectColor visual class. To use PseudoColor, enter the following command before creating a window:

DEVICE, Pseudo_Color=8

Colormaps define the mapping from color index to screen pixel value. In this discussion, the term colormap is used interchangeably with the terms color table, color translation table, or color lookup table other terminology that you may be familiar with from working with other systems. Colormaps perform a slightly different role on 8-bit workstations than they do on 24-bit workstations.

On an 8-bit workstation, the screen pixel value in video memory "looks up" the red-green-blue color combination in its corresponding color table index (hence, the term color lookup table). For example, a pixel value of 43 looks in color table location 43 and may find Red=255, Green=0, and Blue=255. The three values at that colortable location tell the red, green, and blue electron guns in the CRT what intensities to display for that pixel. In this example, any pixel with a value of 43 will be displayed as magenta (100% red, 0% green, 100% blue).

24-bit Graphics Primer

On a 24-bit workstation, each pixel on the screen can be displayed in any one of a possible 16.7 million (2²⁴) colors. The video memory on the machine is capable of addressing each pixel on the screen with a 24-bit value, "decomposed" to eight bits each for the red, green, and blue intensity values for that pixel.

Since each pixel in video memory directly references a set of three 8-bit red-green-blue intensities, there is no need for a color lookup table as in an 8-bit system. However, because PV-WAVE is an 8-bit colortable-based software package (instead of a "true" 24-bit software package), it performs similar conversions internally when drawing to a 24-bit display.

Some 24-bit displays allow the screen to be treated as two separate 12-bit PseudoColor visuals. This allows for "double-buffering", a technique useful for animation, or for storing distance data to simplify hidden line and plane calculations in 3D applications.

Although a 24-bit display takes up three times as much video memory as an 8-bit system, the number of concurrent colors allowed on the screen is not limited by memory the number is limited only by the number of pixels on the screen (assuming, of course, that the screen contains less than 16.7 million pixels). For example, a 24-bit X Window display with 1280-by-1024 pixel resolution contains 1,310,720 pixels, and thus it can potentially display that many colors on the screen at one time.

For more information about how colors are represented on 24-bit displays, refer to Understanding 24-bit Graphics Displays on page -79.

Many factors affect how PV-WAVE chooses the type of colormap. For example, the keywords you supply with the DEVICE procedure control the way color is used in graphics windows throughout that session.

PV-WAVE colormaps can be either shared or private, and either read-write or read-only:

• Colormaps may be private or shared. This characteristic is determined by the number and type of application(s) running during your session.

• Colormaps may be static (read-only) or writable. This characteristic is controlled by the visual class that was invoked at the time the X server was started (or restarted).

For more information about how to select PV-WAVE's visual class, refer to Selecting a Visual Class on page -69.

Shared Colormaps

The window manager creates a colormap when it is started. This is known as the default colormap, and it can be shared by all applications using the display. When any application requires a colormap entry, it can allocate one from this shared colormap.

Using the shared colormap ensures that all applications share the available colors without conflict, and all color indices are available to every application. No application is allowed to change a color that is allocated to another application.

In other words, PV-WAVE can change the colors it has allocated without changing the colors that have been allocated by the window manager or other applications that are running.

On the other hand, using a shared colormap can involve the following disadvantages:

• The window system's interface routines must translate between internal pixel values and the values required by the server, significantly slowing the transfer of images.

• The number of available colors in the shared colormap depends on the window manager being used and the demands of other applications. Thus, the number of available colors can vary, and the shared colormap might not always have enough colors available to perform the desired PV-WAVE operations.

• The allocated colors in a shared colormap do not generally start at 0 (zero) and they are not necessarily contiguous. This makes it difficult to use the write mask for certain operations.

For more information about the write mask, refer to Using the Write Mask and Graphics Functions to Manipulate Color on page -81.

Private Colormaps

An application can create its own private colormap. Most hardware can only display a single colormap at a time, so these private colormaps are called virtual colormaps, and only one at a time is visible. When the window manager gives the input focus to a window with a private colormap, the X server loads its virtual colormap into the hardware colormap.

The advantages of private colormaps include:

• Every color supported by the hardware is available to PV-WAVE, improving the quality of images.

• Allocated colormaps always start at 0 (zero) and use contiguous colors, which simplifies your use of the write mask.

• No translation between internal pixel values and the values required by the server is required, which optimizes the transfer of images.

On the other hand, using a private colormap can involve the following disadvantages:

• You may see "flashing" when you move the pointer in and out of PV-WAVE graphics windows. This happens because when the pointer moves inside a PV-WAVE window, the PV-WAVE colormap is loaded, and other applications are displayed using PV-WAVE's colors. The situation is reversed when the pointer moves out of the PV-WAVE window into an area under the jurisdiction of a different application.

• Colors in a private colormap are usually allocated from the lower end of the map first. But these typically are the colors allocated by the window manager for such things as window borders, the color of text, and so forth.

• Since most PV-WAVE colormaps have very dark colors in the lower indices, the result of having other applications use the PV-WAVE colormap is that the portions of the screen that are not PV-WAVE graphics windows look dark and unreadable.

When Color Characteristics are Determined

PV-WAVE decides how many colors and which combination of colormap and visual class to use when it creates its first graphics window of that session. You can create windows in two ways:

• Use the WINDOW procedure. WINDOW allows you to explicitly control many aspects of how the window is created, including its X visual class.

• If no windows exist and a graphics operation requiring a window is executed, PV-WAVE implicitly creates a window (window 0) using the default characteristics.

Once the first window is created, all subsequent PV-WAVE windows share the same colormap. The number of colors available is stored in the system variable !D.N_Colors. For more information about !D.N_Colors, see the PV-WAVE User's Guide.

For more information about when color characteristics are determined when drawing or plotting to a window running in a 24-bit visual class, refer to 24-bit Visual Classes on page -77.

To change the type of colormap used or the number of colors, you must first completely close the existing connection to the X server using the following command:

DEVICE, /Close_Display

You can then use the WINDOW procedure to specify the new configuration. However, remember that if you enter the command shown above, it will cause every PV-WAVE graphics window that is currently open to be deleted.

How Many Colors PV-WAVE Maps into the Color Table

If the number of colors to use is explicitly specified using the Colors keyword with the WINDOW procedure, PV-WAVE attempts to allocate the number of colors specified from the shared colormap using the default visual class of the screen. If enough colors aren't available, a private colormap with that number of colors is created instead.

For more information about the advantages and disadvantages of private colormaps, refer to Private Colormaps on page -72.

By default, the shared colormap is used whenever possible, and PV-WAVE allocates all available colors from the shared colormap. The allocation occurs if no window currently exists and a graphics operation causes PV-WAVE to implicitly create one.

Reserving Colors for Other Applications' Use

Specifying a negative value for the Colors keyword to the WINDOW procedure causes PV-WAVE to use the shared colormap, allocating all but the specified number of colors. For example:

WINDOW, Colors = -16

allocates all but eight of the currently available colors. This allows other applications that might need their own colors (such as the window manager) to run in tandem with PV-WAVE.

Color Translation Table

Colors in the shared colormap do not have to start from index zero, nor are they necessarily contiguous. PV-WAVE preserves the illusion of a zero-based contiguous colormap by maintaining a translation table between applications' color indices and the actual pixel values allocated from the X server. The color indices range from 0 to !D.N_Colors - 1. Normally, you need not be concerned with this translation table, but it is available using the statement:

DEVICE, Translation=Trans

This statement stores the current translation table, a 256-element byte vector, in the variable Trans. Element zero of this translation vector contains the value pixel allocated for the zero^th color in the PV-WAVE colormap, and so forth.

The translation table may be bypassed, allowing direct access to the display's color hardware pixel values, by specifying the Bypass_Translation keyword with the DEVICE procedure. Translation is disabled by clearing the bypass flag, as shown in the following command:

DEVICE, Bypass_Translation=0

When a private or static (read-only) color table is initialized, the bypass flag is cleared. The bypass flag is always set when initializing a shared color table.

For more information about !D.N_Colors, refer to the PV-WAVE User's Guide.

To see an example of how the translation table can affect displayed colors, see Interaction Between the Set_Graphics_Function Keyword and Hardware Pixel Values on page -83.

The X Window System can direct graphics to either windows or pixmaps.

• Windows Windows are the usual windows that appear on the screen and contain graphics. Drawing to a window produces a viewable result.

• Pixmaps Pixmaps are areas of invisible graphics memory contained in the server. Drawing to a pixmap simply updates the pixmap memory.

Pixmaps are useful because it is possible to write graphics to a pixmap and then copy the contents of the pixmap to a window where it can be viewed. This copy operation is very fast because it happens entirely within the server, instead of communicating across the network to the client. Provided enough pixmap memory is available for the server's use, this technique works very well for animating a series of images. The process works by placing the desired images into pixmap memory and then copying them to a visible window.

To read a brief description of the relationship between the X server and the X client, refer to X Window System on page -58.

To create a pixmap, use the Pixmap keyword with the WINDOW procedure. For example, to create a 128-by-128 pixmap in PV-WAVE window 1:

WINDOW, 1, /Pixmap, XSize=128, YSize=128

Once they are created, pixmaps are treated just like normal windows, although some operations (WSHOW, for instance) don't have any noticeable effect when applied to a pixmap.

The following example shows how animation can be performed using pixmap memory. It uses a series of 15 heart images taken from the file heartbeat.dat. (This file is located in the data subdirectory of the main PV-WAVE directory.) It creates a pixmap and writes all 15 images to it. It then uses the Copy keyword of the DEVICE procedure to copy the images to a visible window. Pressing any key causes the animation to halt:

PRO animate_heart

; This procedure animates a series of heart data.

IF !Version.platform EQ 'VMS' THEN $
    OPENR, u, GETENV('WAVE_DIR')+$
    '[data]heartbeat.dat', /Get_Lun $
ELSE $
OPENR, u, '$WAVE_DIR/data/heartbeat.dat', /Get_Lun

; Open the file containing the images.

frame = ASSOC(u, BYTARR(256, 256))

; Associate a file variable with the file. Each heart image is 
; 256-by-256 pixels.

WINDOW, 0, /Pixmap, XSize=7680, YSize=512

; Window 0 is a pixmap that is one double-sized image tall and 
; 15 double-sized images wide. The images will be placed in this
; pixmap.

FOR i = 0, 15-1 DO TV, $
    REBIN(SMOOTH(frame(i), 3), 512, 512), i

; Write each image to pixmap memory. SMOOTH is used to
; improve the appearance of each image and REBIN is used to
; enlarge/shrink each image to the final display size.

FREE_LUN, u

; Close the image file and free the file unit.

WINDOW, 1, XSize=512, YSize=512, Title='Heart'

; Window 1 is a visible window that is used to display the animated
; data, creating the appearance of a beating heart.

i = 0L

; Load the current frame number.

WHILE GET_KBRD(0) EQ '' DO BEGIN 
DEVICE, Copy=[i * 512, 0, 512, 512, 0, 0, 0]

; Display frames until any key is pressed. Copy the next image
; from the pixmap to the visible window.

i = (i + 1) MOD 15

; Keep track of total frame count.

ENDWHILE
END

In this example, the pixmap was made one image tall and 15 images wide for simplicity. However, some X servers will refuse to display a pixmap that is wider than the physical width of the screen. For this case, the above routine would have to be rewritten to either use a shorter, taller pixmap or to use several pixmaps.

If you do not request a visual class (by entering a DEVICE command prior to opening the first graphics window), PV-WAVE uses the first class the device supports, regardless of the root visual class. PV-WAVE queries the device about the following visual classes, in order, until a supported visual class is found:

1. DirectColor, 24-bit2. TrueColor, 24-bit3. PseudoColor, 8-bit, then 4-bit 4. StaticColor, 8-bit, then 4-bit 5. GrayScale, any depth6. StaticGray, any depth

PV-WAVE can operate in either of the two 24-bit visual classes. But because of the search order, if your workstation is configured to run in a 24-bit mode, PV-WAVE will choose DirectColor by default.

For more discussion concerning the search order for X visual classes, refer to Selecting a Visual Class on page -69.

In DirectColor mode, color tables are always in effect and can be loaded. PV-WAVE loads the color tables using the same LOADCT and TVLCT commands you use when using PV-WAVE in 8-bit PseudoColor mode.

In this mode, color data is decompressed, meaning there are still only 256 slots in the PV-WAVE color table while operating in DirectColor mode. When color data is decompressed, 8 of the bits map to one of the 256 reds, 8 of the bits map to one of the 256 greens, and 8 of the bits map to one of the 256 blues that have been loaded into the 256 element color table (with LOADCT or TVLCT).

For more information about which bits are mapped to red, green, and blue, refer to Specifying 24-bit Colors in Hexadecimal Notation on page -79.

In TrueColor mode, color tables cannot be loaded. However, PV-WAVE can load a translation table. You load the translation table using either the LOADCT or TVLCT commands. The translation table works just like a color table except that it takes effect at drawing time (TV, PLOT, CONTOUR, etc.) rather than when you enter the LOADCT or TVLCT command.

In TrueColor mode, the color map takes effect when the graphics command (PLOT, SURFACE, TVSCL, etc.) is entered. An intriguing benefit of this behavior is that several PV-WAVE color tables loaded into translation tables (using LOADCT or TVLCT) may be used simultaneously during the same session, as shown in the following group of commands:

DEVICE, True_Color=24

; Define a TrueColor graphics window.

data = DIST(512)

; Create a sample data set that can be displayed as an image.

WINDOW, 0
LOADCT, 0
TVSCL, data

; Display the image in window 0 using grayish hues.

WINDOW, 1
LOADCT, 1
TVSCL, data

; Display the image in window 1 using bluish hues.

WINDOW, 2
LOADCT, 4
TVSCL, data

; Display the image in window 2 using shades of red, yellow, and
; green.

If the root window is also running in the 24-bit TrueColor visual class (just like PV-WAVE in this example), you will not see any "flashing", even though you are entering LOADCT and TVSCL commands. For more information about the condition known as "window flashing", refer to Private Colormaps on page -72.

PV-WAVE does not inherit the visual class of the X Window System root window. Thus, booting a machine with the root window set to any specific visual class has no effect on the visual classes that are available for use by PV-WAVE (see the Note later in this section for an exception to this statement). For example, you could edit the /etc/ttys file of a Digital UNIX workstation (if it supported 24-bit visual classes) such that it included the line:

0: window = '/usr/bin/Xtm -class StaticGray'

and then proceed to simultaneously (and successfully) run two PV-WAVE sessions one in DirectColor mode and the other in PseudoColor mode.

A 24-bit raster image is actually made up of three component 8-bit images a red, a green, and a blue image, which combine to create a "true" color picture. With 24-bit graphics displays, each pixel on the screen can be displayed in any one of a possible 16.7 million (2²⁴) colors.

The video memory in a 24-bit machine is capable of addressing each pixel on the screen with 8 bits assigned to each of the red, green, and blue intensity values for that pixel. These sets of 8-bit values are known as color planes, e.g., the "red plane", the "green plane", and the "blue plane". The three red-green-blue intensity values for each 24-bit pixel in video memory are translated directly into color intensities for the red, green, and blue electron guns in the CRT.

Colors in PV-WAVE graphics windows can be specified using the Color keyword. In the range of {0...16,777,216}, the color magenta has a decimal value of 16,711,935. But when using 24-bit color, the convention is to represent this value not as a decimal value, but as a 6-digit hexadecimal value. For example, the color magenta can be passed to one of the graphics routines using the construct:

Color = 'ff00ff'x

The first two digits in this hexadecimal value correspond to the blue intensity, the middle two digits correspond to the green intensity, and the right two digits correspond to the red intensity. The interpretation of the various digits is shown in Figure B-4.

The hexadecimal notations for some of the most commonly-used colors are shown in the following table.

---

NOTE: When programming with WAVE Widgets or Widget Toolbox, you can only enter colors using color names. The hexadecimal form is not recognizable by the WAVE Widgets or Widget Toolbox routines. For more information about how to select colors for widgets in a graphical user interface (GUI), refer to the PV-WAVE GUI Application Developer's Guide.

---

In the TrueColor visual class, raster graphics colors go through the translation table, but vector graphics colors do not. This means that vector graphics colors in plots can be specified explicitly despite any translation table that has been loaded.

For more information about the translation table, refer to Color Translation Table on page -74.

Example Plotting with 24-bit Colors

The following example plots a line chart showing five data sets, each one plotted in a different color. (Assume that mydata1, mydata2, mydata3, mydata4, and mydata5 have all been defined as integers or floating-point vectors prior to entering the commands shown below.)

DEVICE, True_Color=24

; Define a TrueColor graphics window.

PLOT, mydata1, Color='00ff00'x

; Draw mydata1 using a green line.

OPLOT, mydata2, Color='0000ff'x

; Draw mydata2 using a red line.

OPLOT, mydata3, Color='ff0000'x

; Draw mydata3 using a blue line.

OPLOT, mydata4, Color='00ffff'x

; Draw mydata4 using a yellow line.

OPLOT, mydata5, Color='007fff'x

; Draw mydata5 using a orange line.

---

NOTE: The system variable !D.N_Colors must still be initialized properly prior to opening the graphics window. For more information about how to initialize color characteristics, refer to When Color Characteristics are Determined on page -73.

---

If you are using PV-WAVE in one of the 24-bit visual classes, you may want to consider using the write mask to isolate a certain group of bits, such as the red group of bits, or the green group. This is relatively easy to do, since each pixel in video memory directly references a set of three 8-bit red-green-blue intensities. For more information about how to address the various planes of a 24-bit (24-plane) workstation, refer to Understanding 24-bit Graphics Displays on page -79.

In an 8-bit visual class, an analogous write mask operation is to use a write mask of 1 so that only the "lowest" plane is affected. But this is a suitable choice only if you want to force your application to display in monochrome on both color and monochrome displays.

---

TIP: For best results when using the write mask, use a color table that uses all 256 available colors, and bypass the translation table to make sure the color table starts at zero (0). Unfortunately, a side effect of letting PV-WAVE allocate all 256 colors is that you may see "window flashing" when using your application, as explained in Private Colormaps on page -72.

---

Using the Write Mask to Create Special Effects

The write mask can be used to superimpose (overlay) one graphics pattern over another when plotting to a graphics window, allowing you to create special effects. For example, some 24-bit displays allow the screen to be treated as two separate 12-bit Pseudo_Color visuals. This allows for "double-buffering", a technique useful for animation, or for storing distance data to simplify hidden line and plane calculations in 3D applications.

Another possible application for the write mask is to simultaneously manage two 4-bit-deep images in a single graphics window instead of a single 8-bit-deep image. You could use the write mask to control whether the current graphics operation operates on the "top" image or the "bottom" image.

Using Graphics Functions to Manipulate Color

PV-WAVE's X (and Windows) driver provides two keywords for inquiring and manipulating the graphics function Get_Graphics_Function and Set_Graphics_Function.

The value of the Set_Graphics_Function keyword controls the logical graphics function; this function specifies how the source pixel values generated by a graphics operation are combined with the pixel values already present on the screen. To see a complete list of graphics function codes, refer toTo see a complete list of graphics function codes, refer to the Set_Graphics_Function keyword description in the section X Window System.

For example, the following code segment shows how to use the XOR graphics function to toggle the "low bit" of the pixel value that determines the color in a rectangle defined by its diagonal corners (x₀, y₀) and (x₁, y₁):

DEVICE, Get_Graphics=oldg, Set_Graphics=6

; Set graphics function to exclusive or (GXxor), saving the old
; function.

POLYFILL, [[x0,y0], [x0,y1], [x1,y1], $

[x1,y0]], /Device, Color=1

; Use POLYFlLL to select the area to be inverted, and
; immediately XOR a pixel value of 1 with the image currently
; displayed in that area. XORing every pixel with the binary
; equivalent of 1 ensures that only the lowest bit of the color is
; affected.

DEVICE, Set_Graphics_Function=oldg

; Restore the previous graphics function.

The default value for the Set_Graphics_Function keyword is GXcopy, which means that the source graphics from the current operation get copied into the window, destroying any graphics that were previously displayed there.

Interaction Between the Set_Write_Mask and the Set_Graphics_Function Keywords

You use the Set_Write_Mask keyword to specify the planes whose bits you are manipulating or the plane you want to use for the special effects. The way the two graphics patterns are combined depends on the value you provide for the Set_Graphics_Function keyword. For example, you could use the following commands:

DEVICE, Set_Graphics_Function=6
DEVICE, Set_Write_Mask=8

to extract the fourth bit (the binary equivalent of the decimal value 8) of the image in the current graphics window. The extracted plane is XORed (XOR is the graphics function specified by setting the Set_Graphics_Function keyword equal to 6) with the source pattern (the result of the current graphics operation). After the graphics function is implemented, the result is drawn in the current graphics window using whichever color(s) in the color table match the resultant value(s).

The graphics functions specified by the Set_Graphics_Function keyword operate on hardware pixel values. Unless the translation table is bypassed, like it is when displays with static (read-only) visual classes and private color tables are used, a color table index that represents a certain color will likely differ in value from the hardware pixel value that represents the same color. This can produce unexpected colors when you use the GX graphics functions.

An easy way to avoid getting such unexpected colors is to use Boolean OR, AND, XOR, and NOT operators, rather than the GX graphics functions. For details, see the following example.

Suppose that you are using your X display in one of the 8-bit visual classes, and a simple color translation table has been defined in the following way:

Now enter the following commands:

data = [1, 2, 3]

; Define a simple dataset to experiment with.

GXand = 1
PLOT, data, Color=5

; The data is plotted in hardware color 1, because color 5 gets 
; translated to hardware pixel value 1.

PLOT, data, Color=(5 AND 6)

; The data is plotted in hardware color 3, because 5 ANDed with 6
; equals 4, which then gets translated to hardware pixel value 3.

DEVICE, Set_Graphics_Function=GXand
PLOT, data, Color=6

; The data is plotted in hardware color 1, because color 5 gets 
; translated to hardware pixel value 1 and color 6 gets translated to
; hardware pixel value 7. Then, in hardware pixel values, 7 is ANDed
; with 1 and the result equals 1.

DEVICE, Translation=Transarr 

The result is a 256-element byte vector, Transarr. Element zero of Transarr contains the pixel value allocated for the first color in the PV-WAVE colormap, and so forth.

PV-WAVE provides methods for getting and setting X Window IDs for any PV-WAVE window. PV-WAVE also supports methods for setting and getting X Pixmap IDs for PV-WAVE windows.

To set the X Window ID for a PV-WAVE window, use the Set_Xwin_Id keyword with the WINDOW procedure. The X Window ID must be a valid, existing ID for the X server that PV-WAVE is using. When the Set_Xwin_Id keyword is used, PV-WAVE uses the X window associated with the ID; PV-WAVE does not create a new window. The programmer is responsible for synchronizing the use of this window by the two programs.

To get the X Window ID for a PV-WAVE window, use the Get_Win_ID keyword with the WINDOW procedure. The X Window ID returned from the WINDOW procedure may be passed to another program. The other program may then write into the PV-WAVE window. The programmer is responsible for synchronizing the use of this window by the two programs.

Similarly, the Get_Xpix_Id keyword can be used to get the X Pixmap ID.

---

CAUTION: The WDELETE procedure will delete all windows sharing a common X Window ID. For example:

---

WINDOW, 0, Get_Xwin_Id=New_Xwin_Id 
WINDOW, 1, Set_Xwin_Id=New_Xwin_Id 
WDELETE, 1

The command WDELETE, 1 deletes both windows 1 and 0.

Z-buffer Output

The Z-buffer allows you to create complex 3D plots, image warping to polygons, and transparency effects without special hardware.

To direct graphics output to the Z-buffer, enter the command:

SET_PLOT, 'Z'

This causes PV-WAVE to use the Z-buffer driver for producing graphical output. Once the Z-buffer driver is enabled via SET_PLOT, the DEVICE procedure is used to control its actions, as described in Controlling Z-buffer Output with DEVICE Keywords on page -86.

Use INFO, /Device to view the driver's current settings.

The following keywords to the DEVICE procedure provide control of the Z-buffer driver:

Close Deallocates the memory used by the buffers. The Z-buffer device is reinitialized if subsequent graphics operations are directed to the device.

Get_Graphics_Function See the description of the Get_Graphics_Function keyword in Controlling the X Driver with DEVICE Keywords on page -61.

Get_Write_Mask See the description of the Get_Write_Mask keyword in Controlling the X Driver with DEVICE Keywords on page -61.

Set_Character_Size A two-element vector that changes the standard width and height of the vector-drawn fonts. The first element in the vector contains the new character width, and the second element contains the height. By default, characters are approximately 8-pixels wide, with 12 pixels between lines.

Set_Colors Sets the number of pixel values, !D.N_Colors. This value is used by a number of routines to determine the scaling of pixel data and the default drawing index. Allowable values range from 2 to 256, and the default value is 256. Use this parameter to make the Z-buffer device compatible with devices with fewer than 256 color indices.

Set_Graphics_Function See the description of the Set_Graphics_Function keyword in Controlling the X Driver with DEVICE Keywords on page -61.

The Z-buffer allows you to use all graphics functions supported by the X driver.

Set_Resolution Two-element vector that sets the width and height of the buffers. The default size is 640-by-512. If this size is not the same as the existing buffers, the current buffers are destroyed and the device is reinitialized.

Set_Write_Mask See the description of the Set_Write_Mask keyword in Controlling the X Driver with DEVICE Keywords on page -61.

Example 1

This example demonstrates how graphics can be rendered in memory (into the Z-buffer) and then later displayed. The resulting image is shown in Figure B-6.

SET_PLOT, 'z'
SHADE_SURF, HANNING(23,23)
SURFACE, HANNING(23,23), /Noerase
img = TVRD(0,0,640,512)
SET_PLOT, 'x'
TV, img

Figure B-7

This example creates a single image composed of two intersecting objects drawn with hidden surfaces removed. This effect can only be accomplished with the Z-buffer. The resulting image is shown in Figure B-8.

dev_name = !D.Name

; Remember current graphics device

im = BYTARR(512,512)
OPENR, 1, FILEPATH(`mandril.img', SubDir='data' )

; Open the file containing the image.

READU, 1, im
CLOSE, 1
SET_PLOT, `z'
ERASE

; Erase the Z-buffer in case there was something in there before.

SHADE_SURF, HANNING(23,23), /Save

; Draw a surface.
; Remember the 3D viewing transform (/Save).

verts=[ [0,0,0], [20,0,0.5], [20,20,1], $
    [0,20,0.5] ]

; Create a 3D quadrilateral in data coordinates.

POLYFILL, Verts, Pattern = im, $
    Image_coord=[[0,0],[511,0],[511,511], $
    [0,511]], /T3d

; Draw the transformed quadrilateral with an image mapped
; onto it.

res = TVRD(0,0,640,512)
SET_PLOT, dev_name
TVSCL, res

; Notice how the two objects intersect.

Example 3

In this example, the same image from the previous example is created; however, this time maximum intensity projection is used to produce a transparency effect. The resulting image is shown in Figure B-9.

dev_name = !D.Name

; Remember current graphics device

im = BYTARR(512,512)
OPENR, 1, FILEPATH(`mandril.img', SubDir='data' )
READU, 1, im
CLOSE, 1
SET_PLOT, 'z' 
ERASE

; Erase the Z-buffer in case there was something in there before.

SHADE_SURF, HANNING(23,23), /Save

; Draw a surface.
; Remember the 3D viewing transform (/Save).

verts=[ [0,0,0], [20,0,0.5], [20,20,1], [0,20,0.5] ]

; Create a 3D quadrilateral in data coordinates.

POLYFILL, Verts, Pattern = im, $
    Image_coord=[[0,0],[511,0],[511,511], [0,511]], /T3d

; Draw the transformed quadrilateral with an image mapped
; onto it.

res = TVRD(0,0,640,512)
SET_PLOT, dev_name
TVSCL, res

; Notice how the two objects interact this time. You can partially see
; through the surface to the image passing through it.

Figure B-9 Resulting image from Example 3.

Figure B-10