     Syntax: DEVICE WORD [ rest_of_line ]
             DEVICE INTEGER [ WORD ] [ rest_of_line ]
             DEVICE META WORD
             DEVICE META CLOSE

(The DEVICE INTEGER form is retained for historical interest and backwards compatibility only.)

Choose a device to plot to. Exactly which devices are available depends on your hardware configuration and how SM was compiled. You can list available devices with the LIST DEVICE command (see List). When you specify a device the previous device is closed, which may lead to some action being taken (for example, sending a plot to a printer).

When a device is opened it is looked up by name in the graphcap file (see Graphcap). In some cases all the information that SM needs to plot to the device is available there (for example xterm or postscript); such devices are referred to as stdgraph devices. Otherwise the graphcap entry will contain the name of the real device driver, for example x11. Anything else on the line is passed to the device driver. In particular, for the stdgraph devices an argument that is not specifically processed by the device is taken to be the name of a file to save the plot in. Thus device postscript foo.ps creates a plot in a file called foo.ps (This isn't actually the preferred way to create a postscript file; it's better to use a specialised device such as postfile (see Postscript), or at least to say device postscript ":SY=mv $F foo.ps:" (see Stdgraph).)

The pseudo-device META is special (see Meta). It is used to support metafiles, which allow you to save a plot as you display it, and finally send it to a different device.

Especially for hardcopy devices, you may have to specify which one you want, e.g. DEVICE postscript latypus. Because this depends on how your local graphcap was configured, you'll have to see your Guru for guidance; see Graphcap.

When a device is opened, it is set to the current CTYPE, LWEIGHT, and LTYPE, and the proper aspect ratio is chosen to make text and plotted points look nice. It also looks for an entry foreground in your .sm file, and uses it as the default colour for the device (this overrides any default that the device driver may have specified). The device driver may (or may not) choose to honour a background entry as well. These colours may be specified either as names (see CTYPE), or the background colour may be given as a set of three numbers, which are interpreted as the red, green, and blue intensities in the range 0 - 255. Some devices may allow you a wider selection of background names; for example the Xwindows driver allows any name from the colour database.

If you want to use some foreground colour that CTYPE doesn't usually understand you must define it before opening the device. For example, after defining the macro

     add_colour 4 ## add a colour to the standard set. Usage: name r g b
                  CTYPE=<0 255 0 255 0 0 0 255 255 $2> + \
                      256*(<0 255 0 0 255 0 255 0 255 $3> + \
                            256*<0 255 0 0 0 255 255 255 0 $4>)
                  ctype=<default white black red green blue cyan magenta yellow $1>

you could say add_colour gray 200 200 200, after which `gray' would be a perfectly good `foreground' colour.

Different ways of plotting to the same device (e.g. portrait or landscape) are accommodated by using different drivers (e.g. postport and postland for postscript devices) rather than some magic command to SM.

The NULL device

DEVICE nodevice is always available; it is a bit bucket where plot commands may be sent never to be seen again, the equivalent of /dev/null (under unix) or nl: under VMS.

It is useful because it is always available; it's the current device when SM is started. Because SM submits plots only when the current device is closed, and because opening nodevice closes the current device, it is also used by the hardcopy command (in fact hardcopy is a macro that expands to DEVICE nodevice).

Borland Graphics on a PC

SM works on a PC running DOS either by using Borland's graphics or windows (see the section on MS-Windows); this section describes the former. SM was ported to run under DOS by Laurent Bartholdi, who also wrote the BGI and MS-Windows device drivers. He gets all the credit for the PC version of SM, but of course he is not responsible for any remaining bugs (some of which we almost certainly created while merging the PC and regular versions).

The graphics drivers, the .bgi files, are assumed to be in a directory given by the DOS BGIPATH environment variable; alternatively you can specify a bgipath variable in your .sm file.

The DEVICE command takes two optional arguments: DEVICE bgi devtype mode. The first, devtype, is the type of hardware that you are running. If you want the driver to try to figure this out for itself, use DEVICE bgi detect (this is the default if you omit devtype entirely); for a listing of possibilities say DEVICE bgi ?. The second argument, mode, determines how SM switches between screen and graphics modes. Your options are none, swap (the default), or switch; experiment to see which works better for you. At present, a certain amount of `snow' is left at the top of the graphics screen. This is very dependent on the details of your graphics card, and we see no general way to prevent its appearance.

Once you have decided what options you like best, you can set a variable stdmode in your .sm file (e.g. to detect swap) to save yourself some typing.

There is a `hot key', ALT-F1, that can be used to toggle between text and graphics mode.

The current return value of the function coreleft is available as $coreleft (which is like any other DEFINE var | variable).

OS/2 Presentation Manager

The OS2PM driver is used to display graphics in a Presentation Manger graphics window under OS/2 v2.x (you should specify your terminal as os2pc). Two optional arguments are currently supported:

-n
     Disable all backing for the graphics window. This will significantly increase the drawing speed, but the contents of the graphics window will not be redrawn when portions of the window are uncovered or when the window is resized.

