Keywords Accepted by the IDL Devices

Set this keyword to select the ITC Avant Garde PostScript font.

AVERAGE_LINES

( The Regis Terminal Device )

Controls the method of writing images to the VT240. If this keyword is set, (default setting), 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.

BINARY

Set this keyword to set the encoding type for the CGM output file to binary.

BITS_PER_PIXEL

IDL 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. If you do not specify a value of 1, 2, 4, or 8, IDL selects the closest one.

It should be noted that many laser printers, including the original Apple Laserwriter are 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 apparent shades of grey 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.

BKMAN

Set this keyword to select the ITC Bookman PostScript font.

BOLD

Set this keyword to specify that the bold version of the current PostScript font should be used.

BOOK

Set this keyword to specify that the book version of the current PostScript font should be used.

BYPASS_TRANSLATION

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to bypass the translation tables, allowing direct specification of color indices. Color Translation Pixel values read via the TVRD function are not translated if this keyword is set, and the result contains the byte value of the actual pixel values present in the display.

By default, the translation tables are used with shared and static color tables. When using displays with private color tables, the translation tables are bypassed.

This keyword is accepted by the WIN device (for compatibility with the X device), but has no effect when set.

CLOSE

Set this keyword to deallocate the memory used by the Z-buffer. The Z-buffer device is reinitialized if subsequent graphics operations are directed to the device.

CLOSE_DOCUMENT

( See The Printer Device )

Set this keyword to have IDL send any buffered output to the currently selected printer. This keyword is applicable only when the printer device is selected. See The Printer Device for details.

CLOSE_FILE

( The CGM Device , The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device , The Regis Terminal Device , The Tektronix Device )

Set this keyword to have IDL output any buffered commands and close the current graphics file.

Caution: Under operating systems other than VMS, if you close the output file and then cause IDL to produce more output (e.g., by executing a new PLOT command), IDL will open the file again, causing the contents of the recently closed file to be lost. To avoid this, use the FILENAME keyword to specify a different file name or use SET_PLOT to disable the graphics driver, or be sure to print the closed output file before creating more output.

See the discussion of printing output files in Printing Graphics Output Files

COLOR

( The PCL Device , The PostScript Device )

Set this keyword to enable color PCL or PostScript output. See The PCL Device or The PostScript Device .

COLORS

( The CGM Device , The Tektronix Device )

This keyword specifies the maximum number of colors and the size of the color table used for output. The value of the system variable fields !D.N_COLORS and !D.TABLE_SIZE are set to this value and !P.COLOR is set to one less than this value.

For Tektronix Terminals Only

This keyword sets the number of colors supported by a 4100 series terminal. 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 will cause problems. Some Tektronix terminals will 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, 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.

COPY

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Use this keyword to copy a rectangular area of pixels from one region of a window to another. COPY should be set 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 as both the source and destination.

COURIER

Set this keyword to select the Courier PostScript font.

CURSOR_CROSSHAIR

( The Microsoft Windows Device , The X Windows Device )

Set this keyword to selects the crosshair cursor type. This is the IDL 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. 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_MASK

When the CURSOR_IMAGE keyword is used to specify a cursor bitmap, the CURSOR_MASK keyword can be used to simultaneously specify the mask that should be used. In the mask, bits that are set indicate bits in the CURSOR_IMAGE that should be seen and bits that are not set are "masked out".

By default, the CURSOR_IMAGE bitmap is used for both the image and the mask. This can cause the cursor to be invisible on a black background (because only black pixels are allowed to be displayed).

CURSOR_ORIGINAL

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to select the window system's default cursor. Under X Windows, it is the cursor in use by the root window when IDL starts. For the Macintosh and Microsoft Windows devices, it is the arrow pointer.

CURSOR_STANDARD

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

This keyword can be used to change the appearance of the cursor in IDL graphics windows.

For X Windows

This keyword selects one of the predefined cursors provided by the X Window system. The available cursors shapes are defined in the file cursorfonts.h in the directory /usr/include/X11 (Unix), or DECW$INCLUDE: (VMS). In order to use one of these cursors, you select the number of the cursor and provide it as the value of the CURSOR_STANDARD keyword. For example, the 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

For Microsoft Windows

The table below shows the values for CURSOR_STANDARD that result in different cursor shapes. For example, to change the cursor to an "I-beam" when the cursor is in an IDL graphics window, use the command:

DEVICE, CURSOR_STANDARD = 32513

Values for the
WIN device CURSOR_STANDARD
keyword
Cursor Shape	Value
Arrow	32512
I-Beam	32513
Hourglass	32514
Black Crosshair	32515
Up Arrow	32516
Size (Windows NT only)	32640
Icon (Windows NT only)	32641
Size NW-SE	32642
Size NE-SW	32643
Size E-W	32644
Size N-S	32645

For Macintosh

