To write a new device handler, it is simplest to start by modifying an existing one. This Appendix explains what the device handler must do, but it does not explain how to do it---which is, of course, very hardware-dependent.
GREXEC
. Routine
GREXEC
is called whenever PGPLOT needs to determine
device-specific information or perform graphical I/O. This routine in
turn calls on the appropriate device handler. Reconfiguring PGPLOT
involves modifying the GREXEC
routine to use a different
set of device handlers; no other changes to PGPLOT are needed.
Usually the Fortran code for GREXEC
is created
automatically from a list of selected device handlers during the
installation of PGPLOT.
C*GREXEC -- PGPLOT device handler dispatch routine C+ SUBROUTINE GREXEC(IDEV,IFUNC,RBUF,NBUF,CHR,LCHR) INTEGER IDEV, IFUNC, NBUF, LCHR REAL RBUF(*) CHARACTER*(*) CHR C--- INTEGER NDEV PARAMETER (NDEV=6) CHARACTER*10 MSG C--- GOTO(1,2,3,4,5,6) IDEV IF (IDEV.EQ.0) THEN RBUF(1) = NDEV NBUF = 1 ELSE WRITE (MSG,'(I10)') IDEV CALL GRWARN('Unknown device code in GREXEC: '//MSG) END IF RETURN C--- 1 CALL NUDRIV(IFUNC,RBUF,NBUF,CHR,LCHR) RETURN 2 CALL PSDRIV(IFUNC,RBUF,NBUF,CHR,LCHR,1) RETURN 3 CALL PSDRIV(IFUNC,RBUF,NBUF,CHR,LCHR,2) RETURN 4 CALL TTDRIV(IFUNC,RBUF,NBUF,CHR,LCHR,1) RETURN 5 CALL XWDRIV(IFUNC,RBUF,NBUF,CHR,LCHR,1) RETURN 6 CALL XWDRIV(IFUNC,RBUF,NBUF,CHR,LCHR,2) RETURN C END |
Table E.1 gives an example. The first argument (IDEV
) is
an integer specifying the type of the currently selected
device. Routine GREXEC
calls the appropriate device
handler for this type, passing the remaining arguments to the device
handler. If IDEV
is zero, GREXEC
returns the
number of device types available. Some device handlers handle more
than one PGPLOT device type: e.g., in the above example
PSDRIV
handles both types PS and VPS. The last argument
passed to the device handler is an integer specifying which of the
supported types is required. This argument is omitted for handlers
that support only one type (NUDRIV
in the above example).
To reconfigure PGPLOT, GREXEC
must be modified as
follows: (a) set parameter NDEV
to the number of device
types; (b) make sure that the computed-goto statement has
NDEV
branches; (c) supply a target for each branch to
call the appropriate device handler.
SUBROUTINE xxDRIV (OPCODE, RBUF, NBUF, CHR, LCHR, MODE) INTEGER OPCODE REAL RBUF(*) INTEGER NBUF CHARACTER*(*) CHR INTEGER LCHR INTEGER MODEThe first argument (
OPCODE
) is an integer ``operation
code'' which specifies what operation the device handler is to
perform; it is an input parameter to the subroutine (see Table
E.2). The MODE
argument is another input parameter that
distinguishes between multiple device types supported by the same
handler. The other arguments are used for both input and output, and
their meaning depends on the value of the operation code. Not all
arguments are used for every operation code. RBUF
is a
floating-point array used to pass numerical data to or from the device
handler, and NBUF
indicates how many elements of the
array are used. CHR
is a character variable used to pass
character data to or from the device handler, and LCHR
indicates how many characters are used. NBUF
or
LCHR
should be set to zero if no data of the
corresponding type are passed. If the function requested by the
operation code (OPCODE
) is not implemented in the device
handler, the subroutine should set NBUF = -1
before returning.
The device handler subroutine can communicate with PGPLOT only
through the arguments. It should not attempt to reference the PGPLOT
common blocks (this is because the internal structure of the PGPLOT
common blocks may change). Data stored internally by the handler
between calls should be placed in static storage (use the Fortran
SAVE
statement).
Opcode | Function |
---|---|
1 | Return device type |
2 | Return maximum dimensions of view surface, and range of color index |
3 | Return device scale |
4 | Return device capabilities |
5 | Return default device/file name |
6 | Return default size of view surface |
7 | Return miscellaneous defaults |
8 | Select device |
9 | Open workstation |
10 | Close workstation |
11 | Begin picture |
12 | Draw line |
13 | Draw dot |
14 | End picture |
15 | Set color index |
16 | Flush buffer |
17 | Read cursor |
18 | Erase alpha screen |
19 | Set line style |
20 | Polygon fill |
21 | Set color representation |
22 | Set line width |
23 | Escape function |
24 | Rectangle fill |
25 | Set fill pattern |
26 | Line of pixels |
27 | Scaling information |
28 | Draw marker |
29 | Query color representation |
30 | Scroll rectangle |
(query commands) open workstation (query commands, set color rep) begin picture (graphical output commands) end picture (query commands, set color rep) begin picture (graphical output commands) end picture close workstationAny violation of this sequence is due to a bug in PGPLOT. Device handlers should attempt to trap all errors, including I/O errors (e.g., insufficient disk space or insufficient memory), and issue a warning message rather than terminating execution of the program.
'PS'
for a PostScript device handler. This name
must be different for each mode of each device handler installed in
PGPLOT, and should preferably be unique in the first two or three
characters. A descriptive character string (displayed by routine
PGLDEV
) should be included in parentheses after the name,
e.g., 'PS (PostScript file, landscape orientation)'
.
PGCLOS
), `N' otherwise. Use `V' for
devices where the PGPLOT window is deleted from the screen when the
device is closed.
GRWARN
) and ignore subsequent output commands, rather than
terminating execution of the program.
The handler should make the cursor visible at position (x,y), allow the user to move the cursor, and wait for a key stroke. It should then return the new cursor (x,y) position and the character (key stroke) typed. (If it is not possible to make the cursor visible at a particular position, the handler may ignore the requested (x,y) coordinates.) On a device with a mouse or similar device, clicking mouse-button 1 should return character `A', mouse-button 2 should return `D', and mouse-button 3 should return `X'.
If the hardware permits, the handler should interpret the ``mode'' as
specified in the description of routine PGBAND
. The exact
appearance of the dynamic ``rubber band'' lines may be hardware
specific; if possible, they should be drawn with the current color
index, but they must not erase previously drawn graphics. Handlers
that cannot draw the ``rubber band'' lines should treat all modes as
mode = 0.
NBUF - 2
.
PGQCR
will return R=G=B=0.0 for color
index 0 and R=G=B=1.0 for all other color indices.