-gWxH
     Specify the window geometry. The W and H parameters should contains the WIDTH and HEIGHT of the graphics window in pixels.

If DEVICE os2pm is specified without the -gWxH argument the graphics window will be created the same size as the last previously displayed window. If this is the first time the graphics window is created it will default to 600 x 400 pixels.

For example,

          DEVICE os2pm -g800x500
               .
               .
               .
          DEVICE os2pm -n

The first DEVICE statement will produce an 800 x 500 pixel graphics window with backing enabled. The second will again produce an 800 x 500 pixel window but with no backing.

Graphics Metafiles

As described elsewhere (see Meta) SM can save graphics commands to a metafile while producing a plot on your screen.

Postscript Devices

Strictly speaking, there are no postscript devices, merely postscript drivers in stdgraph (see Graphcap). On the other hand, SM is able to drive postscript printers in a totally transparent way, so a user can think of SM's postscript capability as discrete drivers. In the following descriptions the arguments to the device command are referred to as $1, $2, and so on. Aliases are listed in parentheses after the device name, so post_colour can also be called post_color. Those currently supported are:

postscript (POSTSCRIPT)
     The basic driver; produces 8x8inch output on the default printer.

postport (POSTPORT)
     A full-page portrait-mode plot.

postland (POSTLAND)
     A full-page landscape-mode plot.

post_colour (post_color)
     Like postscript, but generates a colour postscript plot, and sends it to a printer called ps_colour0.

blackpostscript
     Like post_colour, but uses a black background.

postfile (postencap)
     Like postscript, but generate an encapsulated postscript file in $1.

postlandfile
     Like postland, but generate an encapsulated postscript file in $1.

post_remote (postscript_remote)
     Like postscript, but prints to a printer $2 on host $1.

postland_remote
     Like postscript, but prints to a printer $2 on host $1.

postport_remote
     Like postport, but prints to a printer $2 on host $1.

For an example of defining your own postscript device that takes a printer name as an argument, see Graphcap.

The Silicon Graphics (and RS-6000) Device

The Silicon Graphics device driver works. If you read this and want more documentation, send mail to us and we'll get to it.

The General Device Driver, using Graphcap

By far the majority of devices that SM supports are driven through the stdgraph device; a partial list includes tek4010, tek4012, pericom, selanar, (or hirez ), versaterm (or macvt ), vt640 (a vt100 with retrographics ), vt240 in REGIS mode, hard4012 or hard4010 for a tek4010 that really has no decent ascii mode, tek4025, wyse1575, cit414a or 414a. We also support graphcap drivers for Postscript, QMS, and LN03 laser printers, (device names postscript, qms and ln03). Stdgraph can also cooperate with raster devices, for instance to plot on a lineprinter.

For the stdgraph (i.e. default) device driver the final word on the command line (if present) is taken to be the name of a file to receive the output that would ordinarily go to the screen, so if you say

     device graphon outfile

and then create a plot nothing will seem to happen. However, if you close the device and write outfile to the terminal (maybe using /passall if you are running VMS) your plot will appear. In addition, any word beginning with a colon will be taken to be part of a graphcap entry (see Graphcap), and prepended to the entry in the graphcap file for your chosen device. For example, if you wanted to save your postscript output in a file you could say

     dev postscript ":SY=echo File is $F:"

which would replace the SY entry that sent the output to the printer by a new one that merely tells you what the file is called. If you'd prefer to give it a memorable name, you could say

     dev postscript ":SY=echo File is \$F:OF=name:"

or

     dev postscript :SY@: :OF@: name