Setting the CURSOR_STANDARD keyword changes the cursor to a crosshair in IDL graphics windows.

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 lower left corner of the cursor image. This parameter is only applicable if CURSOR_IMAGE is provided. The cursor image is displayed top-down--the first row is displayed at the top.

DECOMPOSED

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

This keyword is used to control the way in which graphics color index values are interpreted when using displays with decomposed color ( TrueColor or DirectColor visuals). This keyword has no effect with other types of visuals.

Set this keyword to 1 to cause color indices to be interpreted as 3, 8-bit color indices where the least-significant 8 bits contain the red value, the next 8 bits contain the green value, and the most-significant 8 bits contain the blue value. This is the way IDL has always interpreted pixels when using visual classes with decomposed color.

Set this keyword to 0 to cause the least-significant 8 bits of the color index value to be interpreted as a PseudoColor index. This setting allows users with DirectColor and TrueColor displays to use IDL programs written for standard, PseudoColor displays without modification.

In older versions of IDL, color index values higher than !D.N_COLORS-1 were clipped to !D.N_COLORS-1 in the higher level graphics routines. In some cases, this clipping caused the exclusive-OR graphics mode to malfunction with raster displays. This clipping has been removed. Programs that incorrectly specified color indices higher than !D.N_COLORS-1 will now probably exhibit different behavior.

DEMI

Set this keyword to specify that the demi version of the current PostScript font should be used.

DEPTH

( The LJ Device )

The DEPTH keyword specifies the number of significant bits in a pixel. The LJ250 can support between 1 and 4 significant bits (known also as planes). The number of available colors is related to the number of significant planes by the equation:

Colors = 2^#planes

Therefore, the LJ250 can support 2, 4, 8, or 16 separate colors on a single page of output. The default is to use a single plane, producing monochrome output.

Since IDL is based around 8-bit pixels, it is necessary to define which bits in a 8-bit pixel are used by the LJ250 driver, and which are ignored. When using a depth of 1 (monochrome), dithering techniques are used to render images. In this case, all 8 bits are used. If more than a single plane is used, the least significant n bits of a 8-bit pixel are used, where n is the selected depth. For example, using a depth of 4, pixel values of 15, 31, and 47 are all considered to have the value 15 because all three values have the same binary representation in their 4 least significant digits.

When the depth is changed, the standard color map given in Table 7-5 of the LJ250/LJ252 Companion Color Printer Programmer Reference Manual is automatically loaded. Therefore, color maps should be loaded with TVLCT after changing the depth.

DIRECT_COLOR

Set this keyword to select the DirectColor visual. The value of the keyword represents the number of bits per pixel. This keyword has effect only if no windows have been created. Visual classes are discussed in more detail in X Windows Visuals

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. Values for the HP-GL Eject Keyword describes the possible values.

Values for the HP-GL Eject Keyword
Value	Meaning
0	Do nothing. Note that this is likely to cause one page to plot over the previous one, so you should limit yourself to one page of output per file. This is the default.
1	Use the sheet feeder to load the next page.
2	Put the plotter off-line at the beginning of each page after the first.

Many HP-GL plotters lack a sheet feeder, and require the user to load the next page manually. Therefore, the default action is for IDL 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 will want to issue the command:

DEVICE, /EJECT

to tell IDL 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 HP-GL 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 the user to replace the paper. When the user puts 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.

ENCAPSULATED

Set this keyword to create an encapsulated PostScript file, suitable for importing into another document (e.g., a LaTeX or FrameMaker document).

NOTE: You must explicitly set this keyword to zero to create "regular" PostScript output after creating encapsulated output. (That is, like most keyword settings to the DEVICE procedure, the setting "sticks" until you change it, or until you quit IDL.)

Normally, IDL assumes that its PostScript-generated output will be sent directly to a printer. It therefore includes PostScript commands to position 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 non-zero, IDL does not generate these commands.

IDL 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 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 or scaling factor once any graphics commands have been issued. If you need to change these parameters, use the FILENAME keyword to start a new file.

ENCODING

Set this keyword to set the CGM encoding type for the output file. Valid values are: 1 (binary encoding, the default), 2 (text encoding), and 3 (NCAR binary encoding). The encoding type can only be changed when there is no CGM file open.

FILENAME

( The CGM Device , The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device , The Regis Terminal Device , The Tektronix Device )

Normally, all generated output is sent to a file named idl.xxx where xxx is the lowercase name of the device shown in IDL Graphics Output Devices . The FILENAME keyword can be used to change these defaults. If FILENAME is specified:

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

2. The specified file is opened for subsequent graphics output.

HP-GL Only

Under Unix, if you wish to send HP-GL output directly to a plotter without generating an intermediate file, you should specify the device special file for the plotter as the argument to FILENAME. For example, if your plotter is connected to a serial input/output port known on your system as /dev/ttya , you would issue the command:

