# Chapter 6: Parameter Setting Routines

All parameters in DISLIN have default values set by the initialization routine DISINI. This chapter summarizes subroutines that allow the user to alter default values. The following routines can be called from level 1, 2 or 3 except for those noted throughout the chapter. Subroutines that can only be called from level 0 must appear before DISINI. In general, parameter setting routines should be called between DISINI and the plotting routines they affect.

## 6.1.1 Resetting Parameters

R E S E T

RESET sets parameters back to their default values.

 The call is: CALL RESET (CNAME) level 1, 2, 3 or: void reset (const char *cname);

 CNAME is a character string containing the name of the routine whose parameters will be set back to default values. If CNAME = 'ALL', all parameters in DISLIN will be reset.

DELGLB frees space that is allocated by DISLIN for global parameters. You can call this routine after DISFIN or WGFIN if you don't want to use any other DISLIN routine after the call.

 The call is: CALL DELGLB level 0 or: void delglb (void);

## 6.1.2 Changing the Plot Units

U N I T S

The routine UNITS defines the plot units.

 The call is: CALL UNITS (COPT) level 0 or: void units (const char *copt);

 COPT is a character string that can have the values 'CM', 'INCH', 'POINTS' and 'TWIPS'. 'CM' means 100 points per centimetre, 'INCH' means 100 points per inch, 'POINTS' means 720 points per inch and 'TWIPS' means 1440 points per inch. Default: COPT = 'CM'.

## 6.1.3 Modifying the Origin

P A G O R G

The routine PAGORG sets the origin of the page. By default, the page origin is located in the upper left corner of the page.

 The call is: CALL PAGORG (COPT) level 1, 2, 3 or: void pagorg (const char *copt);

 COPT is a character string that can have the values 'TOP' and 'BOTTOM'. The keyword 'TOP' sets the page origin to the upper left corner, 'BOTTOM' to the lower left corner. Default: COPT = 'TOP'.

In DISLIN, all lines are plotted relative to the origin which is a point located in the upper left corner of the page. Modifying this point by ORIGIN produces a shifting of plot vectors on the page.

 The call is: CALL ORIGIN (NX0, NY0) level 1 or: void origin (int nx0, int ny0);

 NX0, NY0 are the coordinates of the origin. Default: (0, 0).

## 6.1.4 File Format Control

M E T A F L

METAFL defines the metafile format.

 The call is: CALL METAFL (CFMT) level 0 or: void metafl (const char *cfmt);

 CFMT is a character string that defines the file format. = 'GKSL' defines a GKSLIN metafile. = 'CGM' defines a CGM metafile. = 'PS' defines a coloured PostScript file. = 'EPS' defines an Encapsulated PostScript file. The format is nearly the same as for 'PS'. = 'PDF' defines a PDF file. = 'HPGL' defines an HPGL file. = 'SVG' defines a Scalable Vector Graphics file. = 'IPE' defines a XML metafile, which can be interpreted by the drawing editor Ipe. = 'WMF' defines a Windows metafile. = 'GIF' defines a GIF file. = 'TIFF' defines a TIFF file. = 'PNG' defines a PNG file. = 'PPM' defines a portable pixmap format. = 'IMAG' defines an image file. = 'BMP' defines a Windows Bitmap format. = 'VIRT' defines a virtual file. The metafile is hold in a raster format in computer memory. = 'CONS' defines a graphics output on the screen. If the screen is a windows display, a graphical window is used that has nearly the size of the screen. = 'XWIN' defines a window for graphical output. By default, the size of the window is nearly 2/3 of the size of the screen. = 'GL' defines an OpenGL window. By default, the size of the window is nearly 2/3 of the size of the screen. Default: CFMT = 'GKSL'.

• The default size of SVG, TIFF, GIF, PNG, PPM, BMP, IMAGE and virtual files is set to 853 x 603 points but can be modified with the routine WINSIZ. The size of graphical windows can also be defined with WINSIZ.
• The default background colour for graphical windows and image formats such as TIFF, GIF and PNG is black but can be modified with the routine SCRMOD.
• The format of VIRT, TIFF, PNG, BMP and IMAGE is by default a 8 bit palette format, but can be changed to a true colour format with the parameter 'RGB' in the routine IMGFMT. GIF files created by DISLIN have always a 8 bit palette format.
S E T F I L

By default, the plot file name consists of the keyword 'dislin' and an extension that depends on the file format. An alternate filename can be set with SETFIL.

 The call is: CALL SETFIL (CFIL) level 0 or: void setfil (const char *cfil);

 CFIL is a character string that contains the filename.

The routine FILMOD determines if a new plot file name is created for existing files.

 The call is: CALL FILMOD (CMOD) level 0, 1, 2, 3 or: void filmod (const char *cmod);

 CMOD is a character string containing the mode. = 'COUNT' means that a new file version will be created. An increasing version number is added to the filename and the filename is shortened to eight characters. = 'VERSION' is a similar option to 'COUNT' that creates a new file version, but without shorten the filename. = 'DELETE' means that the existing file will be overwritten. = 'BREAK' means that the program will be terminated by DISINI. Default: CMOD = 'COUNT'.

The routine FILOPT modifies rules for creating file version names, or or sets options for including files with INCFIL.

 The call is: CALL FILOPT (COPT, CKEY) level 0, 1, 2, 3 or: void filopt (const char *copt, const char *ckey);

 COPT is a character string containing an option. CKEY is a character string that can have the values 'SEPARATOR', 'NUMBER', 'DIGITS' and 'SCALE'. The keyword 'SEPARATOR' defines the separator between filenames and version numbers. If CKEY = 'SEPARATOR', COPT can have the values 'UNDERSCORE', 'HYPHEN' and 'NONE'. If CKEY = 'NUMBER', COPT can have the values 'SHORT' and 'LONG'. The option 'LONG' means that leading zeros are used in the version number. The keyword 'DIGITS' sets the number of digits that are used for version numbers. For that keyword, COPT can have the values '2', '3', '4', '5' and '6'. The keywort 'SCALE' enables or disables scaling of images files imported by INCFIL. COPT can have the values 'ON' and 'OFF'. Defaults: ('_', 'SEPARATOR'), ('SHORT', 'NUMBER'), (4, 'DIGITS'), ('OFF', 'SCALE').

Normally, the background of screens and image formats such as TIFF, GIF, BMP and PNG is set tp 'BLACK'. With the routine SCRMOD, the back and foreground colours can be swapped.

 The call is: CALL SCRMOD (CMOD) level 0 or: void scrmod (const char *cmod);

 CMOD is a character string containing the mode. = 'AUTO' uses a 'BLACK' background colour for screen output and image files. = 'REVERS' means that the background colour is set to 'WHITE' and the foreground colour to 'BLACK'. = 'NOREV' means that the background colour is set to 'BLACK' and the foreground colour to 'WHITE'. Default: CMOD = 'AUTO'.

The routine CGMBGD sets the background colour for CGM files.

 The call is: CALL CGMBGD (XR, XG, XB) level 0, 1, 2, 3 or: void cgmbgd (float xr, float xg, float xb);

 XR, XG, XB are the RGB coordinates of the background colour in the range 0 to 1. Default: (1., 1., 1.).

The routine CGMPIC modifies the picture ID in CGM files. The picture ID may be referenced by some browsers.

 The call is: CALL CGMPIC (CSTR) level 0, 1, 2, 3 or: void cgmpic (const char *cstr);

 CSTR is a character string containing the picture ID (<= 256 characters). By default, the ID 'Picture n' is used where n is the picture number beginning with 1.

The routine WMFMOD modifies the appearance of WMF files.

 The call is: CALL WMFMOD (CMOD, CKEY) level 0 or: void wmfmod (const char *cmod, const char *ckey);

 CMOD is a character string containing the values 'STANDARD' or 'PLACEABLE'. If CMOD = 'PLACEABLE', an additional leading header of 22 byte is added to the WMF file. The format is also known as Aldus Placeable Metafile. CKEY is a character string that can have the value 'FORMAT'. Default: CMOD = 'STANDARD'.

The routine TIFMOD modifies the physical resolution of TIFF files.

 The call is: CALL TIFMOD (N, CVAL, COPT) level 0 or: void tifmod (int n, const char *cval, const char *copt);

 N is an integer value containing the number of pixels per resolution unit. CVAL is a character string containing the resolution unit. CVAL can have the values 'INCH' and 'CM'. COPT is a character string that can have the value 'RESOLUTION'. Default: (100, 'INCH', 'RESOLUTION').

The routine BMPMOD modifies the physical resolution of BMP files.

 The call is: CALL BMPMOD (N, CVAL, COPT) level 0 or: void bmpmod (int n, const char *cval, const char *copt);

 N is an integer value containing the number of pixels per resolution unit. CVAL is a character string containing the resolution unit. CVAL can have the values 'INCH' and 'METER'. COPT is a character string that can have the value 'RESOLUTION'. Default: (2500, 'METER', 'RESOLUTION').

The routine PDFMOD selects between compressed and non compressed PDF files, and can enable PDF buffer output instead of file output.

 The call is: CALL PDFMOD (CMOD, CKEY) level 0 or: void pdfmod (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'ON' and 'OFF'. CKEY is a character string that can have the values 'COMPRESSION and 'BUFFER'. For CKEY = 'BUFFER' and CMOD = 'ON', the PDF file is hold in memory and can be copied to a user buffer with the routine PDFBUF after DISFIN. Default: ('ON', COMPRESSION'), ('OFF', 'BUFFER').

The routine PDFMRK writes bookmarks to PDF files. This makes it possible to navigate through PDF files that contain multiple pages.

 The call is: CALL PDFMRK (CSTR, COPT) level 1, 2, 3 or: void pdfmrk (const char *cstr, const char *copt);

 CSTR is a character string that contains the text of the bookmark. COPT is a character string that can have the values 'CHAPTER', 'SECTION', 'SUBSECTION', 'PARAGRAPH' and 'SUBPARAGRAPH'. This option defines the level of a bookmark in the hierarchy of bookmarks. A bookmark with the option 'SECTION' can only be defined if a bookmark with the option 'CHAPTER' is defined before, and so on.