(it doesn't matter if the entries are all in the same word). The former redefines the output file OF to be ``name'', and makes SY tell you so. The latter disables both OF and SY, so the generated postscript would ordinarily go to the terminal (just like any other graphics terminal), but a file name is specified, so the output is sent there instead.

If you find yourself frequently wanting to use a customised stdgraph device, this mechanism can become rather tedious; you'd rather simply invent the device and be done with it. The proper way to do this is to create a local graphcap file (see Graphcap File), and add your new device to it. For example, if you wanted to define a postscript device that took the name of the printer as its argument, you'd put an entry

     mypostscript|like postscript, but specify the printer as its argument:\
             :SY=lpr -r -P$1 $F:TC=postscript:

in your file, and merrily proceed with making beautiful plots using DEVICE mypostscript fred. If you always want to use your new device you could call it postscript and in effect redefine the old postscript device (note carefully that I said :TC=postscript: not :tc=postscript:; if I hadn't, an infinite loop would have resulted).

The SunView (and Sunwindows) Devices

As the sunwindows driver is now obsolete, and may well disappear in some future release, you should use the sunview driver instead. If you insist on using the old driver, it must be run from within a gfxtool.

The SunView window driver supports a subset of the usual SunView command line arguments, specifically:

-WH
     Summarise options

-Wi
     Open window as an icon

-Wl label
     Specify label for the window (default: SM)

-Wn
     Don't label window

-WP x y
     Position of icon

-Wp x y
     Position of window -Ws w h Size of window

The standard SunView popup `frame' menu has been modified to allow you to erase the graphics screen. It is perfectly safe to use the menu to quit the graphics window, in this case the next device sunview command will create a new one. If SM thinks that the window is active when you try to kill it, it will warn you; failing to believe it may result in a cascade of complaints to the console window. There is a bug in the cursor routine (I claim that it is a SunView bug) that means that SM sees only every other key-stroke.

The Unix-PC Device

On a Unix-PC DEVICE upc opens a window of 304 by 192 pixels, which is about 4 by 4 inches. To quote the author (Peter Teuben, teuben@astro.umd.edu),

 1. This whole Unixpc version is an experimental version, take it as is, it works on my configuration, but may not work on yours.

 2. I'm playing with allowing a second and third parameter to the upc device name, which would allow you to change the default size of 304 by 192 pixels (The size in X must be a multiple of 16 though). Right now I have it check environment variables YAPP_X and YAPP_Y, but this may not work satisfactorily.

 3. I spawn windows using the public domain program `wlogin', this may be of some importance if your `upc' device in SM fails.

I don't have a Unix PC, so I can't work on this driver.

PC Graphics under MS-Windows

This section needs more work; send mail to rhl@astro.princeton.edu.

VAX/VMS UIS$ device

the VAXUIS driver is used to display graphics on a VAX Workstation using the VAX UIS$ library routines. The optional X and Y parameters specify the size of the graphics window ( in centimeters ) created on the workstation screen.

If called without the optional X and Y parameters the graphics display window will be the same size as that previously displayed.

If the X and Y parameters are not specified the first time the DEVICE vaxuis command is issued, the graphics display window will occupy 1/2 the height and 1/2 the width of the workstation screen.

For example, to create a 15 cm wide x 10 cm tall display window say:

     		DEVICE vaxuis 15 10

The X-Windows Devices (X10 and X11)

There are two X-Windows drivers, one for X10 and one for X11 and they differ in their treatment of command line arguments. The X11 driver is considerably more sophisticated and will be treated first.

The X11 window driver (device x11) supports a subset of the standard command line arguments, specifically (the X-resources names appear in parentheses at the ends of the descriptions):

#geom
     Specify icon geometry (.icongeometry)

-bd n
     Border width (.borderwidth)

-bg colour
     Background colour (.background)

-device n (.device)
     Use X11-device n

-cmap
     Use a private colour map for this device (.colormap)

-colormap
     Use a private colour map for this device (same as -cmap). (.colormap)

-colourmap
     Use a private colour map for this device (same as -cmap). (.colormap)

-cmap
     Use a private colour map for this device (.colormap)

-display name
     Name of display to open (.display)

-fg colour
     Foreground colour (.foreground)

-fn fontname
     Name of hardware font to use (.font)

-geometry geom
     Specify window geometry (.geometry)

-help
     Summarise options

-kbdfocus
     Preserve keyboard focus (the same as -focus). Without this, some window managers transfer focus to the graphics window when it is created; probably not what you want (.kbdfocus)

-iconic
     Open window as an icon (.iconic)

-name name

-ndevice n (.ndevice)
     Allow up to n X11 devices

-nocurswind
     Do not show the cursor position while in cursor mode (same as -nocw) Specify name of window (.name)

-preopened display_id:window_id
     Specify device and window id's

-synchronise
     Synchronise with server (debugging only) (.synchronise)

-title title
     Specify title of window (.title)

Where geom is a standard geometry string of the form WxH+-X+-Y, and the preopened option is for a programme calling SM non-interactively. All options may be abbreviated, so

     device x11 -i #-1+1 -g 512x512+100+100

specifies that the graphics window be created as an icon in the top right hand corner of the screen, and that the real window should be 512*512 and positioned near the top left corner.

SM is able to open more than one x11 device (by default it can handle 5); see the -device and -ndevice options. You can say device x11 -dev + to switch to the next open X11 device; device x11 -dev - switches to the previous one.

If you want to raise your graphics window so that you can see it, you can either use the window manager, reopen the device (dev x11), erase the screen, or use the PAGE command.

On hardware that doesn't support a backing store (or if you have chosen to disable a backing store when compiling the X11 driver) the screen will only be refreshed when it is active or when SM is waiting for input. If your operating system doesn't support the select() system call you may be even worse off, but reopening the device (device x11) should still result in the screen being redrawn.

If you use CTYPE = expr to ask for more than a small number of special colours (see Ctype), you will probably need to specify -cmap to get your own colour map; if you don't SM may well complain about being unable to allocate colours.

The X10 driver is known as xwindow, and you can optionally specify a device to open, and a window ID, on the command line. For example

     device xwindows DEVICE unix:0

will open a graphics window on device unix:0. (You can optionally include a ID number after the DEVICE if you are calling SM from a programme, and have already opened the window). The X10 driver doesn't bother to remember any hardware characters that you may have written on a graph, so that if you refresh the window they won't appear. If this worries you can, as always, force the software character set with an expand 1.001.