DEVICE, FILENAME='/dev/ttya'

All subsequent HP-GL output is sent directly to the plotter connected to serial port /dev/ttya .

FLOYD

( The LJ Device , The Macintosh Display Device , The PCL Device , The X Windows Device )

Set this keyword to select the Floyd-Steinberg method of dithering. This algorithm distributes the error, due to displaying intermediate shades in either black or white, to surrounding pixels. This method generally gives the most pleasing results but requires the most computer time.

FONT

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

This keyword is now obsolete and has been replaced by the SET_FONT keyword. Code that uses the FONT keyword will continue to function as before, but we suggest that all new code use SET_FONT.

FONT_INDEX

An integer representing the font index to be mapped to the current PostScript font.

Normally the font specification keywords (AVANTGARDE, etc.) take effect immediately to change the current font. The FONT_INDEX keyword alters this behavior. The current font is not changed. Instead, the specified font is mapped to the specified font index. This mapping can then be used within text strings to change the font in the middle of the string. Using PostScript Fonts

FONT_SIZE

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

GET_CURRENT_FONT

( The Macintosh Display Device , See The Printer Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to a named variable in which the name of the current font is returned as a scalar string. A null string is returned if the Windows font is the default font. If the current device is PRINTER, the current printer font is returned.

GET_FONTNAMES

( The Macintosh Display Device , See The Printer Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to a named variable in which a string array containing the names of available fonts is returned. If no fonts are found, a null scalar string is returned. This keyword must be used in conjunction with the FONT keyword. Set the FONT keyword to a scalar string containing the name of the desired font or a wildcard.

GET_FONTNUM

( The Macintosh Display Device , See The Printer Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to a named variable in which the number of fonts available to your installation is returned. This keyword must be used in conjunction with the FONT keyword. Set the FONT keyword to a scalar string containing the name of the desired font or a wildcard.

GET_GRAPHICS_FUNCTION

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device , The Z-Buffer Device )

Set this keyword to a named variable that returns the value of the current graphics function (which is set with the SET_GRAPHICS_FUNCTION keyword). This can be used to remember the current graphics function, change it temporarily, and then restore it. See the SET_GRAPHICS_FUNCTION keyword for an example.

GET_SCREEN_SIZE

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to a named variable in which to return a two-word array that contains the width and height of the server's screen, in pixels.

NOTE: For the Macintosh, anchoring the Command Input Line reduces the amount of available screen space.

GET_VISUAL_NAME

(MAC, WIN, The X Windows Device )

Set this keyword equal to a named variable in which a string containing the name of the current visual class IDL is using is returned. Possible return values are:

StaticGray (X only)
GrayScale (X only)
StaticColor (X only)
PseudoColor
TrueColor
DirectColor (X only)

Under X, if no connection to the X server has been established when the DEVICE procedure is called with this keyword set, a new connection is made.

GET_WINDOW_POSITIONrf

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Set this keyword to a named variable that returns a two-element array containing the (X,Y) position of the lower left corner of the current window on the screen. The origin is also in the lower left corner of the screen.

GET_WRITE_MASK

( The Microsoft Windows Device , The X Windows Device )

Specifies the name of a variable to receive the current value of the write mask.

GIN_CHARS

The number of characters IDL is to read 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 IDL 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 IDL prompt.

GLYPH_CACHE

( The Macintosh Display Device , See The Printer Device , The PostScript Device , The Microsoft Windows Device , The Z-Buffer Device )

Set this keyword to a scalar specifying the maximum number of glyphs to cache at any given time. The first time a glyph from a TrueType font is used, it is tessellated into triangles. These triangles are cached so that the tessellation step is not repeated for each use of that glyph. If the glyph cache fills, the least used glyph will be released before a new glyph is generated and cached. The default is 256.

HELVETICA

Set this keyword to select the Helvetica PostScript font.

INCHES

( The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device )

Normally, the XOFFSET, XSIZE, YOFFSET, and YSIZE keywords are specified in centimeters. However, if INCHES is present and non-zero, they are taken to be in inches instead.

INDEX_COLOR

( See The Printer Device )

Set this keyword to place the printer device in index color mode. This is the default. This keyword is applicable only when the printer device is selected. See The Printer Device for details.

ISOLATIN1

Set this keyword to use Adobe ISO Latin 1 font encoding with any font that supports such coding. Use of this keyword allows access to many commonly-used foreign characters.

ITALIC

Set this keyword to specify that the italic version of the current PostScript font should be used.

LANDSCAPE

( The HP-GL Device , The LJ Device , The PCL Device , See The Printer Device , The PostScript Device )

IDL normally generates plots with portrait orientation (the abscissa is along the short dimension of the page). If the LANDSCAPE keyword is set, landscape orientation (abscissa along the long dimension of the page) is used instead. Note that explicitly setting LANDSCAPE=0 is the same as setting the PORTRAIT keyword.

If the current device is PRINTER, and a page is open in the printer, it is closed and a new page set to landscape layout is started.

NOTE: The ability to set a printer to landscape mode is printer-driver dependent. Your printer may not support this functionality; use the system native print setup dialog to set the orientation of the print job.

LIGHT

Set this keyword to specify that the light version of the current PostScript font should be used.

MEDIUM

Set this keyword to specify that the medium version of the current PostScript font should be used.

NARROW

Set this keyword to specify that the narrow version of the current PostScript font should be used.

NCAR

Set this keyword to set the encoding type for the CGM output file to NCAR binary.

The NCAR Binary Encoding

The NCAR binary encoding is used exclusively by the NCAR graphics package. Version 3.01 of NCAR View ( ctrans , ictrans , and cgm2ncgm ) does not correctly handle the following graphic elements:

Cell arrays (raster images) with an odd number of pixels in the X dimension. Solution: specify an even number of pixels for the X dimension or make the image one column wider and fill with zeros.
Raster images drawn in top down order. Solution: invert the image prior to using TV or TVSCL and do not use the /ORDER keyword. For example:

TV, image

TV, ROTATE(image, 7) ; Draw image top to bottom.

OBLIQUE

Set this keyword to specify that the oblique version of the current PostScript font should be used.

OPTIMIZE

( The PCL Device )

It is desirable, though not always possible, to compress the size of the PCL 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.

Consult the programmers manual for your printer to determine it supports the required escape sequences. 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). The HP LaserJet II does not support this optimization level. The DeskJet PLUS does.

2. IDL 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. Note: This optimization can be very slow on some devices (such as the DeskJet PLUS). On such devices, it is best to avoid this optimization level.

ORDERED

( The LJ Device , The Macintosh Display Device , The PCL Device , The X Windows Device )

Set this keyword to select the ordered dither method. This introduces a pseudo-random error into the display by using a 4 by 4 "dither" matrix, yielding 16 apparent intensities. This is the default method.

Macintosh Only

This keyword is identical to the THRESHOLD keyword.

OUTPUT

( The HP-GL Device , The PostScript Device )

Specifies a scalar string that is sent directly to the graphics output file without any processing, allowing the user to send arbitrary commands to the file. Since IDL does not examine the string, it is the user's responsibility to ensure that the string is correct for the target device.

PALATINO

Set this keyword to select the Palatino PostScript font.

PIXELS

( The LJ Device , The PCL Device )

Normally, the XOFFSET, XSIZE, YOFFSET, and YSIZE keywords are specified in centimeters. However, if the PIXELS keyword is set, 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.

PLOT_TO

( The Regis Terminal Device , The Tektronix Device )

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. Graphic output may be saved in files for later playback, redirected to other terminals, or to devices that can accept Textronix 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. Alternatively, you can use the TTY keyword, described below.

If the specified unit number is zero then Tektronix output to the file is stopped.

PLOTTER_ON_OFF

There are some configurations in which a HP-GL 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 HP-GL commands. Another escape sequence is sent at the end of the HP-GL 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 IDL to generate the necessary on/off commands. If present and non-zero, 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.

POLYFILL

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

Different implementations of HP-GL 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 HP-GL driver cannot check for calls to POLYFILL that specify too many points. Therefore, it is possible for the user to produce HP-GL 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 will have to break that polygon filling operation into multiple smaller operations.

PORTRAIT

( The HP-GL Device , The LJ Device , The PCL Device , See The Printer Device , The PostScript Device )

Set the PORTRAIT keyword to generate plots using portrait orientation. Portrait orientation is the default. Note that explicitly setting PORTRAIT=0 is the same as setting the LANDSCAPE keyword.

If the current device is PRINTER, and a page is open in the printer, it is closed and a new page set to portrait layout is started.

NOTE: The ability to set a printer to portrait mode is printer-driver dependent. Your printer may not support this functionality; use the system native print setup dialog to set the orientation of the print job.

PREVIEW

Set this keyword to add a "device independent screen preview" to the PostScript output file, in encapsulated PostScript interchange format (EPSI). Use this keyword only with encapsulated output. Many, but certainly not all, desktop publishing and word processing programs will display this screen preview when the file is imported into a document. The preview is only a crude approximation and does not include all elements of the final PostScript output. This feature is not available under VMS.

P RINT_FILE

( The Microsoft Windows Device )

Set this keyword to the name of a file (e.g., PostScript or PCL) to be sent to the currently-selected Windows printer. IDL performs no type checking on this file before sending it to the printer. Therefore, if you have a PostScript printer selected and you send a file that contains no valid PostScript information, you'll simply get text output.

To send the file MYFILE.PS to the currently-selected Windows printer, enter:

DEVICE, PRINT_FILE='MYFILE.PS'

PSEUDO_COLOR

( The Macintosh Display Device , The X Windows Device )

If this keyword is present, the PseudoColor visual is used. The value of the keyword represents the number of bits per pixel to be used. This keyword has effect only if no windows have been created. Visual classes are discussed in more detail in X Windows Visuals

Macintosh Only

Setting this keyword causes all screen manipulations to be done in 8-bit mode. The value of the keyword is ignored, as is the current bit-depth of the monitor.

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 <ESC>2 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 resetting string is <ESC>%!1 , which selects the ANSI code mode.

RESOLUTION

( The LJ Device , The PCL Device )

PCL Only

The resolution at which the PCL printer will work. 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.

LJ250 Only

The resolution at which the LJ printer will work. LJ supports resolutions of 90 and 180 dots per inch. The default is 180 dpi. Lower resolution gives smaller output files and a larger selection of colors, while higher resolution gives superior quality.

RETAIN

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

Use this keyword to specify 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 under Backing Store The possible values for this keyword are summarized in Allowed Values for the RETAIN Keyword . If RETAIN is not used to specify the default method, method 1 (server-supplied backing store) is used.

Microsoft Windows Only

The initial value of this parameter can be set by selecting File-Preferences from the menu bar. Backing Store

A Note on Reading Data from Windows

On some systems, when backing store is provided by the window system (RETAIN=1), reading data from a window using TVRD may cause unexpected results. For example, data may be improperly read from the window even when the image displayed on screen is correct. Having IDL provide the backing store (RETAIN=2) ensures that the window contents will be read properly. These types of problems are described in more detail in the documentation for TVRD. Unexpected Results Using TVRD with X Windows

SCALE_FACTOR

( See The Printer Device , The PostScript Device )

Specifies a scale factor applied to the entire plot. The default value is 1.0, allowing output to appear at its normal size. SCALE_FACTOR is used to magnify or shrink the resulting output.

The SCALE_FACTOR keyword behaves slightly differently in the context of the PRINTER device than it does in the context of the PS device.

When the current device is PRINTER, the SCALE_FACTOR keyword is designed to emulate a scalable resolution setting on the printer. For example, if you have a 300 x 300 pixel image--stored in the variable image --the following IDL commands will print image in a 0.5 inch square on a 600 dpi printer:

SET_PLOT, 'printer'

TV, image

Setting SCALE_FACTOR to 2 will scale the image to a 1 inch square on the same 600 dpi printer:

SET_PLOT, 'printer'

DEVICE, SCALE_FACTOR=2

TV, image

The output of IDL's Direct Graphics routines (CONTOUR, PLOT, SURFACE, etc.) is automatically scaled to fill the available drawing area. As a result, the following IDL commands will produce two identical copies of the same output on any printer:

SET_PLOT, 'printer'

PLOT, data

DEVICE, SCALE_FACTOR=2

PLOT, data

SCHOOLBOOK

Set this keyword to select the New Century Schoolbook PostScript font.

SET_CHARACTER_SIZE

( The CGM Device , The HP-GL Device , The LJ Device , The Macintosh Display Device , The PCL Device , See The Printer Device , The PostScript Device , The Regis Terminal Device , The Tektronix Device , The Microsoft Windows Device , The X Windows Device , The Z-Buffer Device )

Set this keyword equal to a two-element vector to specify the font size and line spacing (leading) of vector and TrueType fonts, and the line spacing of device fonts. The way that the value of this vector determines character size is not completely intuitive.

The vector specified to the SET_CHARACTER_SIZE keyword sets the values of the X_CH_SIZE and Y_CH_SIZE fields in the structure. These values describe the size of the rectangle that contains the "average" character in the current font. (It is not important what the "average" character is; it is used only to calculate a scaling factor that will be applied to all of the characters in the font.) The first element specifies the width of the rectangle in device units (usually pixels), and the second element specifies the height.

For vector and TrueType fonts, the height of the "average" character is determined by the width of the rectangle. The aspect ratio of the "average" character remains fixed; the character is scaled so that its width fits in the specified rectangle. The resulting scale factor is then applied to all of the characters in the font. The amount of spacing between lines (baseline to baseline) is determined explicitly by the height of the rectangle.

For device fonts, the character size is fixed. When the device font system is in use, the first element of the vector specified to SET_CHARACTER_SIZE is silently ignored, and only the line-spacing value is used.

NOTE: Changing between font systems (and sometimes changing from one font to another within the same font system) can also change the !D structure, so do not assume that the character size you have set is preserved when you change fonts.

SET_COLORMAP

( The PCL Device )

Set this keyword to a 14,739 (= 3 17³ ) element byte vector containing the RGB-to-printer color translation table for a color PCL printer. The default table is for an HP Deskjet 500C printer.

The translation table is divided into red, green, and blue planes of 4913 (=17³ ) elements each. For a given RGB triple, the offset into each plane is calculated as follows:

Offset = (Red/16)*289 + (Green/16)*17 + (Blue/16)

Thus, if the RGB triple is [16,32,160], the offset into each plane is 333. The printer will use the value at element 332 of the translation table as the red value, the value at element 5245 (=4913+332) as the green value, and the value at element 10158 (=9826+332) as the blue value.

The following example shows how to scale an existing colortable for use by a PCL printer.

SET_PLOT, 'X' ; Set the plot window to the X device.

WINDOW,0,XS=300,YS=300 ; Create a window.

LOADCT,13 ; Load a color table.

TVLCT,r,g,b,/GET ; Read color table values into variables.

r2=CONGRID(r,4913) ; Re-size color table variables.

g2=CONGRID(g,4913)

b2=CONGRID(b,4913)

colormap=[r2,g2,b2] ; Create 14,739-element color map.

SET_PLOT, 'PCL' ; Change to the PCL device.

DEVICE, FILE = 'pcl.pcl', RESOLUTION = 300, $

/COLOR, SET_COLORMAP = colormap
; Set file name, resolution, color, and color map.

TVSCL,DIST(900) ; Display an image.

DEVICE,/CLOSE ; Close the device.

NOTE: The color table used need not be one of IDL's predefined tables.

SET_COLORS

Sets the number of pixel values, !D.N_COLORS and !D.TABLE_SIZE. This value is used by a number of IDL 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 colors indices.

SET_FONT

( The Macintosh Display Device , See The Printer Device , The PostScript Device , The Microsoft Windows Device , The Z-Buffer Device )

Set this keyword to a scalar string specifying the name of the font used when a hardware or TrueType font is selected. Note that hardware fonts cannot be rotated, scaled, or projected, and that the "!" commands for formatting may not work. When generating three-dimensional plots, it is best to use the vector-drawn or TrueType characters. Note that for the PS device, only one hardware font (other than the predefined fonts set via the fontname keywords, such as /AVANTEGARDE) may be loaded at a time.

Note on the FONT Keyword

The SET_FONT keyword was introduced with IDL version 5.1 and replaces the FONT and USER_FONT keywords used in previous versions.

Using TrueType Fonts

For TrueType fonts, the specified font name must exactly match one of the names in the first column of the ttfont.map file in the resource/fonts/tt directory or (on Macintosh and Windows platforms)the name of an installed font. See for details on the ttfont.map file and for a listing of TrueType fonts distributed with IDL. Note that you must include the TT_FONT keyword to indicate that the font specified is a TrueType font. For example, the following sets the font to the font to the TrueType font Helvetica Bold Italic:

DEVICE, SET_FONT='Helvetica-BoldItalic', /TT_FONT

NOTE: You can append additional TrueType fonts to the ttfont.map file if desired; on Macintosh and Windows platforms, additional fonts can also be added via the normal font installation procedures for your system. Research Systems cannot guarantee that TrueType fonts you add will be satisfactorily tessellated or displayed. See for details.

Using Hardware Fonts

Because device fonts are specified differently on different platforms, the synatax of the fontname string depends on which platform you are using.

Unix and VMS

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 vector drawn text. X Windows users can use the xlsfonts command to list available X Windows fonts.

On some machines, fonts are kept in subdirectories of /usr/lib/X11/fonts .

For example, to select the font 8X13:

!P.FONT = 0

DEVICE, SET_FONT = '8X13'

Microsoft Windows

The SET_FONT keyword should be set to a string with the following form:

DEVICE, SET_FONT=" font * modifier ₁ * modifier ₂ *... modifier _n "

where the asterisk (*) acts as a delimiter between the font's name ( font ) and any modifiers. The string is not case sensitive. Modifiers are simply "keywords" that change aspects of the selected font. Valid modifiers are:

For font weight: THIN, LIGHT, BOLD, HEAVY
For font quality: DRAFT, PROOF
For font pitch: FIXED, VARIABLE
For font angle: ITALIC
For strikeout text: STRIKEOUT
For underlined text: UNDERLINE
For font size: Any number is interpreted as the font height in pixels.

For example, if you have Garamond installed as one of your Windows fonts, you could select 24-pixel cell height Garamond italic as the font to use in plotting. The following commands tell IDL to use hardware fonts, change the font, and then make a simple plot:

!P.FONT = 0

DEVICE, SET_FONT = "GARAMOND*ITALIC*24"

PLOT, FINDGEN(10), TITLE = "IDL Plot"

This feature is compatible with TrueType and Adobe Type Manager (and, possibly, other type scaling programs for Windows). If you have TrueType or ATM installed, the TrueType or PostScript outline fonts are used so that text looks good at any size.

Macintosh

The SET_FONT keyword should be set to a string with the following form:

DEVICE, SET_FONT=" font * modifier ₁ * modifier ₂ *... modifier _n "

For font weight: BOLD
For font angle: ITALIC
For font width: CONDENSED, EXTENDED
For outlined text: OUTLINE, SHADOW
For underlined text: UNDERLINE
For font size: Any number is interpreted as the font size, in points.

For example, if you have Garamond installed, you could select 24-point Garamond italic as the font to use in plotting. The following commands tell IDL to use hardware fonts, change the font, and then make a simple plot:

IDL> !P.FONT = 0

IDL> DEVICE, SET_FONT = "GARAMOND*ITALIC*24"

IDL> PLOT, FINDGEN(10), TITLE = "IDL Plot"

SET_GRAPHICS_FUNCTION

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device , The Z-Buffer Device )