The routine GIFMOD enables transparency for GIF files.

 The call is: CALL GIFMOD (CMOD, CKEY) level 0 or: void gifmod (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'ON' and 'OFF'. CKEY is a character string that can have the value 'TRANSPARENCY'. Default: ('OFF', 'TRANSPARENCY').

The routine PNGMOD enables transparency for PNG files.

 The call is: CALL PNGMOD (CMOD, CKEY) level 0 or: void pngmod (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'ON' and 'OFF'. CKEY is a character string that can have the value 'TRANSPARENCY'. Default: ('OFF', 'TRANSPARENCY').

• For indexed PNG files, the colour table entry 0 is used for transparency. For RGB files, the colour White is used for transparency.

The routine HPGMOD defines options for HPGL files.
 The call is: CALL HPGMOD (CMOD, CKEY) level 0 or: void hpgmod (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'STAN' and 'ARISTO'. For COPT = 'ARISTO', the DISLIN HPGL file will begin with the commands 'IN;SP1;LT;PU'. CKEY is a character string that can have the value 'PLOTTER'. Default: ('STAN', 'PLOTTER').

The routine IMGFMT defines palette or true colour mode for DISLIN image formats such as TIFF, PNG, BMP and IMAGE.

 The call is: CALL IMGFMT (CMOD) level 0 or: void imgfmt (const char *cmod);

 CMOD is a character string that can have the values 'INDEX' and 'RGB'. For TIFF files, the additional keyword 'BILEVEL' is allowed for creating bilevel TIFF files. Default: CMOD = 'INDEX'.

## 6.1.5 Page Control

P A G E

PAGE determines the size of the page.

 The call is: CALL PAGE (NXP, NYP) level 0 or: void page (int nxp, int nyp);

 NXP, NYP are the length and height of the page in plot coordinates. The lower right corner of the page is the point (NXP-1, NYP-1). Default: (2970, 2100).

SETPAG selects a predefined page format.

 The call is: CALL SETPAG (CPAGE) level 0 or: void setpag (const char *cpage);

 CPAGE is a character string that defines the page format.

  = 'DA4L'     DIN A4,          landscape,  2970 *  2100 points.
= 'DA4P'     DIN A4,          portrait,   2100 *  2970 points.
= 'DA3L'     DIN A3,          landscape,  4200 *  2970 points.
= 'DA3P'     DIN A3,          portrait,   2970 *  4200 points.
= 'DA2L'     DIN A2,          landscape,  5940 *  4200 points.
= 'DA2P'     DIN A2,          portrait,   4200 *  5940 points.
= 'DA1L'     DIN A1,          landscape,  8410 *  5940 points.
= 'DA1P'     DIN A1,          portrait,   5940 *  8410 points.
= 'DA0L'     DIN A0,          landscape, 11890 *  8410 points.
= 'DA0P'     DIN A0,          portrait,   8410 * 11890 points.
= 'USAL'     US paper size A, landscape,  2790 *  2160 points.
= 'USAP'     US paper size A, portrait,   2160 *  2790 points.
= 'USBL'     US paper size B, landscape,  4320 *  2790 points.
= 'USBP'     US paper size B, portrait,   2790 *  4320 points.
= 'USCL'     US paper size C, landscape,  5590 *  4320 points.
= 'USCP'     US paper size C, portrait,   4320 *  5590 points.
= 'USDL'     US paper size D, landscape,  8640 *  5590 points.
= 'USDP'     US paper size D, portrait,   5590 *  8640 points.
= 'USEL'     US paper size E, landscape, 11180 *  8640 points.
= 'USEP'     US paper size E, portrait,   8640 * 11180 points.
= 'PS4L'     PostScript A4,   landscape,  2800 *  1950 points.
= 'PS4P'     PostScript A4,   portrait,   1950 *  2800 points.
= 'HP4L'     HP-plotter A4,   landscape,  2718 *  1900 points.
= 'HP4P'     HP-plotter A4,   portrait,   1900 *  2718 points.
= 'HP3L'     HP-plotter A3,   landscape,  3992 *  2718 points.
= 'HP3P'     HP-plotter A3,   portrait,   2718 *  3992 points.
= 'HP2L'     HP-plotter A2,   landscape,  5340 *  3360 points.
= 'HP2P'     HP-plotter A2,   portrait,   3360 *  5340 points.
= 'HP1L'     HP-plotter A1,   landscape,  7570 *  5340 points.
= 'HP1P'     HP-plotter A1,   portrait,   5340 *  7570 points.
Default: CPAGE = 'DA4L'.

S C L F A C

SCLFAC sets the scaling factor for an entire plot.

 The call is: CALL SCLFAC (XFAC) level 0 or: void sclfac (float xfac);

 XFAC is the scaling factor by which the entire plot is scaled up or down. Default: XFAC = 1.

The method by which graphics are scaled to the hardware pages of devices such as a graphics terminal can be selected with the routine SCLMOD.

 The call is: CALL SCLMOD (CMOD) level 0 or: void sclmod (const char *cmod);

 CMOD = 'DOWN' means that graphics will be scaled down if the hardware page of a device is smaller than the plotting page. CMOD = 'FULL' means that the graphics will be scaled up or down depending upon the size of the hardware page. Default: CMOD = 'DOWN'.

• The size of a graphics screen will be interpreted as DIN A4 landscape. This means that by default graphics which are smaller than DIN A4 will not fill the entire screen.
• SCLFAC and SCLMOD can affect each other.
P A G M O D

GKSLIN and CGM files can be rotated by 90 degrees to use the full hardware page of a device. In general, this is done automatically by the driver program.

 The call is: CALL PAGMOD (CMOD) level 0 or: void pagmod (const char *cmod);

 CMOD = 'LAND' means that the metafile is not rotated. CMOD = 'PORT' means that the metafile is rotated by 90 degrees. CMOD = 'NONE' can be used to disable automatic plot file rotation in the driver program (i.e. for PostScript files). Default: CMOD = 'LAND'.

Figure 6.1 shows the effect of PAGMOD:

                                          +--------------+
|              |
|          ^   |
|          |   |
|          |   |
+-----------------------+             |          |   |
|  ^                    |             | Portrait |X  |
|  |                    |             |          |   |
| Y|    Landscape       |             |          |   |
|  |                    |             |          |   |
|  +--------------->    |             |  <-------+   |
|         X             |             |     Y        |
+-----------------------+             +---------------

Figure 6.1: PAGMOD

N E W P A G

NEWPAG creates a new page.

 The call is: CALL NEWPAG level 1 or: void newpag (void);

• PostScript, PDF and CGM files can store multiple pages. For other output formats, NEWPAG is not useful.
• On X Window terminals, NEWPAG is waiting for a mouse button 2 event before displaying the next page. This mode can be changed with the routine WINMOD. On other terminals, NEWPAG has the same effect as ERASE.
H W P A G E

The routine HWPAGE defines the size of the PostScript or PDF hardware page.

 The call is: CALL HWPAGE (NW, NH) level 0 or: void hwpage (int nw, int nh);

 NW, NH are the width and height of the PostScript or PDF hardware page in plot coordinates. Default: (1950, 2800).

The routine HWORIG defines the hardware origin of the PostScript or PDF hardware page.

 The call is: CALL HWORIG (NX, NY) level 0 or: void hworig (int nx, int ny);

 NX, NY are the plot coordinates of the hardware origin. Default: (75, 100).

The routine HWSCAL modifies the scale operator in PostScript and PDF files.

 The call is: CALL HWSCAL (XSCL) level 0 or: void hwscal (float xscl);

 XSCL is a floating point value used for the scale operator. Default: 1.

## 6.1.6 Error Handling

E R R M O D

The printing of warnings and the output of the protocol in DISFIN can be disabled with the routine ERRMOD.

 The call is: CALL ERRMOD (CKEY, CMOD) level 1, 2, 3 or: void errmod (const char *ckey, const char *cmod);

 CKEY is a character string that can have the values 'WARNINGS', 'CHECK', 'PROTOCOL' and 'ALL'. 'WARNINGS' means the error messages about bad parameters passed to DISLIN routines, 'CHECK' the out of range check of coordinates passed to plotting routines such as CURVE and 'PROTOCOL' the output of the protocol in DISFIN. CMOD is a character string that can have the values 'ON' and 'OFF'. For CKEY = 'PROTOCOL', CMOD can have the additional value 'FILE' that means that the protocol in DISFIN is also written to the error file. Default: ('ALL', 'ON')

By default, the name of the error file is 'dislin.err'. An alternate filename can be set with ERRFIL.

 The call is: CALL ERRFIL (CFIL) level 0 or: void errfil (const char *cfil);

 CFIL is a character string that contains the filename.

The routine ERRDEV defines the output device for DISLIN warnings. By default, warnings are written to the screen.

 The call is: CALL ERRDEV (COPT) level 0 or: void errdev (const char *copt);

 COPT is a character string that can have the values 'CONS', 'FILE' and 'APPEND'. 'APPEND' means that all error messages are appended to the same file while for the keyword 'FILE' a new error file is created for each DISINI/DISFIN cycle.

UNIT defines the logical unit used for printing error messages and listing data points that lie outside of the axis scaling.

 The call is: CALL UNIT (NU) level 1, 2, 3 or: void unit (FILE *nu);

 NU is the logical unit. If NU = 0, all messages will be suppressed. Default: NU = 6

• UNIT is an old DISLIN routine for suppressing error messages. It should be replaced by the newer routines ERRMOD, ERRDEV and ERRFIL.

The routine WINAPP defines if a DISLIN program should look like a Windows console, or more like a Windows program. If Windows mode is selected, all warnings are written to an error file and the protocol in disfin is displayed in a widget.

 The call is: CALL WINAPP (COPT) level 0 or: void winapp (const char *copt);

 COPT is a character string that can have the values 'CONSOLE' and 'WINDOWS'.

## 6.1.7 Viewport Control

W I N D O W

This routine defines, for X Window terminals, a region on the screen where the graphics will be displayed. By default, the window size is set to 2/3 of the screen size and located in the lower right corner of the screen.

 The call is: CALL WINDOW (NX, NY, NW, NH) level 0, 1, 2, 3 or: void window (int nx, int ny, int nw, int nh);

 NX, NY are the screen coordinates of the upper left corner. NW, NH are the width and height of the client area of the graphics window in screen coordinates. The client area defines the size of the plot.

• In general, the screen size is 1280 * 1024 pixels.

WINJUS is an alternative routine to WINDOW for setting the position of the graphics window.

 The call is: CALL WINJUS (CJUS) level 0, 1, 2, 3 or: void winjus (const char *cjus);

 CJUS is a character string that can have the values = 'CENTER' means the center of the screen. = 'RBOTTOM' means the lower right corner. = 'RTOP' means the upper right corner. = 'LTOP' means the upper left corner. = 'LBOTTOM' means the lower left corner. Default: CJUS = 'RBOTTOM'.

This routine defines the size of windows and the resolution of DISLIN image formats such as TIFF, PNG, BMP, PPM and IMAGE. By default, the window size is set to 2/3 of the screen size, and the resolution of image formats is 853 x 603 pixels.

 The call is: CALL WINSIZ (NW, NH) level 0, 1, 2, 3 or: void winsiz (int nw, int nh);

 NW, NH are the width and height of the window in pixels.

The routine WINKEY enables a an additional key that can be used for program continuation is DISFIN. Normally, the mouse button 2 can be used for closing the graphics window.

 The call is: CALL WINKEY (CKEY) level 1, 2, 3 or: void winkey (const char *ckey);

 CKEY is a character string that can have the values 'NONE', 'RETURN' and 'ESCAPE'. Default: CKEY = 'NONE'.

The routine CLRMOD defines the colour mode used for output on an X Window terminal.

 The call is: CALL CLRMOD (CMOD) level 0 or: void clrmod (const char *cmod);

 CMOD is a character string defining the mode. = 'NONE' means that a colour table with 256 colours will be reduced to 129 colours to conserve current screen and window colours. The colour values will be reduced by the formula (0 <=> 0, i = (iclr + 1) / 2, iclr = 1, ... 255). = 'FULL' means that all 256 colours will be displayed. = 'CONT' means that a colour table with less than 129 entries will be used. Default: CMOD = 'NONE'.

The routine X11MOD defines backing store for X graphic windows.

 The call is: CALL X11MOD (CMOD) level 0 or: void x11mod (const char *cmod);

 CMOD is a character string containing the mode. = 'NOSTORE' means that graphical output is send directly to the graphics window. = 'STORE' means that graphical output is send to a pixmap that will be copied to the graphics window. = 'AUTO' means that 'NOSTORE' will be used on X11 and 'STORE' on Windows terminals. = 'PIXMAP' means that only a pixmap is used. The graphics window will be invisible. Default: CMOD = 'AUTO'.

The routine WINMOD affects the handling of windows in the termination routine DISFIN.

 The call is: CALL WINMOD (CMOD) level 1, 2, 3 or: void winmod (const char *cmod);

 CMOD is a character string containing the mode. = 'FULL' means that DISFIN is waiting for a mouse button 2 event. After program continuation, all windows are deleted. = 'NOHOLD' means that DISFIN is not waiting for a mouse button 2 event. After a call to DISFIN, all windows are deleted. = 'NOERASE' means that the program is still blocked in DISFIN but windows will not be deleted after program continuation. = 'NONE' means that the program is not blocked in DISFIN and windows are not deleted. = 'DELAY' means that the program is blocked for a short time in DISFIN before it is continued. The delay time can be defined with the routine WINOPT. Default: CMOD = 'FULL'.

The routine WINTYP defines the type of the graphics window. A graphics window with frames and a title bar can be used, or a window without any decorations.

 The call is: CALL WINTYP (CTYP) level 0 or: void wintyp (const char *ctyp);

 CTYP is a character string containing the typ. = 'STAND' means a window with frames and a title bar. = 'POPUP' means a window without any decorations. Default: CTYP = 'STAND'.

The routine WINOPT sets the delay time for the keyword 'DELAY' in WINMOD.

 The call is: CALL WINOPT (IOPT, CKEY) level 1, 2, 3 or: void winopt (int iopt, const char *ckey);

 IOPT is the delay time in seconds or milliseconds. CKEY is a character string that can have the values 'DELAY' and 'MDELAY'. For CKEY = 'MDELAY', IOPT must contain milliseconds, otherwise seconds. Default: (10, 'DELAY').

The routine WINICO loads an icon from a file that is displayed in the title bar of the graphics window (only Windows).

 The call is: CALL WINICO (CFIL) level 1, 2, 3 or: void winico (const char *cfil);

 CFIL is a filename containing the icon. The format of the file must be a Windows .ico format. Default: a standard icon is used.

The routine WINCBK defines a user written callback routine which is called in DISFIN if the size of the graphics window is changed.

 The call is: CALL WINCBK (ROUTINE, 'SIZE') level 1, 2, 3 or: void wincbk (routine, "SIZE");

 ROUTINE is the name of a routine defined by the user. In Fortran, the routine must be declared as EXTERNAL. The parameters passed to ROUTINE are (ID, NX, NY, NW, NH), where ID is the ID of the window (see OPNWIN), NX, NY are the coordinates of the upper left corner and NW and NH the width and height of the changed window in pixels.

The routine SETXID defines an external graphics window for X11 and Windows displays. All graphical output is sent to the external window. For X11 displays, an external pixmap can also be defined.

 The call is: CALL SETXID (ID, CTYPE) level 0, 1, 2, 3 or: void setxid (int id, const char *ctype);

 ID is the window or pixmap ID. CTYPE is a character string that can have the values 'NONE', 'WINDOW', 'PIXMAP' and 'WIDGET'. For the keyword 'WIDGET', the ID of a DISLIN draw widget can be used. Default: (0, 'NONE').

• If an external pixmap is used, backing store must also be enabled with the routine X11MOD.
• An external window is not erased by DISINI. This can be done with the routine ERASE.
• External windows are not blocked in DISFIN (see WINMOD).
• External windows can also be used for multiple DISLIN windows that are defined with the routine OPNWIN.

## 6.1.8 Environment

A few routines in DISLIN such as some font and map routines need the path to the DISLIN installation directory for reading font and map files. The DISLIN installation directory can either be defined outside of a program with the environment variable DISLIN, or within a program with the routine DISENV. If none of the methods above is applied, the default directories c:\dislin and /usr/local/dislin are used on Windows and Linux/UNIX systems.

This routine sets the DISLIN environment within a program. If the DISLIN environment is already defined outside of the program, a call to DISENV has no affect.
 The call is: CALL DISENV (CPATH) level 0, 1, 2, 3 or: void disenv (const char *cpath);

 CPATH is a character string that contains the path to the DISLIN installation directory.

## 6.2 Axis Systems

This section describes subroutines that allow the user to modify axis systems. The position of an axis system, the size, the scaling, ticks, labels and axis titles can be altered in any way. Some of the routines defining axis attributes can also be used with secondary axes. Routines that set axis attributes can be used for one or for any combination of axes. The axes are identified by a character string that can contain the characters 'X', 'Y' and 'Z' in any combination.

## 6.2.1 Modifying the Type

A X S T Y P

The routine AXSTYP defines the type of an axis system. Axis systems can be plotted as rectangles or in a crossed form. For crossed axis systems, the scaling must be linear and the axis limits must contain the origin.

 The call is: CALL AXSTYP (COPT) level 1 or: void axstyp (const char *copt);

 COPT is a character string defining the type. = 'RECT' defines a rectangular axis system. = 'CROSS' defines a crossed axis system. Default: COPT = 'RECT'.

## 6.2.2 Modifying the Position and Size

A X S P O S

AXSPOS determines the position of an axis system.

 The call is: CALL AXSPOS (NXA, NYA) level 1 or: void axspos (int nxa, int nya);

 NXA, NYA are plot coordinates that define the lower left corner of an axis system. By default, axis systems are centred in the X-direction while NYA is set to the value (page height - 300).

AXSORG is an alternate routine for defining the position of a crossed axis system.

 The call is: CALL AXSORG (NX, NY) level 1 or: void axsorg (int nx, int ny);

 NX, NY are plot coordinates that define the position of the origin of a crossed axis system.

AXSLEN defines the size of an axis system.

 The call is: CALL AXSLEN (NXL, NYL) level 1 or: void axslen (int nxl, int nyl);

 NXL, NYL are the length and height of an axis system in plot coordinates. The default values are set to 2/3 of the page length and height.

A call to the routine CENTER will centre the axis system on the page. All elements of an axis system, including titles, axis labels and names, will be taken into consideration. The centralization is done by GRAF through changing the position of the origin. Therefore, all plotting routines called after GRAF will work with the new origin.

 The call is: CALL CENTER level 1, 2, 3 or: void center (void);

• If there are several axis systems on the page, the origin will be changed only by the first call to GRAF.
• The character height of titles should be defined with HTITLE if it is different from the current character height in GRAF.

## 6.2.3 Axis Scaling

A X S S C L

This routine sets the axis scaling to logarithmic or linear.

 The call is: CALL AXSSCL(CSCL, CAX) level 1, 2, 3 or: void axsscl (const char *cscl, const char *cax);

 CSCL = 'LIN' denotes linear scaling. CSCL = 'LOG' denotes logarithmic scaling. CAX is a character string that defines the axes. Default: ('LIN', 'XYZ').

• For logarithmic scaling, the corresponding parameters in GRAF must be exponents of base 10.

The parameters in GRAF will be calculated automatically by DISLIN if the routine SETSCL is used. In this case, GRAF must have dummy parameters in which DISLIN returns the calculated values.

 The call is: CALL SETSCL (XRAY, N, CAX) level 1 or: void setscl (const float *xray, int n, const char *cax);

 XRAY is a vector that contains user coordinates. SETSCL calculates the minimum and maximum values of the data and stores them in a common block. N is the number of points in XRAY. CAX is a character string that defines the axes.

• SETSCL can be used with linear and logarithmic scaling and with all label types.
• The calculation of scaling and label values is done by GRAF. The minimum and maximum of the data are always used for the lower and upper limits of an axis while even values are calculated for the labels.
• The number of digits after the decimal point will be set automatically.
• If the scaling of an axis is logarithmic, labels will be plotted with the format 'LOG'.

## 6.2.4 Modifying Ticks

T I C K S

This routine is used to define the number of ticks between axis labels.

 The call is: CALL TICKS (NTIC, CAX) level 1, 2, 3 or: void ticks (int ntic, const char *cax);

 NTIC is the number of ticks (>= 0). CAX is a character string that defines the axes. Default: (2, 'XYZ').

This routine defines the position of ticks.

 The call is: CALL TICPOS (CPOS, CAX) level 1, 2, 3 or: void ticpos (const char *cpos, const char *cax);

 CPOS is a character string defining the position. = 'LABELS' means that ticks will be plotted on the same side as labels. = 'REVERS' means that ticks will be plotted inside of an axis system. = 'CENTER' means that ticks will be centred on the axis line. CAX is a character string that defines the axes. Default: ('LABELS', 'XYZ').

TICLEN sets the lengths of major and minor ticks.

 The call is: CALL TICLEN (NMAJ, NMIN) level 1, 2, 3 or: void ticlen (int nmaj, int nmin);

 NMAJ is the length of major ticks in plot coordinates (> 0). NMIN is the length of minor ticks in plot coordinates (> 0). Default: (24, 16).

The routine TICMOD modifies the plotting of minor tick marks on calendar axes. By default, a major tick is plotted at each date label and no minor ticks are plotted.

 The call is: CALL TICMOD (COPT, CAX) level 1, 2, 3 or: void ticmod (const char *copt, const char *cax);

 COPT is a character string defining the tick marks. = 'NONE' means that no minor ticks will be plotted. = 'DAYS' means that ticks will be plotted for every day. = 'MONTH' means that ticks will be plotted for every month. = 'DMONTH' means that ticks will be plotted for every second month. = 'QUARTER' means that ticks will be plotted on the first of January, April, July and October. = 'HALF' means that ticks will be plotted on the first of January and July. = 'YEAR' means that ticks will be plotted for every year. CAX is a character string that defines the axes. Default: ('NONE', 'XYZ').

The appearance of minor ticks on logarithmic axes differs slightly from linear axes. By default, logarithmic minor ticks are generated automatically if the label step is 1 or -1 and if the number of ticks in TICKS is greater than 1. If the step has another value, minor ticks are plotted as specified in TICKS. This algorithm can be modified with LOGTIC.

 The call is: CALL LOGTIC (CMOD) level 1, 2, 3 or: void logtic (const char *cmod);

 CMOD is a character string defining the appearance of logarithmic ticks. = 'AUTO' defines default ticks. = 'FULL' means that logarithmic minor ticks will be generated for every cycle even if the label step is not 1 but some other integer. Default: CMOD = 'AUTO'.

## 6.2.5 Modifying Labels

L A B E L S

LABELS determines which label types will be plotted on an axis.

 The call is: CALL LABELS (CLAB, CAX) level 1, 2, 3 or: void labels (const char *clab, const char *cax);

 CLAB is a character string that defines the labels. = 'NONE' will suppress all axis labels. = 'FLOAT' will plot labels in floating point format. = 'EXP' will plot floating point labels in exponential format where fractions range between 1 and 10. = 'FEXP' will plot labels in the format fEn where f ranges between 1 and 10. = 'XEXP' has the same meaning as 'EXP', but a times symbol is used as operator instead of an asterisk. = 'LOG' will plot logarithmic labels with base 10 and the corresponding exponents. = 'CLOG' is similar to 'LOG' except that the entire label is centred below the tick mark; with 'LOG', only the base '10' is centred. = 'ELOG' will plot only the logarithmic values of labels. = 'TIME' will plot time labels in the format 'hhmm'. = 'HOURS' will plot time labels in the format 'hh'. = 'SECONDS' will plot time labels in the format 'hhmmss'. = 'DATE' defines date labels. = 'MAP' defines geographical labels which are plotted as non negative floating point numbers with the following characters 'W', 'E', 'N' and 'S'. = 'MAPNDG' has the same meaning as 'MAP', but without a plotted degree symbol in the labels. = 'LMAP' is similar to 'MAP' except that lowercase characters are used. = 'DMAP' selects labels that are plotted as floating point numbers with degree symbols. = 'MYLAB' selects labels that are defined with the routine MYLAB. CAX is a character string that defines the axes. Default: ('FLOAT', 'XYZ').

• The values 'LOG', 'CLOG' and 'ELOG' can be only used with logarithmic scaling. If these label types are used with linear scaling, DISLIN will change them to 'FLOAT'.
• For the values 'TIME', 'HOURS' and 'SECONDS', the corresponding parameters in GRAF must be in seconds since midnight.
• For the value 'DATE', the corresponding parameters in GRAF must be in days since a base date. The base date can be defined with the routine BASDAT while the number of days since the base date can be calculated with the routine INCDAT. Date labels can be modified with the routine LABMOD.
M Y L A B

MYLAB defines user labels.

 The call is: CALL MYLAB (CSTR, ITICK, CAX) level 1, 2, 3 or: void mylab (const char *cstr, int itick, const char *cax);

 CSTR is a character string containing a label (<= 32 characters). ITICK is the tick number where the label will be plotted (<= 50). Tick numbering starts with 1. CAX is a character string that defines the axes.

LABTYP defines horizontal or vertical labels.

 The call is: CALL LABTYP (CTYPE, CAX) level 1, 2, 3 or: void labtyp (const char * ctype, const char *cax);

 CTYPE is a character string defining the direction. = 'HORI' defines horizontal labels. = 'VERT' defines vertical labels. CAX is a character string that defines the axes, or can have the value 'POLAR', which is a special option for polar plots. The parmeters ('HORI', 'POLAR') mean that true horizontal labels are plotted at the Y-axis. Default: ('HORI', 'XYZ').

LABPOS defines the position of labels.

 The call is: CALL LABPOS (CPOS, CAX) level 1, 2, 3 or: void labpos (const char *cpos, const char *cax);

 CPOS is a character string defining the position. = 'TICKS' means that labels will be plotted at major ticks. = 'CENTER' means that labels will be centred between major ticks. = 'SHIFT' means that the starting and end labels will be shifted. CAX is a character string that defines the axes. Default: ('TICKS', 'XYZ').

LABJUS defines the alignment of axis labels.

 The call is: CALL LABJUS (CJUS, CAX) level 1, 2, 3 or: void labjus (const char *cjus, const char *cax);

 CJUS is a character string defining the alignment of labels. = 'AUTO' means that labels are automatically justified. = 'LEFT' means that labels are left-justified. = 'RIGHT' means that labels are right-justified. = 'OUTW' means that labels are left-justified on the left and lower axes of an axis system. On the right and upper axes, labels are right-justified. = 'INWA' means that labels are right-justified on the left and lower axes of an axis system. On the right and upper axes, labels are left-justified. CAX is a character string that defines the axes. Default: ('AUTO', 'XYZ').

This routine sets the number of digits after the decimal point displayed in labels.

 The call is: CALL LABDIG (NDIG, CAX) level 1, 2, 3 or: void labdig (int ndig, const char *cax);

 NDIG = -2 the number of digits is automatically calculated by DISLIN. NDIG = -1 defines integer labels. NDIG = 0 defines integer labels followed by a decimal point. NDIG = n defines the number of digits after the decimal point. The last digit will be rounded up. CAX is a character string that defines the axes. Default: (1, 'XYZ').

With the routine INTAX, all axes will be labeled with integers.

 The call is: CALL INTAX level 1, 2, 3 or: void intax (void);

This routine sets the distance between labels and ticks.

 The call is: CALL LABDIS (NDIS, CAX) level 1, 2, 3 or: void labdis (int ndis, const char *cax);

 NDIS is the distance in plot coordinates. CAX is a character string that defines the axes. Default: (24, 'XYZ').

The routine LABMOD modifies the appearance of date labels enabled with the keyword 'DATE' in the routine LABELS. Normally, date labels will be plotted in the form dd-mmm-yyyy.

 The call is: CALL LABMOD (CKEY, CVAL, CAX) level 1, 2, 3 or: void labmod (const char *ckey, const char *cval, const char *cax);

 CKEY is a character string containing one of the following keywords: = 'YEAR' means that the century field will be modified in date labels. For CKEY = 'YEAR', CVAL can have the values 'NONE', 'SHORT' and 'FULL'. 'NONE' suppresses the year field while 'SHORT' suppresses the century in the year field. The default values is 'FULL'. = 'DAYS' means that the day field will be modified. CVAL can have the values 'NONE', 'SHORT', 'LONG', 'NAME' and 'FULL'. For CVAL = 'NONE', the day field will be suppressed, for CVAL = 'SHORT', the day will be plotted as a number without a leading zero. CVAL = 'LONG' means that the day will be plotted as a number with two digits, CVAL = 'NAME' means that abbreviations of the weekday names will be plotted and CVAL = 'FULL' means that the full weekday names will be displayed. The default value is CVAL = 'LONG'. = 'MONTH' means that the month field will be modified. CVAL can have the values 'NONE', 'SHORT', 'LONG', 'NAME', 'TINY' and 'FULL'. For CVAL = 'NONE', the month field will be suppressed, for CVAL = 'SHORT', the month will be plotted as a number without a leading zero. CVAL = 'LONG' means that the month will be plotted as a number with two digits, CVAL = 'NAME' means that abbreviations of the month names will be plotted, CVAL = 'TINY' means that only the first character of month names will be plotted and CVAL = 'FULL' means that the full month names will be displayed. The default value is CVAL = 'NAME'. = 'LANG' defines the language used for weekdays and month names in date labels. CVAL can have the values 'ENGLISH', 'SPANISH' and 'GERMAN'. The default value for CVAL is 'ENGLISH'. = 'FORM' defines the order of the date fields. CVAL can have the values 'DMY', 'DYM', 'YDM', 'YMD', 'DYM' and 'MDY'. The default is CVAL = 'DMY'. = 'SEPA' defines a separator character used in date labels. CVAL is a character string containing the separator character. The default is CVAL = '-'. = 'CASE' defines if weekdays and month names are plotted in uppercase characters or in lowercase characters with a leading uppercase character. CVAL can have the values 'UPPER' and 'NONE'. The default value is 'NONE'. = 'STEP' defines a step between labels. CVAL can have the values 'DAYS', 'MONTH', 'DMONTH', 'QUARTER', 'HALF', 'YEAR', 'DYEAR' and 'QYEAR'. For CVAL = 'DAYS', the label step specified in the routine GRAF will be used. The default value is CVAL = 'DAYS'. CAX is a character string that defines the axes.

The routine POLMOD modifies the appearance of angle labels plotted with the routine GRAFP.

 The call is: CALL POLMOD (CPOS, CDIR) level 1, 2, 3 or: void polmod (const char *cpos, const char *cdir);

 CPOS is a character string that defines the position of the first label. CPOS can have the values 'RIGHT', 'TOP', 'LEFT' and 'BOTTOM'. CDIR defines the direction of the labels. CDIR can have the values 'CLOCKWISE' and 'ANTICLOCK'. Default: ('RIGHT', 'ANTICLOCK').

With TIMOPT time labels can be plotted in the format 'hh:mm'. The default is 'hhmm'.

 The call is: CALL TIMOPT level 1, 2, 3 or: void timopt (void);

The routine RGTLAB right-justifies user labels. By default, user labels are left-justified.

 The call is: CALL RGTLAB level 1, 2, 3 or: void rgtlab (void);

## 6.2.6 Modifying Axis Titles

N A M E

NAME defines axis titles.

 The call is: CALL NAME (CSTR, CAX) level 1, 2, 3 or: void name (const char *cstr, const char *cax);

 CSTR is a character string containing the axis title (<= 132 characters). CAX is a character string that defines the axes. Default: (' ', 'XYZ').

HNAME defines the character height for axis names.

 The call is: CALL HNAME (NHNAME) level 1, 2, 3 or: void hname (int nhname);

 NHNAME is the character height in plot coordinates. Default: NHNAME = 36

NAMDIS sets the distance between axis names and labels.

 The call is: CALL NAMDIS (NDIS, CAX) level 1, 2, 3 or: void namdis (int ndis, const char *cax);

 NDIS is the distance in plot coordinates. CAX is a character string that defines the axes. Default: (30, 'XYZ').

The routine NAMJUS defines the alignment of axis titles.

 The call is: CALL NAMJUS (CJUS, CAX) level 1, 2, 3 or: void namjus (const char *cjus, const char *cax);

 CJUS is a character string that can have the values 'CENT', 'LEFT' and 'RIGHT'. CAX is a character string that defines the axes. Default: ('CENT', 'XYZ').

The routine RVYNAM is used to plot names and labels on right Y-axes and colour bars at an angle of 90 degrees. By default, they are plotted at an angle of 270 degrees.

 The call is: CALL RVYNAM level 1, 2, 3 or: void rvynam (void);

## 6.2.7 Suppressing Axis Parts

N O L I N E

After a call to NOLINE the plotting of axis lines will be suppressed.

 The call is: CALL NOLINE (CAX) level 1, 2, 3 or: void noline (const char *cax);

 CAX is a character string that defines the axes.

With a call to AXENDS certain labels can be suppressed.

 The call is: CALL AXENDS (COPT, CAX) level 1, 2, 3 or: void axends (const char *copt, const char *cax);

 COPT is a character string that defines which labels will be suppressed. = 'NONE' means that all labels will be displayed. = 'FIRST' means that only the starting label will be plotted. = 'NOFIRST' means that the starting label will not be plotted. = 'LAST' means that only the ending label will be plotted. = 'NOLAST' means that the ending label will not be plotted. = 'ENDS' means that only the start and end labels will be plotted. = 'NOENDS' means that start and end labels will be suppressed. CAX is a character string that defines the axes. Default: ('NONE', 'XYZ').

The routine NOGRAF suppresses the plotting of an axis system.

 The call is: CALL NOGRAF level 1 or: void nograf (void);

The routine AX2GRF suppresses the plotting of the upper X- and left Y-axis.

 The call is: CALL AX2GRF level 1, 2, 3 or: void ax2grf (void);

SETGRF removes a part of an axis or a complete axis from an axis system.

 The call is: CALL SETGRF (C1, C2, C3, C4) level 1, 2, 3 or: void setgrf (const char *c1, const char *c2, const char *c3, const char *c4);

 Ci are character strings corresponding to the four axes of an axis system. C1 corresponds to the lower X-axis, C2 to the left Y-axis, C3 to the upper X-axis and C4 to the right Y-axis. The parameters can have the values 'NONE', 'LINE', 'TICKS', 'LABELS' and 'NAME'. With 'NONE', complete axes will be suppressed, with 'LINE', only axis lines will be plotted, with 'TICKS', axis lines and ticks will be plotted, with 'LABELS' axis lines, ticks and labels will be plotted and with 'NAME', all axis elements will be displayed. Default: ('NAME', 'NAME', 'TICKS', 'TICKS').

• By default, GRAF plots a frame of thickness 1 around axis systems. Therefore, in addition to the parameter 'NONE', FRAME should be called with the parameter 0 for suppressing complete axes.
• SETGRF does not reset the effect of NOGRAF and NOLINE. This must be done using RESET.
A X S E R S

The routine AXSERS erases the contents of an axis system.

 The call is: CALL AXSERS level 2, 3 or: void axsers (void);

## 6.2.8 Modifying Clipping

C L P W I N

The routine CLPWIN defines a rectangular clipping area on the page.

 The call is: CALL CLPWIN (NX, NY, NW, NH) level 1, 2, 3 or: void clpwin (int nx, int ny, int nw, int nh);

 NX, NY are the plot coordinates of the upper left corner. NW, NH are the width and height of the rectangle in plot coordinates.

The routine CLPBOR sets the clipping area to the entire page or to the axis system.

 The call is: CALL CLPBOR (COPT) level 1, 2, 3 or: void clpbor (const char *copt);

 COPT is a character string that can have the values 'PAGE' and 'AXIS'. Default: COPT = 'PAGE'.

The suppressing of lines outside of the borders of an axis system can be disabled with NOCLIP.

 The call is: CALL NOCLIP level 1, 2, 3 or: void noclip (void);

GRACE defines a margin around axis systems where lines will be clipped.

 The call is: CALL GRACE (NGRA) level 1, 2, 3 or: void grace (int ngra);

 NGRA is the width of the margin in plot coordinates. If NGRA is negative, lines will be clipped inside the axis system. Default: NGRA = -1

## 6.2.9 Framing Axis Systems

F R A M E

FRAME defines the thickness of frames plotted by routines such as GRAF and LEGEND.

 The call is: CALL FRAME (NFRM) level 1, 2, 3 or: void frame (int nfrm);

 NFRM is the thickness of the frame in plot coordinates. If NFRM is negative, the frame will be thickened from the inside. If positive, the frame will be thickened towards the outside. Default: NFRM = 1

The colour of frames can be defined with the routine FRMCLR.

 The call is: CALL FRMCLR (NCLR) level 1, 2, 3 or: void frmclr (int nclr);

 NCLR is a colour value. If NCLR = -1, the current colour is used. Default: NCLR = -1.

## 6.2.10 Setting Colours

A X S B G D

The routine AXSBGD defines a background colour for axis systems.

 The call is: CALL AXSBGD (NCLR) level 1, 2, 3 or: void axsbdg (int nclr);

 NCLR is a colour value. If NCLR = -1, the background of an axis system is not filled in GRAF. Default: NCLR = -1

AXCLRS selects colours for single parts of axes.

 The call is: CALL AXCLRS (NCLR, COPT, CAX) level 1, 2, 3 or: void axclrs (int nclr, const char *copt, const char *cax);

 NCLR is a colour value. If NCLR = -1, the actual colour is used. COPT is a character string that can have the values 'LINE', 'TICKS', 'LABELS', 'NAME' and 'ALL'. CAX is a character string that defines the axes. Default: (-1, 'ALL', 'XYZ').

• By default, a frame of thickness 1 is plotted around axis systems. This may overplot the colour of axis lines (see FRAME, FRMCLR).

## 6.2.11 Axis System Titles

T I T L I N

This subroutine defines up to four lines of text used for axis system titles. The text can be plotted with TITLE after a call to GRAF.

 The call is: CALL TITLIN (CSTR, IZ) level 1, 2, 3 or: void titlin (const char *cstr, int iz);

 CSTR is a character string (<= 132 characters). IZ is an integer that contains a value between 1 and 4 or -1 and -4. If IZ is negative, the line will be underscored. Default: All lines are filled with blanks.

The routine TITJUS defines the alignment of title lines.

 The call is: CALL TITJUS (CJUS) level 1, 2, 3 or: void titjus (const char *cjus);

 CJUS is a character string that can have the values 'CENT', 'LEFT' and 'RIGHT'. Default: CJUS = 'CENT'.

Title lines are centred above axis systems by default but can be left-justified with a call to LFTTIT. This routine has the same meaning as TITJUS ('LEFT').

 The call is: CALL LFTTIT level 1, 2, 3 or: void lfttit (void);

The routine TITPOS defines the position of title lines which can be plotted above or below axis systems.

 The call is: CALL TITPOS (CPOS) level 1, 2, 3 or: void titpos (const char *cpos);

 CPOS is a character string that can have the values 'ABOVE' and 'BELOW'. Default: CPOS = 'ABOVE'.

LINESP defines the spacing between title and legend lines.

 The call is: CALL LINESP (XFAC) level 1, 2, 3 or: void linesp (float xfac);

 XFAC The space between lines is set to XFAC * character height. Default: XFAC = 1.5

HTITLE defines the character height for titles. The character height defined by HEIGHT will be used if HTITLE is not called.

 The call is: CALL HTITLE (NHCHAR) level 1, 2, 3 or: void htitle (int nhchar);

 NHCHAR is the character height in plot coordinates.

The space between titles and axis systems can be enlarged or reduced with VKYTIT. By default, the space is 2 * character height.

 The call is: CALL VKYTIT (NV) level 1, 2, 3 or: void vkytit (int nv);

 NV is an integer that determines the spacing between axis systems and titles. If NV is negative, the space will be reduced by NV plot coordinates. If NV is positive, the space will be enlarged by NV plot coordinates. Default: NV = 0

## 6.3 Colours

This paragraph describes routines that modify colours. A colour value in DISLIN may be an entry of the current colour table, or an explicit RGB value. When specifying an explicit RGB value, the colour value must have the following hexadecimal form: 01bbggrr. The low-order byte contains the intensity of red, the second byte the intensity of green and the third byte the intensity of blue. The high-order byte must have the value 1. The function INTRGB creates an explicit RGB value from RGB coordinates. If the output device can only display 256 colours and an explicit RGB value is given, the nearest entry in the current colour table that matches the RGB coordinates will be used. Some routines define colours also by name such as COLOR, or by RGB coordinates such as SETRGB.

## 6.3.1 Changing the Foreground Colour

C O L O R

COLOR defines the colours used for plotting text and lines.

 The call is: CALL COLOR (CNAME) level 1, 2, 3 or: void color (const char *cname);

 CNAME is a character string that can have the values 'BLACK', 'RED', 'GREEN', 'BLUE', 'CYAN', 'YELLOW', 'ORANGE', 'MAGENTA', 'WHITE', 'FORE', 'BACK', 'GRAY' and 'HALF'. The keyword 'FORE' resets the color to the default value, while the keyword 'BACK' sets the colour to the background colour. 'HALF' sets a new foreground colour with the half intensity of the current foreground colour.

• The values 'BLACK' and 'WHITE' define not absolute colours. If the output format is in reverse mode, 'BLACK' is interpreted as 'WHITE' and 'WHITE' is interpreted as 'BLACK'. If you want to use true black and true white, you can use the routine SETRGB (0., 0., 0.) and SETRGB (1., .1., 1.).

The routine SETCLR sets the foreground colour where the colour can be specified as a colour table entry or as an explicit RGB value.

 The call is: CALL SETCLR (NCOL) level 1, 2, 3 or: void setclr (int ncol);

 NCOL is a colour value. Default: NCOL = 255 (White).

The routine SETRGB defines the foreground colour specified in RGB coordinates.

 The call is: CALL SETRGB (XR, XG, XB) level 1, 2, 3 or: void setrgb (float xr, float xg, float xb);

 XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1. If the output device cannot display true colours, SETRGB sets the nearest entry in the colour table that matches the RGB coordinates.

## 6.3.2 Modifying Colour Tables

S E T V L T

SETVLT selects a colour table.

 The call is: CALL SETVLT (CVLT) level 1, 2, 3 or: void setvlt (const char *cvlt);

 CVLT is a character string that defines the colour table. = 'SMALL' defines a small colour table with the 8 colours: 1 = BLACK, 2 = RED, 3 = GREEN, 4 = BLUE, 5 = YELLOW, 6 = ORANGE, 7 = CYAN and 8 = MAGENTA. = 'VGA' defines the 16 standard colours of a VGA graphics card. = 'RAIN' defines 256 colours arranged in a rainbow where 0 means black and 255 means white. = 'SPEC' defines 256 colours arranged in a rainbow where 0 means black and 255 means white. This colour table uses more violet colours than 'RAIN'. = 'GREY' defines 256 grey scale colours where 0 means black and 255 is white. = 'RRAIN' is the reverse colour table of 'RAIN'. = 'RSPEC' is the reverse colour table of 'SPEC'. = 'RGREY' is the reverse colour table of 'GREY'. = 'TEMP' defines a temperature colour table. The default colour table is 'RAIN'.

The routine MYVLT changes the current colour table.

 The call is: CALL MYVLT (XR, XG, XB, N) level 0, 1, 2, 3 or: void myvlt (const float *xr, const float *xg, const float *xb, int n);

 XR, XG, XB are arrays containing RGB coordinates in the range 0 to 1. N is the number of colour entries.

The routine SETIND allows the user to change the current colour table.

 The call is: CALL SETIND (INDEX, XR, XG, XB) level 1, 2, 3 or: void setind (int index, float xr, float xg, float xb);

 INDEX is an index between 0 and 255. XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1.

The routine VLTFIL saves the current colour table to a file, or loads a colour table from a file.

 The call is: CALL VLTFIL (CFIL, COPT) level 1, 2, 3 or: void vltfil (const char *cfil, const char *copt);

 CFIL is a character string containing a filename. Colour entries are stored in the file as RGB coordinates in the range 0 to 1. COPT is a character string that can have the values 'SAVE' and 'LOAD'.

## 6.3.3 Utility Routines for Colours

I N T R G B

The function INTRGB creates an explicit colour value from RGB coordinates.

 The call is: NCLR = INTRGB (XR, XG, XB) level 1, 2, 3 or: int intrgb (float xr, float xg, float xb);

 XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1. NCLR is the returned colour value.

The function INDRGB returns the nearest entry in the current colour table that matches given RGB coordinates.

 The call is: N = INDRGB (XR, XG, XB) level 1, 2, 3 or: int indrgb (float xr, float xg, float xb);

 XR, XG, XB are the RGB coordinates of a colour in the range 0 to 1. N is the returned colour index.

Sometimes, it is easier to specify colours as HSV coordinates where H is the hue, S the saturation and V the value of a colour. The following routines convert coordinates from the HSV to the RGB model and vice versa.

The routine HSVRGB converts HSV coordinates to RGB coordinates.

 The call is: CALL HSVRGB (XH, XS, XV, XR, XG, XB) level 1, 2, 3 or: void hsvrgb (float xh, float xs, float xv, float *xr, float *xg, float *xb);

 XH, XS, XV are the hue, saturation and value of a colour. XH must be in the range 0 to 360 degrees while XS and XV can have values between 0 and 1. In the HSV model, colours lie in a spectral order on a six-sided pyramid where red corresponds to the angle 0, green to 120 and blue to 240 degrees. XR, XG, XB are the RGB coordinates in the range 0 to 1 calculated by HSVRGB.

The routine RGBHSV converts RGB coordinates to HSV coordinates.

 The call is: CALL RGBHSV (XR, XG, XB, XH, XS, XV) level 1, 2, 3 or: void rgbhsv (float xr, float xg, float xb, float *xh, float *xs, float *xv);

## 6.4 Text and Numbers

H E I G H T

HEIGHT defines the character height.

 The call is: CALL HEIGHT (NHCHAR) level 1, 2, 3 or: void height (int nhchar);

 NHCHAR is the character height in plot coordinates. Default: NHCHAR = 36

This routine modifies the direction of text plotted with the routines MESSAG, NUMBER, RLMESS and RLNUMB.

 The call is: CALL ANGLE (NDEG) level 1, 2, 3 or: void angle (int ndeg);

 NDEG is an angle measured in degrees and a counter-clockwise direction. Default: NDEG = 0

The routine TXTJUS defines the alignment of text plotted with the routines MESSAG and NUMBER.

 The call is: CALL TXTJUS (CJUS) level 1, 2, 3 or: void txtjus (const char *cjus);

 CJUS is a character string that can have the values 'LEFT', 'RIGHT' and 'CENT' for horizontal alignment and 'TOP', 'BOTTOM' and 'MIDDLE' for vertical alignment. Default: CJUS = 'LEFT', 'TOP'.

TXTBGD defines a background colour for text and numbers.

 The call is: CALL TXTBGD (NCLR) level 1, 2, 3 or: void txtbgd (int nclr);

 NCLR is a colour number. The default value -1 means that no background is plotted. The margin between background border and text is (LINESP-1) * NHCHAR, where LINESP is the value in LINESP. Default: NCLR = -1

FRMESS defines the thickness of frames around text plotted by MESSAG.

 The call is: CALL FRMESS (NFRM) level 1, 2, 3 or: void frmess (int nfrm);

 NFRM is the thickness of frames in plot coordinates. If NFRM is negative, frames will be thickened from the inside. If positive, frames will be thickened towards the outside. The margin between frames and text is (LINESP - 1) * NHCHAR, where LINESP is the value in LINESP. Default: NFRM = 0

NUMFMT modifies the format of numbers plotted by NUMBER and RLNUMB.

 The call is: CALL NUMFMT (COPT) level 1, 2, 3 or: void numfmt (const char *copt);

 COPT is a character string defining the format. = 'FLOAT' will plot numbers in floating point format. = 'EXP' will plot numbers in exponential format where fractions range between 1 and 10. = 'FEXP' will plot numbers in the format fEn where f ranges between 1 and 10. = 'LOG' will plot numbers logarithmically with base 10 and the corresponding exponents. The exponents must be passed to NUMBER and RLNUMB. Default: COPT = 'FLOAT'.

• SETEXP and SETBAS alter the position and size of exponents.

NUMODE alters the appearance of numbers plotted by NUMBER and RLNUMB.

 The call is: CALL NUMODE (CDEC, CGRP, CPOS, CFIX) level 1, 2, 3 or: void numode (const char *cdec, const char *cgrp, const char *cpos, const char *cfix);

 CDEC is a character string that defines the decimal notation. = 'POINT' defines a point. = 'COMMA' defines a comma. CGRP is a character string that defines the grouping of 3 digits. = 'NONE' means no grouping. = 'SPACE' defines a space as separator. = 'POINT' defines a point as separator. = 'COMMA' defines a comma as separator. CPOS is a character string that defines the sign preceding positive numbers. = 'NONE' means no preceding sign. = 'SPACE' defines a space as a preceding sign. = 'PLUS' defines a plus as a preceding sign. CFIX is a character string specifying character spacing. = 'NOEQUAL' is used for proportional spacing. = 'EQUAL' is used for non-proportional spacing. Default: ('POINT','NONE','NONE','NOEQUAL').

CHASPC affects inter character spacing.

 The call is: CALL CHASPC (XSPC) level 1, 2, 3 or: void chaspc (float xspc);

 XSPC is a real number that contains a multiplier. If XSPC < 0, the inter character spacing will be reduced by XSPC * NH plot coordinates where NH is the current character height. If XSPC > 0, the spacing will be enlarged by XSPC * NH plot coordinates. Default: XSPC = 0.

CHAWTH affects the width of characters.

 The call is: CALL CHAWTH (XWTH) level 1, 2, 3 or: void chawth (float xwth);

 XWTH is a real number between 0 and 2. If XWTH < 1, the character width will be reduced. If XWTH > 1, the character width will be enlarged. Default: XWTH = 1.

CHAANG defines an inclination angle for characters.

 The call is: CALL CHAANG (ANGLE) level 1, 2, 3 or: void chaang (float angle);

 ANGLE is the inclination angle between characters and the vertical direction in degrees (-60 <= ANGLE <= 60). Default: ANGLE = 0.

All fonts in DISLIN except for the default font are proportional. After a call to FIXSPC the characters of a proportional font will also be plotted with a constant character width.

 The call is: CALL FIXSPC (XFAC) level 1, 2, 3 or: void fixspc (float xfac);

 XFAC is a real number containing a scaling factor. Characters will be centred in a box of width XFAC * XMAX where XMAX is the largest character width of the current font.

## 6.5 Fonts

The following routines define character sets of varying style and plot velocity. All fonts except for the default font DISALF are proportional. Each font provides 6 alphabets.

The calls are:

• If one of the shaded fonts SERIF, HELVE or HELVES is used, only the outlines of characters are plotted to minimize plotting time. With the statement CALL SHDCHA characters will be shaded.

PSFONT defines a PostScript font.

 The call is: CALL PSFONT (CFONT) level 1, 2, 3 or: void psfont (const char *cfont);

 CFONT is a character string containing the font. Standard font names in PostScript are:

         Times-Roman                   Courier
Times-Bold                    Courier-Bold
Times-Italic                  Courier-Oblique
Times-BoldItalic              Courier-BoldOblique
Helvetica                     AvantGarde-Book
Helvetica-Bold                AvantGarde-Demi
Helvetica-Oblique             AvantGarde-BookOblique
Helvetica-BoldOblique         AvantGarde-DemiOblique
Helvetica-Narrow              Bookman-Light
Helvetica-Narrow-Bold         Bookman-LightItalic
Helvetica-Narrow-Oblique      Bookman-Demi
Helvetica-Narrow-BoldOblique  Bookman-DemiItalic
NewCenturySchlbk-Roman        Palatino-Roman
NewCenturySchlbk-Italic       Palatino-Italic
NewCenturySchlbk-Bold         Palatino-Bold
NewCenturySchlbk-BoldItalic   Palatino-BoldItalic
ZapfChancery-MediumItalic     Symbol
ZapfDingbats

• The file format must be set to 'PS', 'EPS, 'PDF' or 'SVG' with the routine METAFL. For SVG files, the Times, Helvetica and Courier fonts can be used.
• Font names cannot be shortened. Some printers provide additional non-standard fonts. These fonts should be specified exactly in upper and lower characters as they are described in the printer manuals. PostScript suppresses any graphics if there is a syntax error in the font name. Standard font names are not case-sensitive.
• A call to a DISLIN font resets PostScript fonts.
W I N F N T

WINFNT defines a TrueType font for WMF files and screen output on Windows displays.

 The call is: CALL WINFNT (CFONT) level 1, 2, 3 or: void winfnt (const char *cfont);

 CFONT is a character string containing the font. The following fonts can normally be used on Windows:

         Courier New
Courier New Bold
Courier New Italic
Courier New Bold Italic
Times New Roman
Times New Roman Bold
Times New Roman Italic
Times New Roman Bold Italic
Arial
Arial Bold
Arial Italic
Arial Bold Italic

• The coding of a Windows font should correspond to the character coding defined with CHACOD. For example, if the character coding in CHACOD is set to 'STANDARD' or 'ISO1', an ISO-Latin-1 should be used. If the character coding is set to 'UTF8', a Unicode font should be loaded.
X 1 1 F N T

X11FNT defines an X11 font for screen output on X11 displays.

 The call is: CALL X11FNT (CFONT, COPT) level 1, 2, 3 or: void x11fnt (const char *cfont, const char *copt);

 CFONT is a character string containing the first part of an X11 font. COPT is a character string containing the last part of an X11 font. IF COPT = 'STANDARD', the value '-*-*-*-*-iso8859-1' is used for the last part of an X11 font.

• CFONT must begin and end with the separator '-' and must contain the first five fields of an X11 font. DISLIN adds then the point size and a transformation matrix to the font. IF COPT has not the value 'STANDARD', it must begin with the character '-' and contain the last 6 fields of an X11 font.
• The coding of the X11 font should correspond to the coding defined with CHACOD (see WINFNT).

Here are some examples for the contents of CFONT:

       -Adobe-Times-Medium-R-Normal-

B M P F N T

DISLIN contains some bitmap fonts that can be set with the routine BMPFNT. Bitmap fonts are allowed for screen output and for a bitmap file format. They can be used to increase the quality of directly created raster formats such as PNG and TIFF.

 The call is: CALL BMPFNT (CFONT) level 1, 2, 3 or: void bmpfnt (const char *cfont);

 CFONT is a character string that can have the values 'COMPLEX', 'SIMPLEX' and 'HELVE'. The DISLIN bitmap fonts contain characters for 'STANDARD', 'ISO1', 'ISO2' and 'ISO3' codings.

TTFONT loads a Windows TrueType font. The characters of the font can be used for all Dislin output devices. By default, only the outlines of the characters are plottted. After the statement CALL SHDCHA characters will be shaded.

 The call is: CALL TTFONT (CFILE) level 1, 2, 3 or: void ttfont (const char *cfile);

 CFILE is a character string that contains the filename of a TrueType font. If the filename does not contain a full directory path, the file is searched in the current directory, in the Windows fonts and in the Dislin fonts directory. For Linux, the font is also searched in the directory '/usr/X11R6/lib/X11/fonts/truetype/'

• The intention of this routine is to make Unicode characters available for all Dislin output formats.

The routine HWFONT sets a standard hardware font if hardware fonts are supported by the current file format. For example, if the file format is PostScript, the font 'Times-Roman' is used, if the file format is 'CONS' or 'XWIN', 'Times New Roman' is used for Windows 95/NT and '-*-Times-Bold-R-Normal-' is used for X11. If no hardware fonts are supported, COMPLX is used.

 The call is: CALL HWFONT level 1, 2, 3 or: void hwfont (void);

The routine CHACOD defines the coding of characters.

 The call is: CALL CHACOD (COPT) level 1, 2, 3 or: void chacod (const char *copt);

 COPT is a character string that can have the values 'STANDARD', 'ISO1', 'ISO2', 'ISO3', 'ISO5', 'ISO7', 'KOI8' and 'UTF8'. The keyword 'STANDARD' means the DISLIN coding of characters as displayed in the figures 6.4 to 6.10. 'ISO5' and 'KOI8' are encodings for Cyrillic characters while 'ISO7' is a coding for Greek characters. 'UTF8' is a coding for Unicode characters. If COPT is not 'STANDARD', the coding is mapped to the available DISLIN characters. Default: COPT = 'STANDARD'.

BASALF defines the base alphabet.

 The call is: CALL BASALF (CALPH) level 1, 2, 3 or: void basalf (const char *calph);

 CALPH is a character string that can have the values 'STANDARD', 'ITALIC', 'GREEK', 'SCRIPT', 'RUSSIAN' and 'MATHEMATIC'. These alphabets can be used with all fonts, but may be ignored for some special character codings. Default: 'STANDARD'.

SMXALF defines shift characters to shift between the base and an alternate alphabet.

 The call is: CALL SMXALF (CALPH, C1, C2, N) level 1, 2, 3 or: void smxalf (const char *calph, const char *c1, const char *c2, int n);

 CALPH is a character string containing an alphabet. In addition to the names in BASALF, CALPH can have the value 'INSTRUCTION'. C1 is a character that shifts to the alternate alphabet. C2 is a character that shifts back to the base alphabet. C1 and C2 may be identical. After the last plotted character of a character string, DISLIN automatically shifts back to the base alphabet. N is an integer between 1 and 6. Up to 6 alternate alphabets can be defined.

The routine PSMODE sets PostScript options.

 The call is: CALL PSMODE (COPT) level 0, 1, 2, 3 or: void psmode (const char *copt);

 COPT is a character string that can have the values 'NONE', 'GREEK', 'ITALIC', 'BOTH', 'SINGLE' and 'MULTI'. The options 'GREEK', 'ITALIC' and 'BOTH' enable Greek and Italic PostScript characters. If they are disabled, DISLIN vector characters are used. PSMODE must be called in level 1, 2 or 3 for this options. The option 'SINGLE' defines an old-style PostScript format without PostScript commands for multiple pages. PSMODE must be called in level 0 for the options 'SINGLE' and 'MULTI'. Defaults: 'NONE', 'MULTI'.

European characters can be plotted by using their character codes in text strings where different character codings are available (see CHACOD), or by defining a shift character that converts the following character into a European character. The routine EUSHFT defines shift characters for European characters.

 The call is: CALL EUSHFT (CNAT, CSHIFT) level 1, 2, 3 or: void eushft (const char *cnat, const char *cshift);

 CNAT is a character string that can have the values 'GERMAN', 'FRENCH', 'SPANISH', 'DANISH', 'ACUTE', 'GRAVE', 'CIRCUM' and 'TURKISH'. CSHIFT is a shift character. For example, with CNAT = 'GERMAN', the characters A, O, U, a, o, u and s placed directly after CSHIFT will be plotted as Ä, Ö, Ü, ä, ö, ü and ß.

• Shift characters can be defined multiple where the characters must be different.
• The Turkish characters are only supported by COMPLX and by the bitmap fonts defined with BITMAP. The other European characters are also supported by PostScript.
• If the shift characters should be plotted in a text string, they must be doubled.
• European characters are not available for the character codings 'ISO5', 'ISO7' and 'KOI8'.
The following table shows all possible European characters. The characters on the left side of a column are shifted to the characters on the right side of that column:

Figure 6.3: EUSHFT Character Set

## 6.6 Indices and Exponents

Indices and exponents can be plotted by using control characters in characters strings, or by using the TeX syntax described in paragraph 6.7. There are 3 predefined control characters in DISLIN which can be altered with the routines NEWMIX and SETMIX. The predefined character

 [ is used for exponents. The character height is reduced by the scaling factor FEXP and the pen is moved up FBAS * NH plot coordinates where NH is the current character height. ] is used for indices. The pen is moved down FBAS * NH plot coordinates and the character height is reduced by the scaling factor FEXP. $is used to move the pen back to the base-line. This will automatically be done at the end of a character string. FBAS and FEXP have the default values 0.6 and 0.8, respectively, these values can be changed with the routines SETBAS and SETEXP. This routine instructs DISLIN to search for control characters in character strings.  The call is: CALL MIXALF level 1, 2, 3 or: void mixalf (void); SETBAS defines the position of indices and exponents. This routine also affects logarithmic axis labels.  The call is: CALL SETBAS (FBAS) level 1, 2, 3 or: void setbas (float fbas);  FBAS is a real number used as a scaling factor. The pen will be moved up or down by FBAS * NH plot coordinates to plot exponents or indices. NH is the current character height. Default: FBAS = 0.6. SETEXP sets the character height of indices and exponents.  The call is: CALL SETEXP (FEXP) level 1, 2, 3 or: void setexp (float fexp);  FEXP is a real number used as a scaling factor. The character height of indices and exponents is set to FEXP * NH where NH is the current character height. Default: FEXP = 0.8 NEWMIX defines an alternate set of control characters for plotting indices and exponents. The default characters '[', ']' and '$' are replaced by '^', '_' and '%'.

 The call is: CALL NEWMIX level 1, 2, 3 or: void newmix (void);

SETMIX defines global control characters for plotting indices and exponents.

 The call is: CALL SETMIX (C, CMIX) level 1, 2, 3 or: void setmix (const char *c, const char *cmix);

 C is a new control character. CMIX is a character string that defines the function of the control character. CMIX can have the values 'EXP', 'IND', 'RES' and 'LEG' for exponents, indices, resetting the base-line, and for multiple text lines in legends, respectively.

• The routines NEWMIX and SETMIX only modify the control characters. A call to MIXALF is always necessary to plot indices and exponents.

## 6.7 Instruction Alphabet

The instruction alphabet contains commands that control pen movements and character sizes during the plotting of character strings. It is provided for the representation of complicated formulas. An alternate method for plotting of complicated formulas is described in paragraph 6.7, TeX Instructions for Mathematical Formulas''.

The instruction alphabet can be used in the same way as other alphabets in DISLIN. Shift characters must be defined with the routine SMXALF to switch between the base and the instruction alphabet.

The commands of the instruction alphabet consist of a single character and an optional parameter. If the parameter is omitted, DISLIN will use default values. A parameter can be a real number, an integer or the character 'X' which resets the parameter back to the entry value at the beginning of the character string.

Commands of the instruction alphabet can only change plot parameters temporarily within a character string. At the end of a character string, all parameters are reset to their entry values.

The following table summarizes all instruction commands. The character r means a real parameter and i an integer. The base-line of character strings is placed directly below them. Commands can be given in uppercase or lowercase letters. Real parameters can be specified without decimal points while integer parameters cannot have decimal points. Several commands can follow one another. Blanks between commands will be ignored.

## Instruction-Alphabet


------------------------------------------------------------
| Cmd. Par.  Default            Description                |
------------------------------------------------------------
|  A   real     1.    moves the pen horizontally by r * NH |
|                     plot  coordinates  where  NH is  the |
|                     current character height.  If r < 0, |
|                     the pen  will be moved backwards.    |
|                                                          |
|  C   integer  1     moves the pen horizontally by i cha- |
|                     racter  spaces.  If i < 0,  the  pen |
|                     will be moved backwards.             |
|                                                          |
|  D   real     1.    moves the pen  down from  the  base- |
|                     line by r * NH plot coordinates.  If |
|                     r > 0,  NH  is the  entry  character |
|                     height.  If r < 0, NH is the current |
|                     character height.                    |
|                                                          |
|  E                  moves the pen up by 0.75 * character |
|                     height  and  reduces  the  character |
|                     height  by  the  scaling  factor 0.6 |
|                     (for exponents).                     |
|                                                          |
|  F   integer   1    moves the pen horizontally by i spa- |
|                     ces.  If i is  negative,  the pen is |
|                     moved backwards.                     |
|                                                          |
|  G   integer   1    moves  the pen  horizontally  to the |
|                     tab position with the index i, where |
|                      1 <= i <= 20.                       |
|                                                          |
|  H   real      0.6  sets the character height to r * NH. |
|                     If r > 0, NH is the entry  character |
|                     height. If r < 0,  NH is the current |
|                     character height.                    |
|                                                          |
|  I                  moves the pen down by 0.35 * charac- |
|                     ter  height  and multiplies the cha- |
|                     racter height by 0.6 (for indices).  |
|                                                          |
|  J   integer   1    underscores twice from the tab posi- |
|                     tion i to the current pen position.  |
|                                                          |
|  K   real      0.8  is used to plot characters with con- |
|                     stant  widths.  Characters  will  be |
|                     centred  in a  box  with  the  width |
|                     r * W where W is the largest charac- |
|                     ter length in the current font.  The |
|                     global routine is FIXSPC.            |
|                                                          |
|  L   integer   1    underscores from the  tab position i |
|                     to the current pen position.         |
|                                                          |
|  M   integer   1    defines the base alphabet.           |
|                     (1 = STAND.,  2 = GREEK,  3 = MATH., |
|                     4 = ITAL., 5 = SCRIPT, 6 = RUSSIAN). |
------------------------------------------------------------

------------------------------------------------------------
| Cmd. Par.  Default            Description                |
------------------------------------------------------------
|  N   integer   1    sets a  colour  i,  where  0 <= i <= |
|                     255. The global routine is SETCLR.   |
|                                                          |
|  O   real      0.   moves the  base-line  vertically  by |
|                     r * character height.  If  r < 0 the |
|                     base-line is moved down.             |
|                                                          |
|  P   integer   1    defines a  horizontal  tab  position |
|                     with the index i  at the current pen |
|                     position, where 1 <= i <= 20.        |
|                     All tab positions are initialized to |
|                     the beginning of the string.         |
|                                                          |
|  R                  resets the  character height and the |
|                     base-line to their entry values.     |
|                                                          |
|  S   integer   0    plots a  symbol  with  the number i, |
|                     where 0 <= i <= 21.                  |
|                                                          |
|  T   integer   0    moves the pen  horizontally from the |
|                     beginning  of the  string  by i plot |
|                     coordinates.                         |
|                                                          |
|  U   real      1.   moves the pen up  from the base-line |
|                     by  r * NH  plot coordinates. If r > |
|                     0, NH is the entry character height. |
|                     If r < 0,  NH is the current charac- |
|                     ter height.                          |
|                                                          |
|  V   integer   1    plots a horizontal line from the tab |
|                     position i to  the current pen posi- |
|                     tion.  The line is moved up from the |
|                     base-line  by 0.5 * character height |
|                     plot coordinates.                    |
|                                                          |
|  W   real      1.   affects the width of characters. The |
|                     global routine is CHAWTH.            |
|                                                          |
|  Y   real      0.   affects  the  character spacing. The |
|                     global routine is CHASPC.            |
|                                                          |
|  Z   real      0.   defines  an  inclination  angle  for |
|                     characters,  where  -60 <= r <= 60.  |
|                     The global routine is CHAANG.        |
------------------------------------------------------------

For the following examples, the characters '{' and '}' are defined with

CALL SMXALF ('INST', '{', '}', 1)

to switch between the instruction and the base alphabet.

## 6.8.1 Introduction

This paragraph presents an alternate method to the DISLIN instruction alphabet for plotting mathematical formulas. The text formatting language TeX has a very easy method for describing mathematical formulas. Since this method is well-known by many scientists, an emulation mode for TeX instructions is added to DISLIN with version 7.4.

TeX instructions can be enabled in DISLIN with the statement CALL TEXMOD ('ON'). If TeX mode is enabled, mixed alphabets defined with SMXALF and the control characters for indices and exponents described in paragraph 6.5 will be ignored.

Mathematical formulas in TeX mode are produced in DISLIN by some special descriptive text. This means that DISLIN must be informed that the following text is to be interpreted as a mathematical formula. The character $in a text switches from text to math mode, and from math to text mode. Therefore, mathematical formulas must be enclosed in a pair of dollar signs. Numbers that appear within formulas are called constants, whereas simple variables are represented by single letters. The universal practice in mathematical typesetting is to put constants in Roman typeface and variables in italics. DISLIN uses this rule by default in math mode. The rule can be modified with the routine TEXOPT. Blanks are totally ignored in math mode and spaces are included automatically by DISLIN between constants, variables and operators. The characters$, {, } and \ have a special meaning in TeX mode and therefore cannot act as printable characters. To include them in normal text, the commands \\$, \{, \} and \\ must be used. Additional, the characters _ and ^ have a special meaning in math mode and can be handled in the same way.

## 6.8.2 Enabling TeX Mode and TeX Options

T E X M O D

The routine TEXMOD can be used to enable TeX mode in DISLIN. In TeX mode, all character strings passed to DISLIN routines can contain TeX instructions for plotting mathematical formulas.

 The call is: CALL TEXMOD (CMODE) level 1, 2, 3 or: void texmod (const char *cmode);

 CMODE is a character string that can have the values 'ON' and 'OFF'. CMODE = 'ON' enables TeX mode and CMODE = 'OFF' disables TeX mode. Default: CMODE = 'OFF'.

The routine TEXOPT sets some TeX options.

 The call is: CALL TEXOPT (COPT, CTYPE) level 1, 2, 3 or: void texopt (const char *copt, const char *ctype);

 COPT is a character string that defines an option. CTYPE is a character string containing a keyword. = 'LIMITS' means that the limits for sums and integrals will be placed above and below the sum and integral signs instead of following them. COPT can have the values 'ON' and 'OFF'. = 'ITALIC' means that for math mode variables will be put in italics. COPT can also have the values 'ON' and 'OFF'. = 'BRACK' means that the Dislin Mathematical vector font can be used for bracket symbols even if a hardware font is enabled. COPT can have the values 'STANDARD' and 'VECTOR'. Defaults: ('ON', 'LIMITS'), ('ON', 'ITALIC'), ('BRACK', 'STANDARD').

The routine TEXVAL defines some scaling and shifting values that are used in TeX formulas.

 The call is: CALL TEXVAL (X, COPT) level 1, 2, 3 or: void texval (float x, const char *copt);

 X is a floating point variable containing the factor. COPT is a character string. ='KEY' defines a factor for the size of indices and exponents. ='H1BR' sets additional spaces that are plotted after bracket symbols defined with \left and before bracket symbols defined with \right. ='H2BR' sets additional spaces that are plotted before bracket symbols defined with \left and after bracket symbols defined with \right. ='VBRACK' defines a scaling factor for the size of bracket symbols. ='WBRACK' defines a scaling factor for the width of bracket symbols. This option is useful for big brackets in PostScript fonts. Defaults: (1.0, 'EXP'), (0.0, 'H1BR), (0.0, 'H2BR), \newline (1.0, 'VBRACK), (1.0, 'WBRACK).

## 6.8.3 Exponents and Indices

Exponents and indices are characters that are either raised or lowered relative to the base line of the text. The character ^ sets the next character as an exponent, while the character _ sets it as an index.

When exponents and indices occur together, their order is unimportant. If the exponent or index contains more than one character, the group of characters must be enclosed in braces { }.

Multiple raisings and lowerings are generated by applying ^ and _ to the exponents and indices.

Note: The commands ^ and _ are only allowed in math mode.

## 6.8.4 Fractions

The instruction \frac{numerator}{denominator} can be used in TeX math mode for plotting fractions. The numerator is plotted on top of the denominator with a horizontal fraction line between them. Fractions may be nested to a depth of 8 within one another.

## 6.8.5 Roots

Roots can be plotted with the syntax \sqrt[n]{arg} where the optional part [n] can be omitted. Roots may be nested inside one another to a depth of 8.

## 6.8.6 Sums and Integrals

Summation and integral signs can be plotted with the two instructions \sum and \int. Sums and integrals can posses upper and lower limits that can be plotted with the exponent and index instructions ^ and _. By default, the limits are placed below and above the summation and integral signs. This can be modified with the routine TEXMOD or with the instruction \nolimits following the summation and integral signs.

## 6.8.7 Greek Letters

The following Greek letters are available in text and in math mode. If they are used in text mode, the first blank character after the letter will be interpreted as a separa- tor and will be ignored.

  \alpha       \theta          o               \chi
\beta        \iota           \pi             \psi
\gamma       \kappa          \rho            \omega
\delta       \lambda         \sigma
\epsilon     \mu             \tau
\zeta        \nu             \upsilon
\eta         \xi             \phi

\Gamma       \Lambda         \Sigma          \Psi
\Delta       \Xi             \Upsilon        \Omega
\Theta       \Pi             \Phi


## 6.8.8 Mathematical Symbols

The following mathematical symbols are available in text and in math mode.

  \pm          \cdot           \cup            \odot
\mp          \ast            \vee            \oplus
\times       \star           \wedge          \ominus

\le, \leq    \ge, \geq       \neq            \sim
\subset      \supset         \cong           \mid
\subseteq    \supseteq       \equiv          \notin
\in          \ni             \parallel       \not=
\approx

\leqslant    \geqslant       \nless          \ngtr
\nleq        \ngeq           \nleqslant      \ngeqslant
\prec        \succ           \nprec          \nsucc
\preceq      \succeq         \npreceq        \nsucceq
\ll          \gg             \lll            \ggg
\nsubseteq   \nsupseteq      \sqsubset       \sqsupset
\sqsubseteq  \sqsupseteq     \doteq          \simeq
\propto      \angle          \measuredangle  \circ
\sphericalangle

\leftarrow   \rightarrow     \Leftrightarrow \downarrow
\Leftarrow   \Rightarrow     \uparrow

\emptyset    \surd           \forall         \backlslash
\nabla       \partial        \exists         \infty
\perp


## 6.8.9 Alternate Alphabets

The DISLIN alphabets 'STANDARD', 'ITALIC', 'GREEK', 'SCRIPT' and 'RUSSIAN' can be used in TeX mode with the instructions \rm, \it, \gr, \cal and \ru.

## 6.8.10 Function Names

The standard for mathematical formulas is to set variable names in italics but the names of functions in Roman. The following function names will be recognized by DISLIN and plotted in Roman.

  \arccos  \arcsin  \arctan  \arg    \cos    \cosh   \cot
\coth    \csc     \dec     \dim    \exp    \hom    \ln
\log     \sec     \sin     \sinh   \tan    \tanh


## 6.8.11 Accents

Accents are available in TeX mode in the same way as in normal DISLIN mode (see EUSHFT)

## 6.8.12 Lines and Symbols above and below Formulas

The commands \overline{arg} and \underline{arg} can be used to draw lines over and under a formula. The command \vec{arg} draws a vector over a formula. \hat{arg}, \tilde{arg} and \dot{arg} draw a circumflex, a tilde and a dot above arg. All commands can be used in TeX text and math mode.

## 6.8.13 Horizontal Spacing

Small amounts of horizontal spacing can be added in TeX mode with the following commands:

  \,  small space      = 3/18 of the current character size
\:  medium space     = 4/18 of the current character size
\;  large space      = 5/18 of the current character size
\!  negative space   = -3/18 of the current character size

Larger amounts of horizontal  spacing can be added  with the
commands:

\quad  extra space   = 1/1 of the current character size
\qquad extra space   = 2/1 of the current character size


## 6.8.14 Selecting Character Size in TeX Mode

The commands \tiny, \scriptsize, \footnotesize, \small, \normalsize, \large, \Large, \LARGE, \huge and \Huge can be used in TeX mode for modifying the character size. The command \normalsize is corresponding to the current character size before the call of the text plotting routine. The character size is decreased or increased by a factor of 1.2 for neighbouring character size commands.

## 6.8.15 Automatic Sizing of Bracket Symbols

Bracket symbols are often used in mathematic formulas, usually in pairs that enclose part of the formula. These bracket symbols should have the same size as the included partial formula. The commands \left lbrack and \right rbrack plot a pair of brackets with the same size as the included formula, where lbrack can be one of the bracket symbols '[', '(' and '{', and rbrack one of the symbols ']', ')' and '}'. The commands \left and \right must appear as a pair, but lbrack and rbrack can be different bracket symbols. If only a single opening or closing bracket should be plotted, the corresponding bracket symbol can have the value '.'.

## 6.8.16 Manual Sizing of Bracket Symbols

The commands \big, \Big, \bigg and \Bigg before one of the bracket symbols '[', '(', '{', ']', ')' and '}' can be used to select explicitly the size of a bracket. The command \low before a bracket symbol plots a smaller bracket symbol.

## 6.8.17 Colours in TeX Mode

The commands \black, \red, \green, \blue, \cyan, \yellow, \orange, \magenta, \white, \fore and \back set the corresponding colours in TeX mode.

## 6.9 Curve Attributes

C H N C R V

CHNCRV defines attributes that will be automatically changed by CURVE after a certain number of calls to the routine CURVE.

 The call is: CALL CHNCRV (CATT) level 1, 2, 3 or: void chncrv (const char *catt);

 CATT = 'NONE' means that CURVE changes no attributes. = 'COLOR' means that colours will be changed. = 'LINE' means that line styles will be changed. = 'BOTH' means that colours and line styles will be changed. Default: CATT = 'NONE'.

• The sequence of colours is WHITE/BLACK, RED, GREEN, YELLOW, BLUE, ORANGE, CYAN and MAGENTA.
• The sequence of line styles is SOLID, DOT, DASH, CHNDSH, CHNDOT, DASHM, DOTL and DASHL.
• The symbol number is always changed. It will be incremented by 1 starting with the current symbol defined by MARKER.

The following three routines are useful when automatic attribute setting is selected and the routine CURVE is called several times to plot a single curve.

INCCRV defines the number of calls after which CURVE will automatically change attributes.

 The call is: CALL INCCRV (NCRV) level 1, 2, 3 or: void inccrv (int ncrv);

 NCRV is the number of curves that will be plotted with identical attributes. Default: NCRV = 1

CHNATT is an alternative routine to INCCRV. It is useful when the number of curves plotted with identical attributes varies. CHNATT defines new attributes that will be used by CURVE during the next call.

 The call is: CALL CHNATT level 1, 2, 3 or: void chnatt (void);

• CHNATT changes only attributes specified with CHNCRV.
• Attributes cannot be skipped by calling CHNATT several times; the order of the attribute cycles must be changed.
R E S A T T

In general, curve attributes will be repeated after 8 changes. With the routine RESATT, the attributes can be reset earlier.

 The call is: CALL RESATT level 1, 2, 3 or: void resatt (void);

INCMRK selects line or symbol mode for CURVE.

 The call is: CALL INCMRK (NMRK) level 1, 2, 3 or: void incmrk (int nmrk);

 NMRK = - n means that CURVE plots only symbols. Every n-th point will be marked by a symbol. NMRK = 0 means that CURVE connects points with lines. NMRK = n means that CURVE plots lines and marks every n-th point with a symbol. Default: NMRK = 0

The symbols used to plot points can be selected with the routine MARKER. The symbol number will be incremented by 1 after a certain number of calls to CURVE defined by INCCRV.

 The call is: CALL MARKER (NSYM) level 1, 2, 3 or: void marker (int nsym);

 NSYM is the symbol number between -1 and 21. The value -1 means that the symbol is not plotted in routines such as CURVE and ERRBAR. The symbols are shown in appendix B. Default: NSYM = 0

The routine MRKCLR sets the colour of symbols plotted by CURVE, so that different colours for curves and symbols can be used.

 The call is: CALL MRKCLR (NCLR) level 1, 2, 3 or: void mrkclr (int nclr);

 NCLR is a colour value. If NCLR = -1, the current colour is selected for symbols in curves. Default: NCLR = -1

HSYMBL defines the size of symbols.

 The call is: CALL HSYMBL (NHSYM) level 1, 2, 3 or: void hsymbl (int nhsym);

 NHSYM is the size of symbols in plot coordinates. Default: NHSYM = 35

MYSYMB sets a user-defined symbol.

 The call is: CALL MYSYMB (XRAY, YRAY, N, ISYM, IFLAG) level 1, 2, 3 or: void mysymb (conat float *xray, const float *yray, int n, int isym, int iflag);

 XRAY, YRAY are the X- and Y-coordinates of the symbol in the range -1 and 1. N is the number of coordinates in XRAY and YRAY. ISYM is a non negative number that will be used as symbol number. IFLAG is an Integer that can have the values 0 and 1. If IFLAG = 1, the symbol will be filled.

• The number of points in MYSYMB is limited to 100 for Fortran 77. There is no limitation for the C and Fortran 90 versions of DISLIN.

THKCRV defines the thickness of curves.

 The call is: CALL THKCRV (NTHK) level 1, 2, 3 or: void thkcrv (int nthk);

 NTHK is the thickness of curves in plot coordinates. Default: NTHK = 1

GAPCRV defines a data gap used in the routine CURVE. If the distance between two neightbouring X coordinates is greater than the gap value, CURVE will not connect these data points.

 The call is: CALL GAPCRV (XGAP) level 1, 2, 3 or: void gapcrv (float xgap);

 XGAP is the gap value.

GAPSIZ defines a data gap used in the routine CURVE. This routine is an extension to GAPCRV and can be used for X-, Y- and Z-coordinates.

 The call is: CALL GAPSIZ (XGAP, CAX) level 1, 2, 3 or: void gapsiz (float xgap, const char *cax);

 XGAP is the gap value.
 CAX is a character string that defines the axes. CAX can have the values 'X', 'Y', 'Z', any combination of these values, or the keyword 'RESET'.

The routine NANCRV can be used to enable the checking for undefined values (NaN) in curves. NaN values will be plotted as gaps and their count is reported in the DISLIN protocol.

 The call is: CALL NANCRV (CMODE) level 1, 2, 3 or: void nancrv (const char *cmode);

 CMODE is a character string that can have the values 'ON' and 'OFF'. Default: CMODE = 'OFF'.

POLCRV defines an interpolation method used by CURVE to connect points.

 The call is: CALL POLCRV (CPOL) level 1, 2, 3 or: void polcrv (const char *cpol);

 CPOL is a character string containing the interpolation method. = 'LINEAR' defines linear interpolation. = 'STEP' defines step interpolation. = 'STAIRS' defines step interpolation. = 'BARS' defines bar interpolation. = 'FBARS' defines filled bar interpolation. = 'STEM' defines stem interpolation. = 'SPLINE' defines spline interpolation. = 'PSPLINE' defines parametric spline interpolation. Default: CPOL = 'LINEAR'.

• The width of bars can be set with BARWTH.
• For spline interpolation, the X-coordinates must have different values and be in ascending order. There is no restriction for a parametric spline. The order of spline polynomials and the number of interpolated points can be modified with SPLMOD.
• The interpolation medthods 'LINEAR', 'BARS', 'FBARS' and 'STEM' can also be used for polar scaling.
S P L M O D

SPLMOD defines the order of polynomials and the number of interpolated points used for the interpolation methods 'SPLINE' and 'PSPLINE'.

 The call is: CALL SPLMOD (NGRAD, NPTS) level 1, 2, 3 or: void splmod (int ngrad, int npts);

 NGRAD is the order of the spline polynomials (2 - 10). It affects the number of points accepted by CURVE which is determined by the formula (2 * NGRAD + 1) * N <= 1000. For example, with a cubic spline, up to 142 points can be passed to CURVE. NPTS is the number of points that will be interpolated in the range XRAY(1) to XRAY(N). Default: (3, 200).

BARWTH sets the width of bars plotted by CURVE.

 The call is: CALL BARWTH (XWTH) level 1, 2, 3 or: void barwth (float xwth);

 XWTH defines the bar width. If positive, the absolute value of XWTH * (XRAY(1)-XRAY(2)) is used. If negative, the absolute value of XWTH is used where XWTH is specified in plot coordinates. Default: XWTH = 0.75

• If XWTH is positive and polar scaling is enabled, the absolute value of XWTH * (YRAY(2) - YRAY(1)) defines the width of bars. If XWTH is negative for polar scaling, the absolute value of XWTH is used where XWTH must be specified in degrees.

The routine NOCHEK can be used to suppress the listing of points that lie outside of the axis scaling.

 The call is: CALL NOCHEK level 1, 2, 3 or: void nochek (void);

## 6.10 Vector Fields

S T M M O D

The routine STMMOD modifies the behaviour of streamlines.

 The call is: CALL STMMOD (CMOD, CKEY) level 1, 2, 3 or: void stmmod (const char *cmod, const char *ckey);

 CMOD is a character string that defines a mode. CKEY is a character string that can have the values 'INTEGRATION', 'ARROWS' and 'CLOSED'. The keyword 'INTEGRATION' defines the integration method used for streamlines. For this keyword, CMOD can have the values 'EULER', 'RK2' and 'RK4'. 'RK2' and 'RK4' mean Runke-Kutta integration of second and fourth order. For the keywords 'ARROWS' and 'CLOSED', COPT can have the values 'ON' and 'OFF'. 'ARROWS' enables arrows at streamlines and the keyword 'CLOSED' means that DISLIN tries to detect closed streamlines. A good integration method such as 'RK4' should be used for this mode. Defaults: ('RK2', 'INTEGRATION'), ('OFF', 'ARROWS'), ('OFF', 'CLOSED').

The routine STMOPT defines some streamline options.

 The call is: CALL STMOPT (N, CKEY) level 1, 2, 3 or: void stmopt (int n, const char *ckey);

 N is an integer option. CKEY is a character string containing one of the following keywords: = 'POINTS' defines the number of points after that the calculation of streamlines will be terminated. The default value is 1000 points. = 'ARROW' specifies the form of arrows that can be plotted at streamlines. The default vector number is 1201 (see VECTOR). = 'STREAMS' defines the number of starting points around a seed point that are used for finding new streamlines if automatic streamline generation is enabled for the routine STREAM3D. (N >= 4). The default value is 4 points. = 'HITS' sets the number of minimal hits for the fast LIC algorithm that are required for each image pixel (N >= 1). DISLIN uses by default 1 hit. = 'LICL' sets the filter length for the fast LIC algorithm. The total filter length is: 2 * N + 1. The default value is N = 10. = 'LICM' defines the length of a streamline in points that is used to calculate multiple image pixels in the fast LIC algorithm. The default length is 100 points.

The routine STMVAL defines some floating point options for streamlines.

 The call is: CALL STMVAL (X, CKEY) level 1, 2, 3 or: void stmval (float x, const char *ckey);

 X is a floating point option. CKEY is a character string containing one of the following keywords: = 'STEP' defines the integration step. The size of the integration step is X * (XPMAX - XPMIN), where XPMIN and XPMAX are the minimum and maximum values of the array XPRAY in STREAM or STREAM3D. The default value is: X = 0.01. = 'DISTANCE' sets the distance of streamlines for evenly-spaced streamlines. The distance is calculated as X * (XPMAX - XPMIN). The distance value should be greater than the integration step. Default: X = 0.02. = 'ARROWS' defines the space between arrows plotted at streamlines. The used space between arrows is: X * X-axis length. Default: 0.25. = 'TEST' defines a test value for evenly-spaced streamlines. The calculation of a new streamline is stopped if the distance to any already calculated streamline is lower than X * distance, where distance is the value for the keyword 'DISTANCE'. Default: X = 0.5. = 'CLOSED' sets a distance value for detecting a closed streamline. The calculation of a streamline is terminated if the distance of a new seed point to the starting point is closer than this value. The used distance is X * (XPMAX - XPMIN). Default: X = 0.005. = 'LICSTEP' defines the integration step for streamlines that are calculated in the LIC algorithm used by the routine LICPTS. Default: X = 0.5.

The routine LICMOD modifies the behaviour of the Line Integral Convolution algorithm in the routine LICPTS.

 The call is: CALL LICMOD (CMOD, CKEY) level 1, 2, 3 or: void licmod (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'ON' and 'OFF'. CKEY is a character string that can have the values 'FAST' and 'SCALE'. The keyword 'FAST' enables or disables the fast LIC algorithm where a single streamline is used to calculate multiple image pixels. The image pixels can be scaled with the vector lengths if the keyword 'SCALE' is used with the mode 'ON'. Defaults: ('ON', 'FAST', ('OFF', 'SCALE').

## 6.11 Line Attributes

L I N E S T Y L E S

The routines SOLID, DOT, DASH, CHNDOT, DASHM, DOTL and DASHL define different line styles. They are called without parameters. The routine LINTYP (NTYP) can also be used to set line styles where NTYP is an integer between 0 and 7 and corresponds to the line styles above. The following constants can be used for line styles in C and Fortran 90/95 programs:

    LINE_SOLID      0   LINE_DASHM      4
LINE_DOT        1   LINE_DASHL      5
LINE_DASH       2   LINE_DOTL       6
LINE_CHNDOT     3

The routine MYLINE sets user-defined line styles.

MYLINE defines a global line style.

 The call is: CALL MYLINE (NRAY, N) level 1, 2, 3 or: void myline (const int *nray, int n);

 NRAY is an array of positive integers characterizing the line style. Beginning with pen-down, a pen-dow and pen-up will be done alternately according to the specified lengths in NRAY. The lengths must be given in plot coordinates. N is the number of elements in NRAY.

 Examples: The values of NRAY for the predefined line styles are given below:

              SOLID :        NRAY = {1}
DOT   :        NRAY = {1, 10}
DASH  :        NRAY = {10, 10}
CHNDSH:        NRAY = {30, 15, 10, 15}
CHNDOT:        NRAY = {1, 15, 15, 15}
DASHM :        NRAY = {20, 15}
DOTL  :        NRAY = {1, 20}
DASHL :        NRAY = {30, 20}

L I N C L R

The routine LINCLR defines colour values for the pen-downs in line styles. The colours are ignored for solid lines.

 The call is: CALL LINCLR (NRAY, N) level 1, 2, 3 or: void linclr (const int *nray, int n);

 NRAY is an array of colour values. N is the number of elements in NRAY (N <= 10). The default value N = 0 disables colours for line styles.

The routine LINWID sets the line width.

 The call is: CALL LINWID (NWIDTH) level 1, 2, 3 or: void linwid (int nwidth);

 NWIDTH is the line width in plot coordinates. Default: NWIDTH = 1

• To define smaller line widths than 1 (i.e. for PostScript files), the routine PENWID (XWIDTH) can be used where XWIDTH has the same meaning as NWIDTH.
• DISLIN tries to use hardware features for the line width. This can be disabled with the option HWMODE ('OFF', 'LINE').

The routine LNCAP sets the current line cap parameter.

 The call is: CALL LNCAP (CAP) level 1, 2, 3 or: void lncap (const char *cap);

 CAP is a character string defining the line cap. = 'ROUND' defines rounded caps. = 'CUT' defines square caps. = 'LONG' defines square caps where stroke ends will be continued equal to half the line width. Default: CAP = 'LONG'.

The routine LNJOIN sets the current line join parameter.

 The call is: CALL LNJOIN (CJOIN) level 1, 2, 3 or: void lnjoin (const char *cjoin);

 CJOIN is a character string containing the line join. = 'SHARP' defines sharp corners between path segments. = 'TRUNC' defines truncated corners between path segments. Default: CJOIN = 'TRUNC'.

The routine LNMLT sets the current miter limit parameter. This routine can be useful if the line join is set to 'SHARP'.

 The call is: CALL LNMLT (XFC) level 1, 2, 3 or: void lnmlt (float xfc);

 XFC is a floating point number where XFC * line width will be used as the miter limit. The miter length is the distance between the inner and outside edge of a path corner. Default: XFC = 2.

The routine LINMOD enables anti-aliased lines in image formats such as PNG, BMP and TIFF. True colour mode is required for anti-aliased lines (see IMGFMT).

 The call is: CALL LINMOD (CMOD, CKEY) level 1, 2, 3 or: void linmod (const char *cmod, const char *ckey);

 CMOD is a character string that can contain the modes 'ON' and 'OFF'. CKEY is a character string that can have the value 'SMOOTH'. Default: ('OFF', 'SMOOTH')

S H D P A T

SHDPAT selects shading patterns used by routines such as SHDCRV and AREAF.

 The call is: CALL SHDPAT (IPAT) level 1, 2, 3 or: void shdpat (long ipat);

 IPAT is an integer between 0 and 17. The predefined patterns are shown in appendix B. The following constants can be used for shading patterns in C and Fortran 90/95 programs:  SHADING_EMPTY 0 SHADING_GRID_BOLD 14 SHADING_LINES 1 SHADING_FILLED 16 SHADING_LINES_BOLD 4 SHADING_DOTS 17 SHADING_GRID 10 

MYPAT defines a global shading pattern.

 The call is: CALL MYPAT (IANGLE, ITYPE, IDENS, ICROSS) level 1, 2, 3 or: void mypat (int iangle, int itype, int idens, int icross);

 IANGLE is the angle of shading lines (0 - 179). ITYPE defines the type of shading lines: = 0 no shading lines. = 1 equidistant lines. = 2 double shading lines. = 3 triple shading lines. = 4 thick shading lines. = 5 dotted lines. = 6 dashed lines. = 7 dashed-dotted lines. IDENS defines the distance between shading lines (0: small distance, 9: big distance). ICROSS indicates whether shading lines are hatched (0: not hatched, 1: hatched).

 Examples: The following calls to MYPAT show the predefined shading patterns used by SHDPAT:

  IPAT = 0:   CALL MYPAT (  0, 0, 0, 0)
IPAT = 1:   CALL MYPAT ( 45, 1, 5, 0)
IPAT = 2:   CALL MYPAT (150, 4, 5, 0)
IPAT = 3:   CALL MYPAT (135, 1, 5, 0)
IPAT = 4:   CALL MYPAT ( 45, 4, 5, 0)
IPAT = 5:   CALL MYPAT ( 45, 1, 5, 1)
IPAT = 6:   CALL MYPAT (135, 2, 1, 0)
IPAT = 7:   CALL MYPAT ( 45, 4, 5, 1)
IPAT = 8:   CALL MYPAT ( 30, 1, 4, 0)
IPAT = 9:   CALL MYPAT ( 45, 2, 1, 1)
IPAT = 10:  CALL MYPAT (  0, 1, 5, 1)
IPAT = 11:  CALL MYPAT ( 45, 3, 1, 0)
IPAT = 12:  CALL MYPAT ( 70, 4, 7, 0)
IPAT = 13:  CALL MYPAT ( 45, 3, 1, 1)
IPAT = 14:  CALL MYPAT (  0, 4, 5, 1)
IPAT = 15:  CALL MYPAT ( 45, 2, 1, 0)
IPAT = 16:  CALL MYPAT (  0, 1, 0, 0)
IPAT = 17:  CALL MYPAT (  0, 5, 5, 0)

N O A R L N

With the routine NOARLN the outlines of shaded regions can be suppressed.

 The call is: CALL NOARLN level 1, 2, 3 or: void noarln (void);

The routine HWMODE enables or disables hardware features for the line width and for shading patterns.

 The call is: CALL HWMODE (CMOD, CKEY) level 1, 2, 3 or: void hwmode (const char *cmod, const char *ckey);

 CMOD is a character string that can have the values 'ON' and 'OFF'. CKEY is a character string that can have the values 'LINE' and 'SHADING'. Default: ('ON', 'LINE'), ('ON', 'SHADING').

The routine SHDFAC sets a scaling factor for the distance of scan lines for software shading.

 The call is: CALL SHDFAC (XFAC) level 1, 2, 3 or: void shdfac (float xfac);

 XFAC is the scaling factor (> 0). Default: XFAC = 1.0

## 6.13 Attribute Cycles

The attributes line style, colour and shading pattern can be changed automatically by routines such as CURVE, SHDCRV, BARS and PIEGRF according to a predefined cycle.

The cycles are:
 Line styles: SOLID, DOT, DASH, CHNDSH, CHNDOT, DASHM, DOTL and DASHL. Colours: WHITE/BLACK, RED, GREEN, YELLOW, BLUE, ORANGE, CYAN and MAGENTA. Shading: Pattern numbers from 0 to 17.

The following subroutines allow the redefining of cycles.

LINCYC changes the line style cycle.

 The call is: CALL LINCYC (INDEX, ITYP) level 1, 2, 3 or: void lincyc (int index, int ityp);

 INDEX is an index between 1 and 30. ITYP is an integer between 0 and 7 containing the line style (0 = SOLID, 1 = DOT, 2 = DASH, 3 = CHNDSH, 4 = CHNDOT, 5 = DASHM, 6 = DOTL, 7 = DASHL).

CLRCYC changes the colour cycle.

 The call is: CALL CLRCYC (INDEX, ICLR) level 1, 2, 3 or: void clrcyc (int index, int iclr);

 INDEX is an index between 1 and 30. ICLR is a colour value (see SETCLR).

PATCYC changes the shading pattern cycle.

 The call is: CALL PATCYC (INDEX, IPAT) level 1, 2, 3 or: void patcyc (int index, long ipat);

 INDEX is an index between 1 and 30. IPAT is a pattern number between 0 and 17 or is determined by the formula IANGLE * 1000 + ITYPE * 100 + IDENS * 10 + ICROSS with the parameters described in MYPAT.

## 6.14 Base Transformations

The following subroutines create a transformation matrix that affects plot vectors contained within page borders. Vectors may be scaled, shifted and rotated and the transformations can be combined in any order.

TRFSHF affects the shifting of plot vectors.

 The call is: CALL TRFSHF (NXSHFT, NYSHFT) level 1, 2, 3 or: void trfshf (int nxshft, int nyshft);

 NXSHFT, NYSHFT are plot coordinates that define the magnitude of shifting in the X- and Y-direction.

TRFSCL affects the scaling of plot vectors.

 The call is: CALL TRFSCL (XSCL, YSCL) level 1, 2, 3 or: void trfscl (float xscl, float yscl);

 XSCL, YSCL are scaling factors for the X- and Y-direction.

TRFROT affects the rotation of plot vectors around a point.

 The call is: CALL TRFROT (XANG, NX, NY) level 1, 2, 3 or: void trfrot (float xang, int nx, int ny);

 XANG is the rotation angle measured in degrees in a counter-clockwise direction. NX, NY are the plot coordinates of the rotation point.

TRFRES resets base transformations.

 The call is: CALL TRFRES level 1, 2, 3 or: void trfres (void);

## 6.15 Shielded Regions

This section describes how to protect regions from being overwritten. Shielded regions can be defined automatically by DISLIN or explicitly by the user. Shielded regions are stored in a buffer which can then be manipulated by the user.

SHIELD selects shielded regions which are set automatically by DISLIN.

 The call is: CALL SHIELD (CAREA, CMODE) level 1, 2, 3 or: void shield (const char *carea, const char *cmode);

 CAREA is a character string defining the regions: = 'MESSAG' is used for text and numbers plotted by MESSAG and NUMBER. = 'SYMBOL' will shield symbols. = 'BARS' will shield bars plotted by BARS. = 'PIE' will shield pie segments plotted by PIEGRF. = 'LEGEND' will protect legends. All legend attributes should be set before calling CURVE because the shielded region of a legend is defined by CURVE. If there is no legend position defined with LEGPOS, CURVE assumes that the legend lies in the upper right corner of the axis system. CMODE is a character string defining a status: = 'ON' means that the regions defined above will be written to the shielding buffer and are protected. = 'OFF' means that regions will not be written to the shielding buffer. Regions that are still stored in the buffer will be shielded. = 'DELETE' removes regions from the shielding buffer. = 'RESET' is a combination of 'OFF' and 'DELETE'. Regions are removed from and will not be written to the shielding buffer. To save computing time, this command should always be used when shielding is no longer needed. = 'NOVIS' The shielding of regions held in the shielding buffer is disabled. This is not valid for regions newly written to the buffer. = 'VIS' Disabled regions will be protected. This is the default value for regions newly written to the buffer.

The calls are:

     CALL SHLREC  (NX, NY, NW, NH)          for rectangles
CALL SHLRCT  (NX, NY, NW, NH, THETA)   for rotated rectangles
CALL SHLCIR  (NX, NY, NR)              for circles
CALL SHLELL  (NX, NY, NA, NB, THETA)   for rotated ellipses
CALL SHLPIE  (NX, NY, NR, ALPHA, BETA) for pie segments
CALL SHLPOL  (NXRAY, NYRAY, N)         for polygons.

 NX, NY are plot coordinates of the upper left corner or the centre point. NW, NH are the width and height of rectangles. NR, NA, NB are radii in plot coordinates. THETA is a rotation angle measured in degrees in a counter-clockwise direction. ALPHA, BETA are starting and ending angles for pie segments measured in degrees in a counter-clockwise direction. NXRAY, NYRAY are arrays of the dimension N containing the corner points of a polygon.

The index of shielded regions in the buffer can be requested with SHLIND. It returns the index of the region last written to the buffer.

 The call is: CALL SHLIND (ID) level 1, 2, 3 or: int shlind (void);

 ID is the returned index.

SHLDEL removes entries from the shielding buffer.

 The call is: CALL SHLDEL (ID) level 1, 2, 3 or: void shldel (int id);

 ID is the index of a shielded region. If ID is 0, all regions defined by the user will be deleted.

SHLRES deletes regions last written to the shielding buffer.

 The call is: CALL SHLRES (N) level 1, 2, 3 or: void shlres (int n);

 N is the number of regions to delete.

SHLVIS disables or enables shielded regions. Disabled regions are no longer protected but are still held in the shielding buffer.

 The call is: CALL SHLVIS (ID, CMODE) level 1, 2, 3 or: void shlvis (int id, const char *cmode);

 ID is the index of a shielded region. If ID is 0, all entries are disabled or enabled. CMODE = 'ON' enables shielded regions. This is the default value for regions newly written to the buffer. CMODE = 'OFF' disables shielded regions.

• A frame is plotted around regions defined by the user. The thickness of frames can be set with FRAME. Regions defined automatically by DISLIN are not enclosed by a frame but frames plotted by MESSAG after using FRMESS and shielded regions defined by MESSAG are identical.
• Shielded regions can overlap each other.
• The statement CALL RESET ('SHIELD') resets shielding. All regions defined by DISLIN and the user are removed from the shielding buffer and no new regions will be written to the buffer.
• The number of shielded regions is limited to the size of the shielding buffer which is set to 1000 words. The number of words used by regions are: SHLREC = 6, SHLRCT = 7, SHLCIR = 5, SHLELL = 7, SHLPIE = 7 and SHLPOL = 2*N+3.
• Shielding of regions is computer intensive. Therefore, shielding should be used very carefully and shielded regions should be deleted from the buffer when no longer needed.
• Base transformations do not affect the position of shielded regions.
• SHLPOL can be used between the routines GRFINI and GRFFIN. The shielded region will be projected into 3-D space. This is not valid for other shielded regions.

Next | Previous | Contents