Chapter 2: Basic Concepts and Conventions 2.1 Page Format In DISLIN, the graphics are limited to a rectangular area called the page. All lines outside of or crossing page bor- ders will be suppressed. The size of the page is determined by the routines SETPAG and PAGE. SETPAG corresponds to a predefined page while PAGE defines a global page setting. In default mode, there are 100 points per centimetre and the point (0,0) is located in the upper left corner (Figure 1): (0,0) +----------------------------------+ | | | | | | | DIN A 4 Landscape | | | | | | | +----------------------------------+ (2969,2099) Figure 1 : Default Page (DA4L) 2.2 File Format DISLIN can create several types of plot files. Device-inde- pendent plot files or metafiles can be coded in ASCII or bi- nary format. Device-dependent plot files are available for several printers and plotters. The file formats are: a) a CGM metafile according to the ANSI standard Plot vectors are coded in binary format as non negative integers with 200 points per cm. Because of binary coding, CGM metafiles are smaller than other plot files. b) a GKSLIN metafile Plot vectors are stored as floating point numbers be- tween 0 and 1 in ASCII format. These files are easily transferable from one computer to another. c) a PostScript file PostScript is an international standard language that has been developed for laser printers in the last few years. Some of the PostScript features such as hardware fonts and shading can be used within DISLIN. PostScript is a trademark of Adobe Systems, Inc. d) an EPS file the Encapsulated PostScript file format is similar to the PostScript format. It is useful for importing Post- Script files into other applications. e) a PDF file The Portable Document Format is the de facto standard for the electronic exchange of documents. Compressed and non compressed PDF files can be created by DISLIN. Post- Script fonts can be used for PDF files in the same way as for PostScript files. f) a HPGL file Plot vectors and colours are coded in a language re- cognized by Hewlett-Packard plotters. g) a WMF file The Windows metafile format is also supported by DISLIN. Plot vectors a converted to 1/1440 inch. WMF files can contain hardware fonts defined with the DISLIN routine WINFNT. h) a SVG file Scalable Vector Graphics (SVG) is a language for de- scribing graphics in XML. SVG files can be displayed directly by some browsers if a corresponding plug-in is installed. The most of the standard PostScript fonts are supported by the DISLIN SVG files. i) a GIF file The Graphics Interchange Format (c) is the Copyright property of Compuserve Incorporated. j) a TIFF file The raster format TIFF can be used for storing graphical output. DISLIN can create 8 bit palette and true colour TIFF files. k) a PNG file The Portable Network Graphics format is a compressed and therefore very small raster format for storing graphical output. PNG files can be displayed directly by several Internet browsers. The compression of PNG files is done in DISLIN with the zlib compression routines written by Jean-loup Gailly and Mark Adler. DISLIN supports 8 bit palette and true colour PNG files. l) a PPM file The portable pixmap format is a well-known colour image file format in the UNIX world. There are many tools for converting PPM files into other image formats. The pixel values are stored in DISLIN PPM files in plain bytes as RGB values. m) a BMP file The Windows Bitmap format can be used for storing gra- phical output. DISLIN can create uncompressed 8 and 24 bit BMP files. n) an IMAGE file This easy raster format is used by DISLIN to store images. The files contain an ASCII header of 80 bytes and the following image data. o) a Tektronix, VGA and X Window emulation Data can be displayed on X Window terminals, VGA screens and graphic terminals with a Tektronix emulation 4010/ 4014. File formats can be set with the routine METAFL. The file- name consists of the keyword 'DISLIN' and an extension that depends on the file format. An alternate filename can be chosen by calling the routine SETFIL. Both subroutines must be called before the initialization routine DISINI. 2.3 Level Structure of DISLIN Most routines in DISLIN can be called anywhere during pro- gram execution. Certain routines, however, use parameters from other routines and must be called in a fixed order. DISLIN uses a level structure to control the order in which routines are called. The levels are: 0 before initialization or after termination 1 after initialization or a call to ENDGRF 2 after a call to GRAF, GRAFP or GRAFMP 3 after a call to GRAF3 or GRAF3D. Generally, programs should have the following structure: (1) setting of page format, file format and filename (2) initialization (3) setting of plot parameters (4) plotting of the axis system (5) plotting the title (6) plotting data points (7) termination. 2.4 Conventions The following conventions appear throughout this manual for the description of routine calls: - INTEGER variables begin with the character N or I - CHARACTER variables begin with the character C - other variables are REAL - arrays end with the keyword 'RAY'. Notes: - CHARACTER variables may be specified in upper or lower case and may be shortened to four characters. - DISLIN stores parameters in common blocks whose names begin with the character 'C'. Common block names in user programs should not begin with the character 'C' to avoid possible name equalities. - The Fortran logical units 15, 16 and 17 are reserved by DISLIN for plot and parameter files. - Two types of coordinates are continually referred to throughout the manual: plot coordinates which corres- pond to the page and always have 100 points per cm, and user coordinates which correspond to the scaling of the axis system. 2.5 Error Messages When a DISLIN subroutine or function is called with an ille- gal parameter or not according to the level structure, DIS- LIN writes a warning to the screen. The call of the routine will be ignored and program execution resumed. Points lying outside of the axis system will also be listed on the screen. Error messages can be suppressed or written to a file with the routines ERRMOD and ERRDEV. 2.6 Programming in C/C++ There are two different libraries in DISLIN: one is develo- ped for Fortran programmers and written in the language For- tran, the other is written in the programming language C and useful for C programmers. Though it is possible to call C routines in Fortran programs and Fortran subroutines in C programs, it is easier to use the corresponding library. Especially, the passing of strings can be complicate in mixed language programming. The number and meaning of parameters passed to DISLIN rou- tines are identical for both libraries. The Fortran version uses INTEGER, REAL and CHARACTER variables while the C li- brary uses int, float and char variables. A detailed de- scription of the syntax of C routines is given by the utili- ty program DISHLP or can be found in the header file 'dislin.h' which must be included in all C programs. Here is a short example for a DISLIN C program: #include #include "dislin.h" main() { disini (); messag ("This is a test", 100, 100); disfin (); } An example for a DISLIN C++ programm is: #include namespace dislin { #include "dislin.h" } main() { dislin::disini (); dislin::messag ("This is a test", 100, 100); dislin::disfin (); } 2.7 Programming in Fortran 90/95 Several DISLIN distributions contain native libraries for the programming language Fortran 90/95 where the source code of DISLIN is written in Fortran 90. Since the passing of parameters to subroutines and functions can be different in Fortran 90 and Fortran 77, you should not link Fortran 77 programs with Fortran 90 libraries and vice versa. Notes: - All program units in Fortran 90 programs that contain calls to DISLIN routines should include the statement 'USE DISLIN'. The module 'DISLIN' contains interfaces for all DISLIN routines and enables the compiler to check the number and type of parameters passed to DISLIN routines. - Since version 9.1 of DISLIN, the array declarations in the DISLIN module file are changed from assumed- shape arrays to explicit-shape arrays for native For- tran 90 libraries. All DISLIN Fortran 90 libraries (native of wrapper) use now the same interfaces. A missing 'USE DISLIN' statement for a native Fortran 90 library of DISLIN should no longer cause a general protection fault. For example: PROGRAM TEST USE DISLIN CALL DISINI () CALL MESSAG ('This is a test', 100, 100) CALL DISFIN () END PROGRAM TEST 2.8 Linking Programs The linking of programs with the graphics library depends upon the operating system of the computer. Therefore, DISLIN offers a system-independent link procedure that can be used on all computers in the same way. Command: DLINK [option] main option is an optional parameter containing a minus sign and a character. The following options can be used on all computers: -c for compiling programs before linking. -cpp for compiling a C++ programs before linking. -r for running programs after linking. -a for compiling, linking and running programs. -r8 for using the double precision libraries of DISLIN. main is the name of the main program. Notes: - If DLINK is called without parameters, the de- scription of the program will be printed on the screen. There may be other local features avai- lable depending upon the operating system used. - Linking of C programs should be done with the procedure CLINK. - The most DISLIN distributions contain libraries for single precision (32 bit) and double preci- sion (64 bit) floating point parameters. The double precision libraries can be identi- fied by the term '_d' in the library filename. 2.9 Utility Programs The following programs are useful for working with DISLIN. They send plot files to devices and print the description of routines on the screen. D I S H L P DISHLP prints the description of a DISLIN routine on the screen. Command: DISHLP routine [options] routine is the name of a DISLIN routine or a question mark. For a question mark, all routine names will be listed. An empty input terminates the program. options is an optional field of keywords (see DISHLP). D I S M A N DISMAN prints an ASCII version of the DISLIN manual on the screen. Command: DISMAN [options] options is an optional field of keywords (see DISMAN). D I S P R V DISPRV checks the use of DISLIN routines in a Fortran pro- gram. The type and dimension of parameters and the overlap- ping of common block and routine names with internal DISLIN declarations will be checked. Command: DISPRV filename[.FOR] [options] filename describes the file containing the Fortran code. options is an optional field of keywords (see DISPRV). D I S D R V DISDRV sends a plot file to a device. CGM and GKSLIN files can be used for all devices while device-dependent plot files can only be sent to corresponding devices. Command: DISDRV filename[.MET] [device] [options] filename is the name of a plot file. device is the name of a device. CONS refers to the graphics screen and XWIN to a smaller graphics window. options is an optional field of keywords (see DISDRV). D I S I M G DISIMG displays an image file on the screen, or converts it to PostScript and TIFF. Command: DISIMG filename[.IMG] [device] [options] filename is the name of the image file. The file must be created with the routine RIMAGE. device is the device name. options is an optional field of keywords (see DISIMG). D I S M O V DISMOV displays a sequence of image files. Command: DISMOV filename[.MOV] [device] [options] filename is the name of a data file where the filenames of the images are stored (1 line for each file- name). The images must be created with the rou- tine RIMAGE. device is the device name. options is an optional field of keywords (see DISMOV). D I S T I F DISTIF displays a TIFF file created by DISLIN on the screen, or converts it to PostScript and an image format. Command: DISTIF filename[.TIF] [device] [options] filename is the name of the TIFF file. The file must be created with the routine RTIFF. device is the device name. options is an optional field of keywords (see DISTIF). D I S G I F DISGIF displays a GIF file, or converts it to another file format. Command: DISTIF filename[.GIF] [device] [options] filename is the name of the GIF file. device is the device name. options is an optional field of keywords (see DISGIF). D I S A P S DISAPS converts an ASCII file to a PostScript file. Several page layouts can be defined. Command: DISAPS filename [output] [options] filename is the name of the ASCII file. output is the name of the output file. By default, the name of the input file and the extension ps will be used. options is an optional field of keywords (see DISAPS). Note: If a utility program is called without parame- ters, a description of possible parameters will be printed on the screen. DISDRV, for example, lists the local output devices available. D I S G C L DISGCL is an interpreter for DISLIN. All DISLIN statements can be written to a script file and then be executed with DISGCL, or can be entered in an interactive mode. High-level language elements such variables, operators, expressions, array operations, loops and user-defined functions can be used within DISGCL. Command: DISGCL [filename[.gcl]] [args] [options] filename is the name of a DISGCL script file. The exten- sion '.gcl' is optional. args are optional arguments that can be passed to DISGCL scripts (see DISGCL). options is an optional field of keywords separated by blanks (see DISGCL). 2.10 WWW Homepage DISLIN is available from the Web sites http://www.dislin.de http://www.mps.mpg.de/dislin 2.11 Reporting Bugs DISLIN is well tested by many users and should be very bug free. However, no software is perfect and every change can cause new bugs. If you have any problems with DISLIN, con- tact the author: Helmut Michels Max-Planck-Institut fuer Sonnensystemforschung 37077 Goettingen, Justus-von-Liebig-Weg 3, Germany E-Mail: michels@mps.mpg.de 2.12 License Information DISLIN is free for non-commercial use for the operating DISLIN is free for non-commercial use. Licenses for commer- cial use are available from the site http://www.dislin.de. Commercial use means selling of programs linked with DISLIN or using DISLIN in an environment related to business. This manual of the data plotting software DISLIN can be copied and distributed freely.