Most window systems allow 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 Graphic Function Codes . The default graphics function is GXcopy, which causes new pixels to completely overwrite any previous pixels. Not all functions are available on all window systems.

Graphic Function Codes
Logical Function	Code	Definition
GXclear	0	0
GXand	1	source AND destination
GXandReverse	2	source AND (NOT destination)
GXcopy	3	source
GXandInverted	4	(NOT source) AND destination
GXnoop	5	destination
GXxor	6	source XOR destination
GXor	7	source OR destination
GXnor	8	(NOT source) AND (NOT destination)
GXequiv	9	(NOT source) XOR destination
GXinvert	10	(NOT destination)
GXorReverse	11	source OR (NOT destination)
GXcopyInverted	12	(NOT source)
GXorInverted	13	(NOT source) OR destination
GXnand	14	(NOT source) OR (NOT destination)
GXset	15	1

For example, the following code segment inverts the bottom bit in the rectangle defined by its diagonal corners ( x ₀ , y ₀ ) and ( x ₁ , y ₁ ):

DEVICE, GET_GRAPHICS_FUNCTION = oldg, SET_GRAPHICS_FUNCTION = 6
; Set graphics function to exclusive or (GXor), and save the old function.

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

/DEVICE, COLOR=1; Use POLYFILL to select the area to be inverted. The source pixel value is 1.

DEVICE, SET_GRAPHICS_FUNCTION=oldg ; Restore the previous graphics function.

SET_RESOLUTION

Set this keyword to a two-element vector that specifies the width and height of the Z-buffers. The default size is 640 by 480. If this size is not the same as the existing buffers, the current buffers are destroyed and the device is reinitialized.

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.

SET_TRANSLATION

This keyword can be used to allow multiple, simultaneous IDL sessions to use the same colors from a shared colormap. Use this keyword before the X connection is established (i.e., before a window is created), IDL will use the shared color map without allocating any additional colors, and will not load a grayscale ramp as is usually done when the X server starts up. The following example shows two cooperating IDL processes sharing the same colormap:

Execute the following commands in the first IDL session:

WINDOW, GET_X_ID = a

DEVICE, TRANSLATION = t

OPENW, 1, 'junk.dat'

WRITEU, 1, a, !D.N_COLORS, t[0:!D.N_COLORS-1]

CLOSE, 1

LOADCT, 3

Execute the following commands in the second IDL session:

OPENR, 1, 'junk.dat'

a=0L

n=0L

READU,1, a, n

t = BYTARR(n)

READU, 1, t

CLOSE, 1

DEVICE, SET_TRANSLATION = t

WINDOW, COLORS=n, SET_X_ID=a

TV, DIST(256)

SET_WRITE_MASK

( The X Windows Device , The Z-Buffer Device )

Sets the write mask to the specified value. For an n -bit system, the write mask can range from 0 to 2ⁿ -1.

STATIC_COLOR

Use this keyword to select the X Windows StaticColor visual. The value of the keyword represents the number of bits per pixel to be used. This keyword has effect only if no windows have been created. Visual classes are discussed in more detail in X Windows Visuals

STATIC_GRAY

Use this keyword to select the X Windows StaticGray visual. The value of the keyword represents the number of bits per pixel to be used. This keyword has effect only if no windows have been created. Visual classes are discussed in more detail in X Windows Visuals

SYMBOL

Set this keyword to select the Symbol PostScript font.

TEK4014

Set this keyword to specify 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. Normally, IDL sends 10-bit coordinates. 12-bit coordinates are compatible with most terminals, even those without the full resolution, but require more characters to send.

NOTE: The 4014 and the 4100 modes can be used together. The coordinate system IDL uses for the Tektronix is 0 to 4095 in the X direction and 0 to 3120 in the Y direction, even when not in the 4014 mode. In the 10-bit case the internal coordinates are divided by 4 prior to output.

TEK4100

Set this keyword to indicate that the terminal is a 4100 or 4200 series terminal. The use of color, ANSI and Tektronix mode switching, hardware line styles, and pixel output with the TV procedure is supported with these terminals. Also, text is output differently.

TEXT

Set this keyword to set the encoding type for the CGM output file to text.

THRESHOLD

( The LJ Device , The Macintosh Display Device , The PCL Device , The X Windows Device )

Set this keyword to select the threshold algorithm--the simplest dithering method. The value of this keyword is the threshold to be used. This algorithm simply compares each pixel against the given threshold, usually 128. If the pixel equals or exceeds the threshold the display pixel is set to white, otherwise it is black.

Macintosh Only

Set this keyword to use the Macintosh's default thresholding. Values greater than one cause the keyword to be set but are otherwise ignored.

TIMES

Set this keyword to select the Times-Roman PostScript font.

TRANSLATION

( The Macintosh Display Device , The Microsoft Windows Device , The X Windows Device )

As discussed in Shared Colormaps , using the shared colormap (normally recommended) causes IDL to translate between IDL 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, use the command:

DEVICE, TRANSLATION=TRANSARR

where TRANSARR is a named variable into which the translation array is stored. The result is a 256-element byte vector. Element zero of the vector contains the pixel value allocated for the first color in the IDL colormap, and so forth.

Microsoft Windows Only

This keyword is accepted by the WIN device, for compatibility with the X Windows driver, but simply returns a 256-element vector where each element has the value of its subscript (0 to 255).

TRUE_COLOR

( The Macintosh Display Device , See The Printer Device , The X Windows Device )

Use this keyword to select TrueColor visuals. The value of the keyword represents the number of bits per pixel to be used. This keyword has effect only if no windows have been created. Visual classes are discussed in more detail in X Windows Visuals . If the current device is PRINTER, the printer is placed in RGB or true-color mode if the value of the TRUE_COLOR keyword is greater than zero (the number of bits per pixel specified is ignored.)

Macintosh Only

For best results, set TRUE_COLOR equal to 24 after setting the Color Depth to Millions from the Monitors Control Panel in the Apple menu.

TT_FONT

( The Macintosh Display Device , See The Printer Device , The X Windows Device , The X Windows Device , The Z-Buffer Device )

Set this keyword to indicate that the font set via the SET_FONT keyword (either to set the fontname or to retrieve fontnames in conjunction with the GET_FONTNAMES or GET_FONTNUM keywords) should be treated as a TrueType font.

TTY

( The Regis Terminal Device , The Tektronix Device )

Set this keyword to specify that output should be sent to the terminal at the same time that it is being sent to a file due to the FILENAME or PLOT_TO keywords. A zero value causes output to go only to the file. If no output file is in use, this keyword has no effect.

USER_FONT

This keyword is now obsolete and has been replaced by the SET_FONT keyword. Code that uses the USER_FONT keyword will continue to function as before, but we suggest that all new code use SET_FONT.

VT240, VT241

( The Regis Terminal Device )

Set this keyword to configure the REGIS device for VT240 series terminals.

VT340, VT341

( The Regis Terminal Device )

Set this keyword to configure the REGIS device for VT340 series terminals.

WINDOW_STATE

( The Microsoft Windows Device , )

Set this keyword to a named variable that returns an array containing one element for each possible window. Array element i contains a 1 if window i is open, otherwise it contains a 0.

XOFFSET

( The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device )

Specifies the X position, on the page, of the lower left corner of output generated by IDL. XOFFSET is specified in centimeters, unless INCHES is specified. Positioning Graphics Output

PostScript Only

SCALE does not affect the value of XOFFSET.

XON_XOFF

If present and non-zero, 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

( The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device )

Specifies the width of output generated by IDL. XSIZE is specified in centimeters, unless INCHES is specified.

PostScript Only

SCALE modifies the value of XSIZE. Hence, the following statement:

DEVICE,/INCHES,XSIZE=7.0,SCALE_FACTOR=0.5

results in a real width of 3.5 inches.

YOFFSET

( The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device )

Specifies the Y position, on the page, of the lower left corner of output generated by IDL. YOFFSET is specified in centimeters, unless INCHES is specified. Positioning Graphics Output

NOTE: The corner of the page from which the Y offset is measured (lower or upper left) differs on various devices. Read the device specific information in the following sections to determine how this is handled for your device.

PostScript Only

SCALE does not affect the value of YOFFSET.

YSIZE

( The HP-GL Device , The LJ Device , The PCL Device , The PostScript Device )

Specifies the height of output generated by IDL. YSIZE is specified in centimeters, unless INCHES is specified.

PostScript Only

SCALE modifies the value of YSIZE. Hence, the following statement:

DEVICE,/INCHES,YSIZE=5.0,SCALE_FACTOR=0.5

results in a real width of 2.5 inches.

LJ250 Only

Changing the size, depth, or orientation of the output causes the current page to be sent to the file. The effect is identical to calling the ERASE procedure.

ZAPFCHANCERY

Set this keyword to select the ITC Zapf Chancery PostScript font.

ZAPFDINGBATS

Set this keyword to select the ITC Zapf Dingbats PostScript font.

Z_BUFFERING