@(#)fintf.doc 10.1 (OAA-ASTRONET) 8/7/95 19:23:09 HEADER : fintf.doc - Vers 3.6.001 - Sep 1993, L. Fini A G L Reference Manual Version 3.61 FORTRAN Language Binding ======================== Luca Fini Dec 1991 Revised: Sep 1993 AGL 3.61 Distribution notice =================== The Astronet Graphic library has been designed and implemented under the coordination of the Astronet Working Group "Graphics and Image Displays". The software is officially supported by Astronet and is distributed by: Astronet Documentation Facility (ADOC) Osservatorio Astronomico di Trieste C.P. Succ. TS 5 Via G.B.Tiepolo, 11 34131 Trieste, Italia Tel: +39 40 319911 Fax: +39 40 309418 e-mail: adoc@astrts.astro.it The distribution release may also be obtained by anonymous ftp at: sisifo.arcetri.astro.it:pub/agl or via e-mail, from the author: Luca Fini Osservatorio Astrofisico di Arcetri L.go E. Fermi 5, 50125 Firenze, Italia Tel: +39 55 27521 Fax: +39 55 220039 e-mail: lfini@astrfi.astro.it Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 1 CONTENTS ======== Note: FORTRAN names of routines are in parentheses. 0. Introduction .................................... INTRO 3 AGL Programming Interface ........................... 3 Version History ..................................... 4 Acknowledgements .................................... 7 AGL and the operating environment ................... 8 Structuring an AGL application ..................... 10 C Programming Hints ................................ 10 FORTRAN Programming Hints .......................... 10 1. Functions which affect the status .............. STATUS 1 AG_CDEF (AGCDEF) Define clipping area AG_CLS (AGCLS) Terminate orderly AG_ISET (AGISET) Set integer User parameters AG_RSET (AGRSET) Set real User parameters AG_SSET (AGSSET) Set status control AG_VDEF (AGVDEF) Define viewport AG_VKIL (AGVKIL) Kill current viewport AG_VSEL (AGVSEL) Select viewport AG_WDEF (AGWDEF) Define user window 2. Functions to perform graphic output ............. GRAPH 1 AG_FILL (AGFILL) Fill a polygon with a pattern AG_GINT (AGGINT) Draw with interpolation AG_GPLG (AGGPLG) Draw polygon AG_GPLL (AGGPLL) Draw polyline AG_GPLM (AGGPLM) Draw polymarker AG_GTXT (AGGTXT) Draw text AG_VERS (AGVERS) Erase current viewport AG_VUPD (AGVUPD) Force graphic update 3. Functions to get information or data ............. INFO 1 AG_IDN (AGIDN) Version identification AG_IGET (AGIGET) Get integer information AG_RGET (AGRGET) Get real information AG_TGET (AGTGET) Get text dimensions AG_VLOC (AGVLOC) Get locator position AG_VLOS (AGVLOS) Get locator position Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 2 4. Functions for metafile manipulation .............. META 1 AG_MCLS (AGMCLS) Close metafile AG_MOPN (AGMOPN) Open metafile AG_MRDW (AGMRDW) Redraw a metafile AG_MRES (AGMRES) Resume metafile recording AG_MSUS (AGMSUS) Suspend metafile recording 5. Miscellaneous .................................... MISC 1 AG_DRIV (AGDRIV) Print driver configuration AG_ESC (AGESC) Device escape AG_GERR (AGGERR) Generate error condition AG_IVAL (n.a.) String parsing & Integer conversion AG_MAGN (AGMAGN) Magnify coordinate vectors AG_RVAL (n.a.) String Parsing & Real conversion AG_SCAN (n.a.) Parse a string AG_SVAL (n.a.) Get string argument AG_TRNS (n.a.) Defines a user specified coordinate AG_TROT (AGTROT) Offset and rotate coordinate vectors AG_TSET (AGTSET) Preset offset and rotation values AG_VN2U (AGVN2U) Normalized to user coord.conversion AG_VU2N (AGVU2N) User to normalized coord.conversion transformation. 6. High level utilities ............................. HIGH 1 AG_AXES (AGAXES) Draw a frame with axes AG_AXIS (AGAXIS) Draw a single axis AG_HIST (AGHIST) Plot Histograms AG_NLIN (AGNLIN) Draw non linear coordinate grids and set up corresponding transformations AG_ORAX (AGORAX) Draw a single axis with arbitrary orientation and scales. 7. Driver support ................................... DRIV 1 AG_DMSG (n.a.) Output debug message AG_GETN (n.a.) File scanning with line count AG_GETS (n.a.) File scanning AG_NEWN (n.a.) File name generator AG_STDO (n.a.) Open file searching in standard directories 8. Error codes ..................................... ERROR 1 Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 3 INTRODUCTION AGL Programming Interface The AGL Programming interface is the set of routines or function calls which the application programmer will use in developing applications. It comes in two flavors for C programmers and for FORTRAN programmers so that a more comfortable environment will be found independently on the language of choice. For this reason this manual also comes in two flavors: a C version, with C language oriented specification of calling sequences, and an analogous FORTRAN version. C and FORTRAN interfaces only differ for entry points names (the FORTRAN entry point name can be derived from the C name by stripping off the underscore character after the prefix AG); entry points arguments will be exactly the same, in the same order, with the obvious correspondence of types (i.e.: int arguments correspond to INTEGER, float to REAL and char to CHARACTER). Note that a few entry points (those devised to be used for special purposes, such as sup- port for device drivers) are only accessible through the C interface. Version History 3.0 First portable version. 3.1 Improved character generation. High quality and Greek fonts have been introduced. An escape mechanism has been introduced to allow "in string" control of character drawing parameters. 3.2 Improved metafile manipulation. Support for the two metafile generation modes HARD and SOFT has been introduced. Support for the generation of polyline representation of character strings has been introduced (functions: AG_TXTI and AG_TXTV). 3.3 Support for line styles has been moved to the AGL library (it was formerly provided optionally by device drivers). This allows to support different line styles on any AGL supported device and simplifies the structure of device drivers. Now functions AG_IGET and AG_RGET return the number of Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 4 values passed back, and must be declared as int instead of void. When calling from FORTRAN they may also be used as INTEGER FUNCTIONs. The new function AG_GETS has been provided. It has functionality similar to the standard fgets(), but discards blank lines, comments and so on. It is intended for use in device drivers. The new function AG_DRIV prints out a list of drivers included into configuration. The ordering of chapters in this manual has been modified by adding chapter five and moving there the AGL provided routines which are to be used as utilities in driver development. Chapter 4 still contain miscellaneous routines. The structure of testing programs has been modified. Now a single test program (ip) is provided (plus a fortran test program just to test the link procedure). The program ip as documented in the related manual (ip.doc) is an interactive plotting package which accepts command input either from keyboard or from a command file and performs the required task. It is an improved version of the program intplot provided with previous versions of AGL. Together with ip a set of command files (*.m) are provided for testing various functions of AGL. 3.4 A generalized driver to be used for raster devices has been added. It requires a device specific rasterizing program to draw plots. Some improvements to the symbol generator accessed through the function AG_GPLM have been added, including the availa- bility of filled symbols. A new utility program has been added which allows to create Tektronix compatible windows on VMS/GPX workstation. Such windows can then be addressed as AGL devices. 3.5 Release 3.5 update was devised in order to solve some pro- blems with the character and symbol generators. Characters and symbols had an unpleasant lopsided aspect on screen devices. This update required some modifications to the user interface in the sense that character dimension setting parameters may have slightly different effect with respect to version 3.4. A modification of the device driver definition was also necessary, but old drivers developed according to previous version definition will still work. The routine AG_VLOS (locator read with string return) has been added to the user interface. The following modifications introduced with version 3.5 have no effect on user interface. Version 3.5 source code has been reviewed completely in Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 5 order to achieve better conformance to the proposed ANSI standard for the C language. Metafile I/O has been improved, and an escape option has been introduced. This will allow in the future to extend the metafile support while maintaining compatibility with older formats. 3.51 Minor update release. Containing some bug fixes and more device drivers, most notably the support for Tektronix 41xx terminals and for the Versatec raster printer. A high level routine for plotting histograms has been added (AG_HIST). The organization of documentation files has been revised in order to make it easier to get required pieces of informa- tion. The Reference manual (file: cintf.doc) has been reas- sembled and a new version suited for the FORTRAN programmer has been added (file: fintf.doc). The device specific infor- mation has been gathered into a single file (devices.doc). NOTE: A bug has been discovered into the routine AG_RVAL since version 3.50; the value return array was incorrectly declared as "double": a violation of the standard type float for floating point arguments used throughout AGL. It has been corrected to float starting with version 3.51. This MAY AFFECT some application programs! 3.52 Minor update release. Some bugs have been fixed (see into file history.doc). The support for bold text when drawing strings has been added (Note: this is an optional driver feature, so it will be supported only on devices which allow line width control). 3.53 Minor updated version not officially released. 3.6 Release 3.6 main features are: 1) A thorough restructuring of source code which allows separate compilation of modules so that troubles with some compilers due to the length of the main module could be solved. 2) The library has been profiled to identify and cure cpu consumung bottlenecks, thus increasing the speed by about 36% (measured on a Sun Sparcstation). 3) The inclusion of many new capabilities: - Consistent support of named colors. - Support for background color control. - A set of new fonts have been added and many new char- Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 6 cters within existing fonts. - The special character drawing sequences have been redesigned and greatly improved: support for blocks, TeX like symbols, newline within strings and more features has been added. - The symbol drawing routine AG_GPLM now accepts also an ASCII value as marker identifier (besides the usual 20 symbols previously available). - A new axis routine (AG_AXIS) which draws a single axis in arbitrary position to complement the previous frame generation routine AG_AXES. - A generic axis routine (AG_ORAX) which draws axes with arbitrary angle. - Support for user provided coordinate transformation functions (AG_TRNS, AG_ISET, AG_RSET). - Provision for the plotting of data frames with a set of spherical projections (AG_NLIN). - A routine which draws lines interpolating between points (AG_GINT). - A polygon drawing routine: AG_GPLG. - A polygon filling routine: AG_FILL. - Coordinate manupulation utilities: offset and rota- tion (AG_TSET, AG_TROT) and magnification (AG_MAGN). 4) A "direct" X11 driver has been added. It uses direct calls to the Xlib to avoid interprocess communication overhead. 5) A customization symbol has been included in the makefile which allows the generation of a "tailored" version of the library without support for metafile. This may be used for special applications where high speed and smaller executables are a must (the last effect is due to the fact that the metafile redrawing routine references all the other AGL entry points, which are thus loaded by the linker even if they aren't called by the user application). 3.61 Minor updated version with a number of bug fixes and some enhancements. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 7 ACKNOWLEDGEMENTS AGL is the result of the cooperation of various people at many levels. The original design is due to a number of people both par- ticipating to the Astronet working Group on Graphics and provid- ing useful comments on a personal basis. Among them: G.A De Biase, A. Ficarra, M. Nanni, F. Pasian, M. Pucillo, P. Santin. The first implementations at Arcetri are due to the coopera- tion of people both in the detailed design phase and in coding and debugging: G. Andreoni, L. Hunt, P. Fontanelli. More people contributed to following versions, and most notably to the portable one (AGL 3.xx), volunteering as test people, or providing drivers or ports to various operating envi- ronments. Among them: R. Baglioni, A. Blom, F. Pasian, M. Pucil- lo, P. Santin, A. Silvestri, F. Tribioli. Improvements and error checking is also due to reports and criticism by users, such as: M.Cameron, R.Coluzzi, R.David, B.De- bray, H.Held, E.Huizinga, C.Levin, B.Pettersson, I.Porceddu, H.Schwengeler, R.van Hees, G.Sedmak. A special mention must be devoted to the ESO Image Process- ing Group who adopted the AGL software as basic support for graphics within Midas and thus acted both as main test site and as principal external supporters of the AGL project. Among them a special thank to R. Warmels, who directly suffered for bugs, inadequacies and the like during the AGL development phase. Also, some drivers (i.e.: the IDI driver used by Midas and the Versatec printer/plotter driver) and the full revision which resulted in Versions 3.6 and 3.61 have been developed with the support of ESO/IPG. AGL and the Operating Environment Here are some operating environment details which may be useful to the AGL application programmer. Please note that some details and concepts may be different on different Operating Systems, so a check in the AGL Installation and Customization Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 8 Guide may be sometimes necessary. 1. Environment variables (Unix, MS-DOS) or Logical names (VMS) AGL3CONFIG Defined by the system manager. Contains the name of the AGL standard directory, where all the run- time files are located. This variable is not used under MS-DOS where all AGL files are assumed to be located onto the directory: \AGL. AGL3DEV Defined by the user. May contain a string used as default device type. When a device name is not found into the configuration file (see below) the content of AGL3DEV (if it exists) is used as device type (see: AG_VDEF). Here is a list of some currently defined device types (see the complete list at the end of the "AGL Installation and Customization Manual"): hpgl HPGL plotter ibmpc IBM-PC screen (EGA/CGA) idi IDI interface driver pscript Postscript printer raster Generic raster device tkg.4010 Tektronix terminal tkg.cit101 Itoh CIT 101/414 terminal tkg.4100 Tektronix 41xx terminals vt125 Digital VT 125 window X11 or SunView window x11 Direct X11 driver 2. Configuration file There are two different configuration files which may be of concern of the programmer or AGL user; both of them are named: agldevs.dat. One is maintained by the system manager and is located on the AGL standard directory (see above): it contains system wide definitions of device names and types (E.g. for spooled devices, etc.). The second may be on the user's current directory and contains device names and types specific of the user (E.g. a definition for the interactive terminal, and/or for the user's favorite plotter, possibly with indication of special commands for plotting). NOTE: the user's agldevs.dat file content overrides the system wide definitions. Details about configuration files content may be found in: "AGL Installation and Customization Guide". Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 9 HOW TO STRUCTURE AN AGL APPLICATION The following rules apply to any application program irrespective whether it is written in FORTRAN or in C; the test programs pro- vided are written in FORTRAN, but they should be simple enough to be profitably used as examples of C applications also. You only must remember the slight differences int the AGL inter- face mainly due to the different ways of argument passing in the two languages. The language specific AGL reference guide will anyway provided all the required information for the calling sequences. All references quoted below can be retrieved in the fortran code after comment lines like the following: c -- Reference <n> Some parts of the following discussion which are at a greater level of detail than required at a first look may be skipped. they are enclosed between clear division lines: ===========================================================DETAIL More detailed discussion that can be skipped at the first glance. It will maybe necessary to read the later. ================================================================= All the program quoted below are provided as source files in the standard AGL kit. 1) Program "test1.f" c -- Reference 1.1 integer agvdef The routine AGVDEF we will use below returns an integer value so that it MUST be declared as integer. c -- Reference 1.2 write(6,8000) read(5,8010) device if(device.eq.' ') device='tt:' c 8000 format(' Device name [tt:]?:') 8010 format(a) This part only to ask interactively for a device name. See below for details on AGL device names. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 10 c -- Reference 1.3 ivwp=AGVDEF(device,0.0,1.0,0.0,1.0,0.0,0.0) Any AGL application will start with a call like the one above. The string 'x:' specifies which device the graphic output must go to. ===========================================================DETAIL All the details regarding device names should have been set by the local system manager when AGL was installed. Here are, any- way a short resume of AGL device naming. A detailed description can be found in the "AGL Installation Guide". Given the string 'x:' the routine will look into a table to find out which kind of device it is. The table is contained into a file named "agldevs.dat" which is either on the current dire- ctory (for devices which are known only to the user) or on a system wide directory whose name is in the system variable AGLCONFIG. That file must have a line starting with 'x:' which specifies the kind of device, otherwise the program will exit immediately with the following message: AGL Status code 310 in: AG_VDEF from: User prog. This means that the requested device is not defined. In the installation examples provided with the AGL kit the name 'x:' is used for the "X11" device. This means that you must be working on an X11 terminal or workstation to use it. Other frequently used names are: 'tt:' which stands for the current terminal, 'ps:' for a PostScript printer, 'con:' for the IBM-PC screen (again a line into the above mentioned file must specify the type of device). ================================================================= The following four values specify which part of the drawing sur- face you want to use. They refer to the "normalized" coordinate system which sets the lower left corner of your drawing area as (0,0) and the upper right corner as (1,1). The last two value are, for the moment, not significant. Then you may want to draw a box with suitable quoted axes, labels, title, and so on. That could be done in a single call, if your needs aren't too much sofisticated: Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 11 c -- Reference 1.4 call AGAXES(-1.2,1.2,-1.2,1.2,'title=Lissajous;') This call will produce a box with tick marks, quotes and the like. The routine AGAXES is actually an high level routine which calls quite a number of other AGL routines to do his job. The first four values define the data window to be in the range [-1.2,1.2] for both axes. The last argument is a character string which specifies a lot of details on how the axes must be drawn. Here only the plot title is specified, but you could add labels for both axes, the request of grid lines, logarithmic scales on an axis or both, and so on (see the reference manual for a complete description). ===========================================================DETAIL After the call not only the quoted axes will have been drawn, but the status of AGL will be suitable for subsequent plotting, namely a user set of coordinates will be in effect so that data in the range [-1.2,1.2],[-1.2,1.2] will be mapped as expected into the proper area. The same effect could be obtained without calling the AGAXES routine by means of a call to AGWDEF. Moreover new clipping limits have been extabilished, so that data falling outside the box will not be seen. The current AGL graphic mode is referred to as "USER" whereas after the call to AGVDEF it was "NORMAL". When in NORMAL mode coordinates are in the range [0,1] and map exactly on the full graphic surface of the device; anyway everything is plotted outside the area defined in the AGVDEF call is clipped. When in USER mode coordinates are in the range specified in the call to AGWDEF (or AGAXES as in the example above) and the clipping is referred to an area which may be a subset of the one defined in the AGVDEF call. This subset is, by default, the full area defined by AGVDEF, but can be modified by calling AGCDEF, which will define a new "clipping area". Note that clipping with respect to clipping area in USER mode is only applied to "lines" while the text is still clipped with respect to the full viewport. ================================================================= c -- Reference 1.5 call AGSSET('color=red') The routine AGSSET has a great number of uses. It can set or modify every aspect of AGL and it is likely the more widely used. Here it is called in order to set the color of the lines we want to draw. Up to now the default color was used. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 12 Here you may notice that the argument is a character string: it could be actually be a more complex one containing a series of commands (separated by semicolons) which would be executed as if a series of single commands calls had been made. ===========================================================DETAIL Obviously the color support is dependent on the capabilities of the device. AGL only tries to ensure that you always see some- thing even if you set a color on a black and white device. Available colors are, at the moment, black,white,red,blue,yellow gree,cyan and magenta. Another valid name is background which will set the color to the background default color for the device (e.g.: white for a device printin on paper and black for a display). If you set the color to the background color you most likely will not see any drawing (some device will actually write with the background color, i.e.: will erase previously drawn lines if drawing the same plot), but this depend on the kind of device (this cannot be obtained on a pen plotter, of course). For devices supporting this feature, the background color can be modified, e.g.: call AGSSET('bacgkr=red'); this call will also erase all the previous drawings. ================================================================= c -- Reference 1.6 arc=0.0 step=2*3.1415927/499. c do 1000 i=1,500 xlj(i)=cos(arc*3.0+1.5708) ylj(i)=sin(arc*4.0) arc=arc+step 1000 continue Here the data to be plotted are computed. In this case it is a simple sin versus cos function, just for the purpose of the example. Two single precision arrays containing 500 elements are produced. c -- Reference 1.7 call AGGPLL(xlj,ylj,500) Here the content of the two arrays is actually plotted. c -- Reference 1.8 call AGSSET('cursor=-1') This call to AGSSET will select a particular type of cursor. The cursor is in this context a cross or other pointing device which can be moved on the screen waiting for some kind of action Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 13 (e.g.: a button or key press) and returning the coordinates of the point. Here this device is used for a simple action: stopping the pro- gram until a key is pressed. because of this use we actually do not want to see the cross on the screen, or get back coordinates, so we set the cursor type to -1. ===========================================================DETAIL AGL in principle supports a number of different cursor types. Unfortunately this is a feature which is strictly related to device capabilities, so that usually only two kinds of cursors are available: -1 which is an "invisible" cursor, and: 0 which is the device default cursor which usually operates as expected. All devices capable of interaction are required to support at least these two cursor types. ================================================================= c -- Reference 1.9 call AGVLOC(xa,ya,key,ipix) The routine AGVLOC will start a cursor interaction with the device and wait for some action; after that it will return the cursor coodinates, a code indicating the particolar action per- formed, and possibly the value of the color pixel at that point. In this case we have selected cursor type -1, so only the key code will be significant. In this application, anyway, we will ignore also this value. If the current graphic device is not capable of interaction this call will return immediately and a warning will be issued: you will not see it, anyway, because warning messages are usually discarded if not explicitly enabled. c -- Reference 1.10 call AGCLS A call to AGCLS will terminate orderly the graphic operations. The closing call is usually a good programming practice in that some device might not remain in proper state if not explicitly instructed to do so. 2) Program "test2.f" This is a sightly more complicated example but the first part of it is a very close copy of program test1. Explanations will thus sometimes refer to the previous pages. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 14 c -- Reference 2.1 c -- Reference 2.2 See References 1.1 and 1.2 c -- Reference 2.3 ivwp0=AGVDEF(device,0.0,1.0,0.9,1.0,0.0,0.0) See also Reference 1.3. Notice that this viewport defines a small strip of in the upper part of the graphic surface. This viewport will be not used, for the moment. c -- Reference 2.4 ivwp=AGVDEF(device,0.0,0.5,0.45,0.9,0.0,0.0) See also Reference 2.3. Here another viewport is defined which selects the upper left fourth of the graphic surface as target for our plot and, moreover, it is contigous in the upper part to the viewport defined above. Notice that from now on the last definition will hold and the one at point 2.3 is suspended. c -- Reference 2.5 c -- Reference 2.6 See References 1.4 and 1.5 c -- Reference 2.7 Here in the data computation loop we also store values of the arc in a suitable array to be used later. c -- Reference 2.8 Up to now the plot is almost exactly the same as in program test1 except for the fact that everything is scaled down in order to fit the smaller viewport. c -- Reference 2.9 call AGVKIL Here we close the current viewport (we don't use AGCLS because we are not finished with plotting). The call to AGVKIL is not strictly requred, but would be a good programming practice because there is a limit on the number of viewports which can be open at the same time. And also remeber the first viewport which is still waiting. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 15 c -- Reference 2.10 ivwp=AGVDEF(device,0.5,1.0,0.45,0.9,0.0,0.0) Now we define another viewport in the upper right fourth of the graphic surface, c -- Reference 2.11 call AGAXES(0.0,6.2831853,-1.2,1.2,'laby=Sin(X);gridy') call AGGPLL(arc,ylj,500) we draw suitable axes and a sinusoidal function (we computed the array arc in the loop at Reference 2.7). You may notice some sligth differences in the layout of the plot which are the consequence of the different options in the call to AGAXES. c -- Reference 2.12 call AGVKIL Here again we terminate the output on the current viewport (see also Reference 2.9). c -- Reference 2.13 ivwp=AGVDEF(device,0.0,0.5,0.0,0.45,0.0,0.0) A new viewport is now opened to draw one more plot. It is located in the bottom left part of the graphic surface. c c -- Reference 2.14 call AGAXES(-1.2,1.2,0.0,6.2831853, + 'labx=cos(Y);laby=Arc;gridy') call AGGPLL(xlj,arc,500) call AGVKIL Here the vector arc is plotted against xlj. The viewport is then closed. c c -- Reference 2.15 do 1100 i=-4,4 idx(i)=i 1100 freq(i) = 0 c do 1110 i=1,500 ind = xlj(i)*4.9999999 freq(ind) = freq(ind)+1 1110 continue The above loops prepare data for the next plot. The first one prepares an array of values we will need as X-axis of the plot (idx), and clears the array freq. The second one computes the frequencies of values in the vector xlj falling into nine inter- vals equally spaced in [-1.0,1.0]. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 16 c c -- Reference 2.16 ivwp=AGVDEF(device,0.5,1.0,0.0,0.45,0.0,0.0) call AGAXES(-5.0,5.0,0.0,110.0, + 'labx=value;laby=Frequency;factx=0.25') call AGHIST(idx,freq,9,1,0) call AGVKIL Here another viewport is defined in the lower right corner of the graphic surface. Axes are then plotted with scales suitable for an histogram plotting; you may note that we used an array of indexes:w C PROGRAMMING HINTS 1. As an help to software development some files have been added which may be included into source code. These files are copied onto the AGL standard directory during the in- stallation. agl.h Declaration of functions. Entry points decla- rations useful for value returning routines. aglerror.h Error codes definitions and explanation. It may be included in source files which need to test error return values or used as on line help for error codes. 2. If an application program includes agl.h, the standard file stdio.h must be included before it, because one of the entry points return a pointer to FILE. When including agl.h you might want also to define the pre- processor symbol: ANSI which will provide C ANSI standard function prototypes. FORTRAN PROGRAMMING HINTS Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 17 1. When using AGL FUNCTION subprograms be sure that the routine name is correctly declared within the calling program, otherwise the return value might be incorrect. E.g: AGVDEF returns the INTEGER identifier associated with the opened viewport, if the name AGVDEF is not declared as INTEGER it is assumed to be REAL due to the default type declaration of FORTRAN variables. 2. A FORTRAN source file named aglerror.f is provided within the AGL distribution kit, containing declarations and value assignment (by means of PARAMETER statements) of AGL error codes. This file may be included by applications which must check error return values. The file aglerror.f is copied onto the standard AGL directory as part of the installation procedure. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 1 AGCDEF Define clipping area Redefine the clipping area. Clipping area is a subset of the current view- port onto which graphic data are mapped when in USER mode. It defaults to the current viewport limits, but may be defined smaller than that, e.g. in order to leave space for labels and comments around the plot. Clipping area redefinition also resets aspect ratio control (see AGSSET, item: "GEOM"). subroutine AGCDEF (x1,x2,y1,y2) real x1,x2,y1,y2 Clipping area bounds [0.0..1.0]. They must be also enclosed into the current viewport. (x1<x2) and (y1<y2) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 2 AGCLS Terminate orderly Orderly terminate AGL operations. Deactivate all viewports, close all open metafiles, deallocate active graphic devices. subroutine AGCLS () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 3 AGISET Set integer status parameters Set up to ten (10) integer values into the user defined parameters area. This call may be used by applications in order to store numerical values to be retrieved later on. These values remain associated with the current viewport and can be retrieved by a call to AGIGET (item USER) subroutine AGISET (number,values) integer number Number of items to store (n<=10) integer values(1) Array of values to be stored If n<=0 the parameter area is cleared Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 4 AGRSET Set float status parameters Set up to ten (10) float values into the user defined parameters area. This call may be used by applications in order to store numerical values to be retrieved later on. These values remain associated with the current viewport and can be retrieved by a call to AGRGET (item USER) subroutine AGRSET (number,values) integer number Number of items to store (n<=10) real values(1) Array of values to be stored If n<=0 the parameter area is cleared Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 5 AGSSET Set status Set various status parameters. Parameters and values are specified by a command string. subroutine AGSSET (commnd) character*(*) commnd Command string. Command strings have the following syntax: "keywd[=value];keywd[=value];....." Keywords can be truncated at the minimum number of characters needed to recognize them (shown uppercase in the list below) and can be typed both in upper and lower case; string values must be quoted. Keyword Description BACKgr=color Set background color as specified "color". Each color value is either a number (device dependent) or a standard color x`name. For a list of standard colors see the entry "COLOR" below. Note: the capability to set background color is device de- pendent, some drivers will not respond to this command. It is also recommended to send this command before any other graphic output command. Changing the background color will also usually erase the device. BOTTomup Set string drawing direction bottom up (angle=90 deg) See also: LFRG, RGLF and UPDOWN CHANGle=a Set string drawing angle to a (see also: bottomup, updown, lfrg, rglf, degrees, radian) CHBAsic Set character dimension to "basic" (See Note 1) CHDIms=h,v Set character dims h (horiz.) v (verti.) (See Note 1) CHLArge Set character dimension to "large" (See Note 1) CHMEdium Set character dimension to "medium" (See Note 1) CHSMall Set character dimension to "small" (See Note 1) CLR1 Set standard color one (usually black, if background is white, or white if viceversa) CLR2 Set standard color two (usually red, if possible) CLR3 Set standard color three (usually red, if possible) COLOr=color Set current drawing color as specified by "color". Color is either a device dependent numeric value or one of the follo- Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 6 wing strings: background,black,red,green,blue,yellow,magenta,cyan,white. where 'background' stands for the default background color The color capability is obviously device dependent. Drivers will set the "closest" color. CURSOR=xx Set cursor style (default is 0, if<0 no cursor is displayed) see also AGVLOC DEBUg=xx Set debugging (1: on, 0: off. Default off) DEGRees Set angular units in degrees (Default. See changle) ERRFile=name Redirect error output to file (default is stderr) FONT=font Set character font. font may be a numeric value between 0 and 5, or one of the following font names (only the first three characters are significant): default (or font 0) : the AGL builtin font quality (or font 1) : high quality roman font greek (or font 2) : Greek font script (or font 3) : Script font old (or font 4) : Old English font with special astro- nomical symbols tiny (or font 5) : Tiny roman font. Simpler than font 1. GEOm Activate geometrical aspect ratio control IBAckg=color Define the colour of the background to be set at initializa- of any graphic device supporting background color setting. Usually the default background color is a device dependent parameter. If a call: AGSSET("IBACK=<color>"); is issued before a viewport activation which also initialize a graphic device, then the default background is set to <color> (if possible). <color> is one of the following strings: background,black,red,green,blue,yellow,magenta,cyan,white. Color=background, or no value, means that the device dependent default background must be set The color assigned with the call is used for any device activated after the call until a new color or the default one is preset with another call to AGSSET() LINX Activate linear transformation on X axis LINY Activate linear transformation on Y axis LOGX Activate log transformation on X axis Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 7 LOGY Activate log transformation on Y axis LFRG Set string drawing direction to left to right (angle=0 deg) See also: BOTTOMUP, RGLF and UPDOWN LSTYLe=xx Set line style. patterns are: 0: solid, 1: dot, 2: dash, 3: dot dash, 4: long dash, 5: dot dot dash. Default is 0. LWIDTh=xx Set line width. (Optionally supported by device drivers). Values specify increasing line width. Default is 0. MFHARd Set metafile option to "hard" (see AGMOPN) MFSOFt Set metafile option to "soft" (default) (see AGMOPN) MOde=mode Set graphic write mode. The value mode can be one of: Subst, Or, Xor, Eqv (the first char only is significant). Default mode is Subst (the new pixel value substitutes the previous one, other values are optionally supported by device drivers. MSGAll Display all information messages MSGError Display error and severe error messages MSGNone Suppress any error message MSGSevere Display only severe error messages MSGWarning Display warning, error and severe error messages NORMalized Set graphic mode to "normalized" (see: also USER and SPECIAL) NGEOm Suppress geometrical aspect ratio control (see: GEOM) RADIans Set angular units in radians (Default is deg. See changle) RGLF Set string drawing direction to right to left (angle=180 deg) See also: BOTTOMUP, LFRG and UPDOWN SCALE=nn Set a global scaling factor for symbols and characters. The dimensions of symbols and characters may be separately modified with: CHSMALL, CHBASIC, CHMEDIUM, CHLARGE and CHDIM, and SYSMALL, SYBASIC, SYMEDIUM, SYLARGE and SYDIM. Default is 1.0 SPECial Set graphic mode to SPECIAL. In order to set this mode a user defined coordinate transformation must have been set via a call to AGTRNS. See also items USER and NORMAL STPError Set prog. termination threshold to error STPNever Set prob. termination threshold to never terminate STPSevere Set prog. termination threshold to severe error SYBAsic Set symbol (marker) dimension to "basic" Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 8 SYDIm=h Set symbol dimension to h times "basic" (h is a float value) SYLArge Set symbol (marker) dimension to "large" SYMEdium Set symbol (marker) dimension to "medium" SYSMall Set symbol (marker) dimension to "small" TWIDTh=xx Set line width for text strings. (Optionally supported by device drivers). Values specify increasing line width. Default is 0. USER Set graphic mode to USER (see also items NORMAL and SPECIAL) UPDOwn Set string drawing direction to up down (angle=270 deg) See also: BOTTOMUP, LFRG and LFRG Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 9 AGVDEF Define viewport Define and activate a new viewport. If a viewport is currently active it is saved prior of activating the new one. After definition the graphic mode is NORMALIZED. The first time a viewport is activated on a given device, the device is allocated and initialized. Subsequent activation of viewports referencing the same device will not reinitialize it. The device is released when the last viewport referencing it is killed. integer function AGVDEF (device,xa,xb,ya,yb,xlim,ylim) Returns integer viewport identifier (or < 0 if an error occurs) character*(*) device Graphic device identification. It is a string with the following syntax: device[.aux][/n]:[inpmet][>outmet[/a]] where: device - Device name See below for naming rules. aux - Auxiliary user information. This string is passed as such to the device driver to select special device dependent features. E.g.: it may be used by some drivers to select either portrait or land- scape orientation, and the like. Specifications for auxiliary info are given in the device specific documentation. /n - optional "no erase on init" flag. : - required separator. inpmet - optional input metafile name. If specified the named metafile is executed just after viewport acti- vation. > Output metafile designator (requi- red if output metafile name is specified). outmet - Optional output metafile name. If specified the named metafile is opened for output just after view- port activation and prior of input metafile execution. /a - Optional request for append mode opening of output metafile. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 10 real xa,xb,ya,yb Viewport bounds (Normalized: 0.0-1.0). xa<xb, ya<yb. (xb-xa)>0.001, (yb-ya)>0.001 real xlim,ylim Viewport dims (in cm). If 0.0 the device default values are assigned. The request will be accepted only at device initiali- zation (i.e. the first time a viewport is opened onto the device). Some devices may ignore the request (it is an optional driver capability). DEVICE NAME SPECIFICATION Device names may be either the special name tt: or a logical or physical name. Device name translation is performed according to the following steps. 1. If the name is "tt:", no further translation is performed and it is assumed that the output must be sent to the current interactive ter- minal. A definition for the type of terminal must be found within the user defined file agldevs.dat, or in the system wide file agldevs.dat It may be specified either by an entry into the file agldevs.dat such as: tt:<devtype> (eg: tt:tkg.t4010, tt:vt125, etc.) If the entry is not found the environment variable (logical name) AGL3DEV is translated to get the device type (eg: tkg.t4010, vt125, etc.). If neither the entry is found into agldevs.dat nor the AGL3DEV variable is defined a severe error condition is raised. 2. Any other string is considered to be an environment variable (or logi- cal name) and translated. 3. When no further translation is possible the resulting string (the original string, if it was a physical name) is used as device name. 4. An entry for the given device name must be found either in the user specific agldevs.dat file or in the sistem wide file with the same name, with specification of the type of device. If the entry is not found the device name is used as physical device for output and the environment variable (logical name) AGL3DEV is translated to get the device type. If neither the entry is found into agldevs.dat nor the AGL3DEV variable is defined a severe error condition is raised. By default the device is erased when the 1st viewport is opened onto unless disabled with "/n". The following examples shows various device specifications: tt: Send output to current interactive device, find device type into file agldevs.dat or into the environment variable AGL3DEV. tt/n: As above. Do not erase on opening. ps0.R90:>meta.tmp Translate environment variable (logical) ps0, use Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 11 the resulting string (or "ps0" if no translation exists) as device name. Search for device type first into agldev.dat on the current directory then in the same file on the AGL standard direc- tory; if not found try to translate the environ- ment variable (logical) AGL3DEV. If successful open the device also sending to it the device specific string R90. Then open the output metafile meta.tmp for graphic operations recording. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 12 AGVKIL Kill current viewport Kill the current viewport. If a metafile is currently associated to the viewport it is closed. subroutine AGVKIL () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 13 AGVSEL Select viewport Select a previously saved viewport after saving the current one. The specified viewport must have been previously defined and saved (see also: AGVDEF). subroutine AGVSEL (id) integer id Viewport identifier as returned by a pre- vious call to AGVDEF. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- STATUS Page 14 AGWDEF Define user window User window definition. Sometimes referred to as "world coordinates" defi- ne the user data coordinate systems. User data in the given rectangular range are mapped onto the current clipping area (see AGCDEF). After the call the mode is set to USER. User data transformation may be controlled in various ways (see AGSSET, items: NORMAL, USER, LOGX, LOGY, LINX, LINY, GEOM, NGEOM). subroutine AGWDEF (x1,x2,y1,y2) real x1,x2,y1,y2 Window bounds Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 1 AGGPLG Draw polygon Polygon drawing. The given set of points are connected with straight lines starting at the first point. The last point is joined to the first. Line aspect (style, width, color) may be selected via AGSSET. The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL" subroutine AGGPLG (xv,yv,np) real xv(1),yv(1) Coordinate arrays integer np Array length Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 2 AGGPLL Draw polyline Polyline drawing. The given set of points are connected with straight lines starting at the first point. Line aspect (style, width, color) may be selected via AGSSET. The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL" subroutine AGGPLL (xv,yv,np) real xv(1),yv(1) Coordinate arrays integer np Array length Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 3 AGGPLM Draw polymarker Trace a set of symbols or markers. Symbols my be chosen from a set of seventeen. Symbol dimensions may be controlled via suitable AGSSET commands. The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL" subroutine AGGPLM (xv,yv,np,mark) real xv(1),yv(1) Symbol position arrays integer np Position array length integer mark Symbol specifier (0..20) Currently defined marker symbols: Specifier Symbol 0 Dot 1 Exagon 2 Square box 3 Triangle 4 + 5 X 6 + over X 7 Star 8 + over square box 9 X over square box 10 Lozenge 11 Horizontal bar 12 Vertical bar 13 Rightward oriented arrow 14 Upward oriented arrow 15 Leftward oriented arrow 16 Downward oriented arrow 17 Filled exagon 18 Filled square 19 Filled triangle 20 Filled lozenge Note: simbolic names for the marker values are defined into include file <agl.h> for the convenience of the C program- mer. Values greather than 32 are taken as ASCII codes and the corresponding character of the current font is drawn centered in the point of given coordinates. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 4 AGGTXT Draw text Text drawing routine. String dimension and orientation can be set via AGSSET. Relative string position with respect to the given point can be specified by the center index argument as shown in the following figure where a box supposed to enclose the string is sketched. 22 21 20 19 18 +-----+-------------------+--------------------+-----+ | | | | | | | | | | | | | | | | 7| 6| |5 | 23+-----+ *** **** ****+ **** ***** *****+-----+17 | |* * * * * * * * * | | | |* * * * * * * * * | | | |***** **** * * * *** *** | | | |* * * * * * * * * | | | |* * * * * * * * * | | | |* * **** *** **** ***** * | | | 8| | |4 | 24+-----+- -+0 -+-----+16 | | | | | | | **** * * *** *** * * * | | | |* * * * * * * * | | | |* * * * * * * * | | | |* ** ***** * * ** * | | | |* * * * * * * * * | | | |* * * * * * * * * | | 9+-----+ **** * * *** + *** * * *****+-----+15 | 1| 2| |3 | | | | | | | | | | | | | | | | | | | | | +-----+-------------------+--------------------+-----+ 10 11 12 13 14 Note: The vertical offset of displacement codes 10,11,12,13,14 and 18,19, 20,21,22 is the character height. The horizontal offset of codes: 14,15,16,17,18 and 22,23,24,9,10, is equal to the character width. The positioning and newline is made with respect to the current character size and could be different than exepected if character size is modified by the related metacharacter sequences (see below). The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL" Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 5 The text drawing routine provides for interpretation of the following metacharacter: \{ - Begin grouping \} - End grouping \^ - move the following part of the string up by half a character \_ - move the following part of the string down by half a character \< - Backspace by a single character \+ - Increase character size by 20% (1) \- - Decrease character size by 20% (1) \! - Force interpretation of the following part as a metasequence (this is needed to allow metasequences starting with 'n' not to be interpreted as newlines) \0 - select font 0 (Default font) (1,2) \1 - select font 1 (Quality roman font) (1,2) \2 - select font 2 (Greek font) (1,2) \3 - select font 3 (Script font) (1,2) \4 - select font 4 (Old English) (1,2) \5 - select font 5 (Tiny roman font) (1,2) \[ - Increase line width (bolding) (4) \] - Decrease line width (bolding) (4) \#<n> - Draw marker number <n> into the line (3) \n - Perform a "newline" ~~ - Draw a single '~' character \~ - Draw a single '~' character ~\ - Draw a single '\' character \\ - Draw a single '\' character The above "single character" instructions MUST NOT BE FOLLOWED BY BLANK The character '~' can also be used instead of '\' as metacharacter flag The '~' is more suited to C programs where '\' has a special meaning. All selections made by metacharacters are valid from the point in the string where they are defined up either to the end of current group (the part of the string enclosed in \{..\}) or to the end of the string Note 1: The same action of this metacharacter commands can be selected permanently via the suitable AGSSET command Note 2: Correspondance of font characters (and ASCII codes) can be obtai- ned by running the test program "fonts" Note 3: This function allows to include a marker symbol within a text string. See routine AGGPLM for the defined marker symbols. The syntax for includeing markers is sligtly different from the one used in AGL vers. 3.5x !! Note 4: This functions are optionally supported by device drivers. AGL also interprets a set of 'TEX like' keywords as listed below. Unfortunately, due to the fact that most of them require special characters to be shown, only the names are listed, while the exact meaning can only be seen by means of the "fonts" program, which is created as part of the standard AGL installation procedure. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 6 If the metacharacter sequence is more than one character long (escape not included, of course), it MUST BE FOLLOWED BY A BLANK SPACE. \AA \Alpha \Aquarius \Aries \Beta \Cancer \Capricorn \Chi \Delta \Earth \Epsilon \Eta \Gamma \Gemini \Iota \Jupiter \Kappa \Lambda \Leo \Libra \Mars \Mercury \Moon \Mu \Neptune \Nu \Omega \Omicron \PI \Phi \Pisces \Pluto \Psi \Rho \Sagittarius \Saturn \Scorpio \Sigma \Sqrt \Tau \Taurus \Theta \Upsilon \Uranus \Venus \Virgo \Xi \Zeta \aleph \alpha \asteroid \beta \bigcirc \black \blue \cent \chi \circ \cyan \clover \clubsuit \comet \dag \ddag \default \delta \diamond \div \downarro \epsilon \equinox \equiv \eta \firtree \gamma \ge \greek \green \hbar \heart \infty \int \iota \italic \kappa \lambda \larrow \le \magenta \mp \mu \!nabla \!ne \!nu \odot \oint \old \omega \omicron \oplus \otimes \palmtree \paragraph \parallel \partial \perp \phi \pi \pm \propto \psi \red \rho \rightarrow \roman \script \shield \sigma \snow \spade \sqrt \sum \tau \theta \times \tiny \uparrow \upsilon \varepsilon \varphi \vartheta \white \xi \yellow \zeta When specifying metasequences the minimum number of characters required for matching may be used. The "!" character in front of sequences starting with "n" is required to asubroutine the interpretation as newline single character sequence. subroutine AGGTXT (xc,yc,text,centre) real xc,yc String position character*(*) text String to draw (max 132 chars) integer centre Centre index (see above) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 7 AGGINT Draw a segments interpolating between points This module will trace a polyline interpolating in a suitable number of intermediate points between the points defined in the call. This module is of use when a non-linear transformation is active and a line which is "straight" in the world coordinate system would not result in a straight line on the graphic device. This routine is less efficient than AGGPLL() so when the input polyline is known to contain points which are close enough to get proper resolution AGGPLL() should be called instead. Line aspect (style, width, color) may be selected via AGSSET. The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL" subroutine AGGINT (xv,yv,np) real xv(1),yv(1) Coordinate arrays integer np Array length Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 8 AGVERS Erase current viewport Erase current viewport (Note: most devices do not allow partial erase of the screen, so the full screen will be erased even if the viewport only covers a portion of it) If the device drivers allows background color selection, then the current background color is used. Background color can be set by means of the SSET routine. subroutine AGVERS () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- GRAPH Page 9 AGVUPD Force graphic update Forcefully empty the graphic buffer. This operation is usually performed in an automatic way by AGL, but the function is provided to cope with special cases subroutine AGVUPD () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 1 AGIDN Version identification Returns a character string containing AGL version identification with the following format: 'AGL - V:3.61 (F)' SUBROUTINE AGIDN(string) CHARACTER*(16) string; Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 2 AGIGET Get integer information Get integer pieces of information. Required information is specified by a command string. integer function AGIGET (item,ival) Returns number of values in ival. character*(*) item Information select string (see below). integer ival(1) Return value(s). The array must be long enough to contain the required number of values specified in the list below. The select string contains a keyword which specifies the piece of informa- tion required. Keywords can be truncated at the minimum number of charac- ters needed to recognize them (shown uppercase in the list below) but can be typed both in upper and lower case Number of Name items Description BACKGround 1 Default background color of current device BLACk 1 Color code to get black color BLUE 1 Color code to get blue color COLOr 1 Current color code CLR1 1 Main color code CLR2 1 Secondary color code CLR3 1 Third choice color code CYAN 1 Color code to get cyan color DEVType 1 Device type (0: passive, 1:interactive) ERROr 1 Last error code FLG00 1 =1 if device is Interactive (else 0) FLG01 1 =1 if device locator can return pixel value (else 0) FLG02 1 =1 if device allows partial erasing (else 0) FLG03 1 =1 if alpha plane is separated from graphic planes FLG04 1 =1 if device must be explicitly erased at initializ. FLG05 1 =1 if command defined in AGLDEVS.DAT will be executed FLG06 1 =1 if device accept RGB color definition (else 0) FLG07 1 =1 if device can set RGB color background (else 0) GREEn 1 Color code to get green color LINX 1 =1 if linear transformation on X axis (else 0) LINY 1 =1 if linear transformation on Y axis (else 0) LOGX 1 =1 if linear transformation on X axis (else 0) LOGY 1 =1 if linear transformation on Y axis (else 0) LSTYLe 1 Current line style LWIDTh 1 Current line width MAGEnta 1 Color code to get magenta color MFMODE 1 Current metafile mode (0:no metafile; 1: SOFT; 2: HARD) MODE 1 =0 if current mode is NORMALIZED, =1 if USER, =2 if current mode is SPECIAL NCOLors 1 Number of colors (pens, gray tones) allowed by device NSYMbols 1 Number of symbols (markers) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 3 NSTYLes 1 Number of line styles supported (the default 0 not included) NWIDThs 1 Number of line widths supported (the default 0 not included) RED 1 Color code to get red color TWIDTh 1 Current text line width USER 10 Get up to 10 user specified data items. See AGISET. WHITe 1 Color code to get white color YELLow 1 Color code to get yellow color Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 4 AGRGET Get real information Get real pieces of information. Required information is specified by a command string. integer function AGRGET (item,fval) Returns number of values in fval character*(*) item Information select string real fval(1) Return value(s). The array must be long enough to contain the required number of values specified in the list below. The select string contains a keyword which specifies the piece of informa- tion required. Keywords can be truncated at the minimum number of charac- ters needed to recognize them (shown uppercase in the list below) but can be typed both in upper and lower case Name items Description ANGFct 1 Angular values conversion factor. It is = 1.0 if current interpretation is "Radians" else is equal to the requi- red conversion factor ASPEct 1 Current device aspect ratio CLPAspect 1 Current clipping area aspect ratio CLPLimits 4 Current clipping area limits (Xlow,Xup,Ylow,Yup) CHDIms 2 Current character dimensions (x,y centimeters) CHNDIms 2 Current character dimensions (x,y normalized) DEVDims 2 Current device dimensions (centimeters) NCHDIms 2 Basic character dimensions (x,y normalized) RESOlution 2 Current x and y axis resolutions (1./N.of pixels) SCALE 1 Current overall character and symbol scale USER 10 Get up to 10 user specified data items. See AGRSET. VWPLimits 4 Current viewport limits (Xlow,Xup,Ylow,Yup) WNDLimits 4 Current window limits (Xlow,Xup,Ylow,Yup) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 5 AGTGET Get text dimensions Returns the normalized displacements of a box enclosing the given string, as shown in the following figure: The displacements are computed with respect to the box origin shown as point (0,0) in the figure. | | (xd[2],yd[2]) --- *** **** **** --- (xd[1],yd[1]) * * * * * * * * * * * * ***** **** **** * * * * * * * * * * * * * * * * * * (0,0) ------- * * **** **** **** --- (xd[0],yd[0]) | * | | * | | | N.b.: in the example there are couples of coordinates which are equal (xd[0]=xd[1], etc.) but this is in general not true for different orientations of the string Return values are always referred to the NORMALIZED mode coordinates irrespective of the current graphic mode. subroutine AGTGET (text,xd,yd) character*(*) text Input string real xd(1) String x displacements (Normalized) real yd(1) String y displacements (Normalized) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 6 AGVLOC Get locator position Get the position from a locating device. The locating device use depends on the particular hardware. It has usually the form of a cross which can be interactively moved by a joy-stick, arrow keys and the like. The routine returns when the needed key (again depending on the device) is depressed. Starting and returned positions are referred to the current graphic mode (either USER or NORMALIZED) and are mapped accordingly. Cursor style (shape and/or dimension) may be varied via a suitable call to AGSSET, default style is 0, other styles may be optionally supported by specific device drivers. If style is <0 then no cursor is displayed and the only significant information returned by the routine is the key code. A warning status is set if the current locator position is outside the currently active viewport An information status is set if the current locator position is outside the clipping area and the current graphic mode is USER subroutine AGVLOC (xv,yv,key,pixval) real xv,yv Input: required locator initial position. Some devices may ignore this values (it is an optional driver capability). Return: final locator position. Both values are referred to the current coordinate system: USER or NORMALIZED. integer key Return: key code (device dependent). integer pixval Pixel value (color). Some devices will always return 0 (it is an optional driver capability). Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- INFO Page 7 AGVLOS Get locator position. Also return a string Get the position from a locating device. This routine has a functionality very close to AGVLOC. The only difference is that a sequence of chara- ters may be returned to the caller into a string. The string input is terminated when a "newline" or other control character is pressed. The newline or control character is NOT included in the string, and a null character is appended (when calling from C language routine). NOTE: if the locating device is moved during interaction (between some keypresses) the position result is unpredictable. subroutine AGVLOS (xv,yv,maxlen,chstrg,pixval) real xv,yv Input: required locator initial position. Some devices may ignore this values (it is an optional driver capability). Return: final locator position. Both values are referred to the current coordinate system: USER or NORMALIZED integer maxlen Maximum length of return string. If more than maxlen characters are typed, they are ignored. If the input is terminated due to a control character, the string is null terminated. character*(*) chstrg Typed string. String length in the calling program must be at least maxlen characters. integer pixval Pixel value (color). Some devices will always return 0 (it is an optional driver capability). Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- META Page 1 AGMCLS Close metafile Closes the currently open Metafile subroutine AGMCLS () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- META Page 2 AGMOPN Open metafile Open an output metafile associated to the current viewport. If a metafile is already open a warning is issued and the metafile is not opened. After opening the metafile is active. If a metafile with the same name already exists on the designated path, the result will depend on system standard action in similar cases. The metafile name can optionally be flagged with /a in which case the metafile will be opened in append mode (if a file of the given name already exists in the designated path). In order to allow full path specification on Unix, the /A flag must be appended as such to the end of the file name. E.g.: the name "/meta/a" will use the name "/meta" as metafile name and open it in append mode, the name "/meta/append" will open the file "/meta/append". Note that it is not possible to open a metafile named "anything/a" because the last part of the name will be interpreted as append mode flag. Metafile recording has two different modes: in SOFT mode the records stored into the metafile have a one to one correspondance to the AG routines calls (e.g. texts are stored as character strings, polylines vectors generated when in USER mode are stored in world coordinates, and so on). In HARD mode only the NORMALIZED coordinates polylines resulting from any kind of operation are stored (E.g. text will be stored as the generated sequence of polylines). The SOFT mode is usually more efficient and compact and suitable for storing data for subsequent redrawing, while HARD mode allows to redraw stored drawings into differently defined viewports (e.g. to produce hard copies of different dimensions and so on). Metafile recording mode can be set by a call to AGSSET with keywords MFHARD and MFSOFT. SOFT mode is the default. subroutine AGMOPN (fname) character*(*) fname Metafile name (see above) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- META Page 3 AGMRDW Redraw a metafile Redraws a previously generated metafile, i.e. all the commands stored in it are executed. The metafile must have been previously closed. subroutine AGMRDW (mfile) character*(*) mfile Name of metafile to redraw Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- META Page 4 AGMRES Resume metafile recording Resumes recording onto the metafile previously suspended by means of a call to AGMSUS function. subroutine AGMRES () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- META Page 5 AGMSUS Suspend metafile recording Temporarily suspends data recording onto the metafile associated to the current viewport. Recording can be resumed via a call to AGMRES. subroutine AGMSUS () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 1 AGDRIV Get Current driver configuration This routine outputs the current driver configuration onto the currently defined error soutput stream (se AGSSET, item ERROR, for error stream redirection). subroutine AGDRIV () Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 2 AGESC Device escape Escape standard AGL commands by sending a strictly device dependent command sequence to the device driver. Note: this function is provided for very specialized applications only and its use is HIGHLY NOT RECOMMENDED. The content of the string is only dependent on the device driver and AGL only provides for pass- ing it to the driver. Most driver will not support this feature and will return from this service with the UNSFEATINF return code subroutine AGESC (cmd,cmdlen) character*(*) cmd Command string (Max 132 bytes) integer cmdlen Command string length (Max 132) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 3 AGGERR Generate an error condition Generate an error condition. The error is treated as AGL generated errors with respect to message printing and process stopping (see AGSSET items: MSGALL,MSGWARN,MSGERR,MSGSEV,MSGNONE,STPERROR,STPNEVER,STPSEVERE). subroutine AGGERR (code,message) integer code Error code in the range Severity ranges: 0 - 99 informaton 100 - 199 warning 200 - 299 error 300 - 399 severe character*(*) message Error message Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 4 AGMAGN Rotate and translate a polyline This module multiplies every element of a couple of X-Y vectors by given factors. subroutine AGMAGN (xfact,yfact,xv,yv,np) real xfact,yfact Multiplying factors real xv(1),yv(1) Coordinate arrays integer np Array length Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 5 AGTROT Rotate and translate a polyline This module rotates and translates a couple of X-Y coordinate vectors In the rotation the different resolution along the two axes is taken into account The amount of translation and the rotation angle must be set via a call to AGTSET prior of the call to AGTROT and they will remain in effect until modified by another call to AGTSET. subroutine AGTROT (xv,yv,np) real xv(1),yv(1) Coordinate arrays integer np Array length Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 6 AGTSET Preset translation and angle for routine AGTROT This module presets parameters (translation amount and rotation angle) for routine AGTROT. The values remain into effect until modified with another call to AGTSET. subroutine AGTSET (xoff,yoff,angle,item) real xoff,yoff X and Y offset real angle Rotation angle (rad). integer item Specifies which items are to be modified. values can be: 0: do nothing. Xoff, yoff and angle ignored 1: modify X and Y offset only. Angle is ignored 2: modify angle only. Xoff anf yoff are ignored 3: modify X and Y offsets and angle Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 7 AGTRNS Defines a User specified coordinate transformation This call defines a User specified routine to be called by the AGL internal coordinate transformation program when the USER graphic mode is active. The call must also define an initialization routine. Coordinate transformations are applied according to selected graphic mode in the following order: Graphic Mode(s) Transformation Performed by USER or SPECIAL Logarithmic (when set) AGL SPECIAL User specified user provided routines USER or SPECIAL User to Normalized AGL The initialization routine will be called whenever a viewport switch is performed. It is provided in order to allow the calling program to set parameters needed by the transformation routine (e.g.: to modify scales which may be different for different viewports). In order to allow for specific data items needed for initialization to be stored together with viewport, data buffers for up to 10 float and 10 integer are provided within the viewport data area. Data can be stored by means of a call to AGRSET and AGISET when the transformation is set up. those values can be retrieved to be used by the initialization routine by calling AGRGET("user") and AGIGET("user"). The routines specified in the call must be defined as follow: subroutine my_init() integer my_transf(double *c0, double *c1) Direct transformation integer my_rtransf(double *c0, double *c1) Reverse transformation The direct and reverse transformation routines will return an integer value which encode the point position with respect to the user data window (the user data window is assumed to be rectangular in the space of the coordinates defined by the transformation) as shown in the following scheme: c0low c0up | | ret = 9 | ret = 8 | ret = 10 c1up ----------+----------+---------- ret = 1 | ret = 0 | ret = 2 c1low----------+----------+---------- ret = 5 | ret = 4 | ret = 6 | | The retuned value on error must be (-1) To reset the transformation you may call: AGTRNS(NULL,NULL,NULL) When data are stored into metafiles the user transformation information Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 8 is lost, so that redrawing will not be performed correctly (unless the HARD metafile mode is used). Note: this routine is callable through the C interface only subroutine AGTRNS (my_init,my_transf,my_rtransf) subroutine (*my_init)(); User initialization routine entry integer (my_transf)() User transformation routine entry integer (my_rtransf)() User inverse transformation entry Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 9 AGVN2U Normalized to user coord. conversion Convert an (x,y) couple of NORMALized coordinates into the corresponding USER coordinates. An information status is set if coordinates are outside the current clipping area. A warning status is set if coordinates are outside the current viewport. An error status is set if no window is currently defi- ned. subroutine AGVN2U (xpn,ypn,xu,yu) real xpn,ypn Normalized input coordinates real xu,yu User output coordinates Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- MISH Page 10 AGVU2N User to normalized coord. conversion Convert an (x,y) couple of USER coordinates into the corresponding NORMAL- ized coordinates. subroutine AGVU2N (xu,yu,xpn,ypn) real xu,yu User input coordinates real xpn,ypn Normalized output coordinates Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 1 AGAXES This module computes and draws axes on the currently active viewport. The position of the axes is computed so that quotes, labels and title will fit into the currently defined viewport A variety of options and axes drawing modes can be selected by means of an option selection string. After the call the clipping area is set so that it encloses the box defined by the axes. The window is defined accordingly to limits passed as arguments and the USER mode is selected. N.B.: Character dimensions and orientation as set prior of the call are not preserved subroutine AGAXES(xl,xu,yl,yu,option) real xl,xu,yl,yu User defined data window character*(*) option Option string (see below) Option string specifications: Syntax: "keywd[=value,value...][;keywd[=value...]]" Note: the keyword separator character ';' can be included into a string value by escaping it as in: "\;" Currently defined keyword and related specific sintax follows: BOLD Traces axes with thicker lines. Only axes are affected, if you also want labels written in bold face you must explicitly set it into the string with the standard AGL metacharacter sequence (~k). This feature is available only for devices supporting increased line width. DEGX DEGY Selects tiks position suitable for sexagesimal notation when automatic tik computing is enabled. It means that tik positions which are integral multiple of 3, 9, 1.5 and the like are selected. By default tik position at integral multiples of 1, 2, 5 are selected. DIVX=[start[,stop]] DIVY=[start[,stop]] Draw divisions and corresponding quotes only between given coordinates FACTX FACTY Specifies a multiplying factor for quotes. Numbers written at tick marks are computed as follows: Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 2 quote = offst? + ( coord * fact? ) where: coord is the coordinate value at the tik, fact? is the factor set with this command (? = either x or y) offst? is an offset value (see OFFSTX, OFFSTY) quote is the numerical value actually written at the tik Default is 1.0 FIXIT Forces the plot area (i.e.: the axes box) to cover exactly the current clipping area, instead of computing a new clipping area in order to fit all the plot (quotes, labels, title, included) in the clipping area. When using this mode the caller must define a clipping area suitably smaller than the current viewport if everything that must be plotted outside the clipping area (quotes and so on ) is to be seen GEOM Set geometrical control on the user data window. It means that the actual aspect ratio of the plot is set equal to the ratio: (ymax-ymin)/(xmax-xmin) GRID GRIDX GRIDY Specifies that a grid of lines is desired on the given axis instead of major tiks. LABX=string Specifies a label to be written under the x-axis. LABY=string Specifies a label to be written to the left of the y-axis. LOGX LOGY Select logarithmic transformation. Default is linear. MANX=mjstep[,mnstep] MANY=mjstep[,mnstep] Select manual definition of tik positions. Mjstep define the spacing of major divisions; mnstep define the spacing of minor divisions. If mjstep is <= 0.0, then no divisions are traced; if mnstep is not specified, minor divisions are not traced. If logarithmic transformation is selected for the axis, mjstep and mnstep are multiplicative increments for major and minor divisions, respectively. Mjstep must be a power of 10 (but not equal to 1.0), and mnstep may be either 5 or a power of 10 not equal to 1.0. The default is automatic tik computation. MARKX=ycoord MARKY=xcoord Traces a straight line (either parallel to X-axis or to Y-axis) at the given coordinate (if that's within the user data window). Often useful as, e.g., MARKX=0, to trace a line at the origin. NQUOTX Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 3 NQUOTY Suppresses quotes on the corresponding axis. OFFSTX OFFSTY Offset for quotes. Values written at tik marks are computed as: quote = offst? + ( coord * fact? ) where: coord is the coordinate value at the tik, fact? is the multiplicative factor (see FACTX, FACTY) offst? is an offset set with this command (? = either x or y) quote is the numerical value actually written at the tik Default is 0.0 TITLE=string Specifies a title to be written on top of the plot. TXDIM=mult Specifies a multiplying factor to apply to character, symbols and dash patterns. When TXDIM is specified the character dimension for labels, title and quotes is fixed as the given multiple of the device standard dimension. The default is to adjust string dimensions according to the dimension of the viewport. XSPACE=nchar Set the space (number of characters) left between the left Y axis and the Y axis label. Default is 5. Here follows a typical calling sequence: AGVDEF (.......) Define graphic device AGAXES(x0,x1,y0,y1,sel) Define and draw axes ... plot data .... AGCLS() Close AGL REMARKS: Title and label strings may contain AGL standard metacharacters for superscripts, subscripts and font definition (See: AGGTXT) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 4 AGAXIS This module draws an axis according to given specifications. The routine AGAXIS allows the user to design himself the layout of the axis, but the caller must carefully compute and provide all the required parameters. To get automatic positioning and quoting of axes use AGAXES instead. The routine AGAXIS will draw either horizontal or vertical axes in the currently active graphic mode. In order to draw axes with arbitrary orientation and scales the routine AGORAX() must be used, instead. subroutine AGAXIS(type,data,lspace,format,label) integer type Axis type and more specifications - Axis type selection: 0 = horizontal, quotes and label below 1 = vertical, quotes and label at right 2 = horizontal, quotes and label above 3 = vertical, quotes and label at left The value of the axis type can be or-ed with the following specification bits: 4 = Draw the axis with thicker line width 8 = Do not draw the axis line (supersedes the above value) 16 = draw the grid with solid line (default is dotted) 32 - Quotes are not centered on tick, but sligtly displaced real data(1) Array of specifications, with the following meaning: (N.B.: array base is 0 for C and 1 for Fortran !!) [0] Axis starting coordinate. [1] Axis ending coordinate. N.B.: data[0] < data[1] if(data[0]==data[1]) no axis or ticks are plotted, but only quotes [2] Divisions (ticks) starting coordinate. This may differ from the axis starting coordinate if the latter is not at an even multiple of the division step. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 5 [3] Divisions (ticks) ending coordinate. This may differ from the axis ending coordinate if the latter is not at an even multiple of the division step. N.B.: data[2] < data[3] [4] Step distance between major ticks or grid lines. If <= 0.0 no ticks or grid lines will be drawn. If the logarithmic option is selected it is a multiplicative factor. [5] Step distance between minor ticks or If <= 0.0 no minor ticks will be drawn. If the logarithmic option is selected it is a multiplicative factor. [6] Constant position of this axis along the other coordinate. [7] Constant position of the ending points of grid lines along the other coor- dinate(i.e., usually, the position of the parallel opposite axis). If data[6] is equal to data[7], ticks are drawn instead of grid lines. [8] Offset for quotes: see [9]. [9] Multiplying factor for quotes. Major ticks are drawn at the requested positions, and the corresponding quote values are computed as: quote = data[8] + position*data[9] before they are actually drawn. To get quotes in the usual way (i.e.: numbers exactly corresponding to coordinates) you must specify: data[8]=0.0, and data[9]=1.0. N.B.: if data[9] is equal to 0.0, no quotes are drawn. [10] An exponent value to be removed from quotes. I.e. if data[10] is not equal to 0.0 all quotes are further divided by 10**data[10] and the exponent is written in a suitable place close to the end of the axis. real lspace Space left between the axis and the label It is expressed as an lspace number of characters in the current dimension. If 0.0 it is computed accordingly to current length of quotes Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 6 character*(*) format Format specification to draw quotes The string may contain some standard C format specifications PLUS a set of special ones as listed below (standard specifica- tion are marked with (C) and special with (S)) If the string has not the '%' as first character quotes are not drawn %[w.p]d (C) : Decimal integer %[w.p]f (C) : Floating point %[w.p]e (C) : Exponential format w=width, p=precision %g (S) : as the %f above, but strips all trailing zeroes and deci- mal point (not the same as the C standard %g format!) %p (S) : Writes only the power of 10 %x (S) : Writes only the power of e %au (S) : Degrees %aum (S) : Degrees minutes %aums (S) : Degrees minutes seconds %ams (S) : minutes seconds %amss (S) : minutes seconds fraction %hu (S) : Hours %hum (S) : Hours minutes %hums (S) : Hours minutes seconds %hms (S) : minutes seconds %hmss (S) : minutes seconds fraction NOTE: Add more s' to the end of the format string to get more fraction digits character*(*) label String to be drawn as label. If the string is empty, obviously no label is drawn. Note: quotes and label are both drawn in the current setting of character strings (see AGSSET for details on how to set various items affecting how characters are drawn), and with the same char- acter size. You can modify the way the label is drawn by means of the standard AGL metacharacter sequences (see AGGTXT) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 7 AGFILL Polygon filling routine This module will draw a pattern of lines within a polygon of specified vertexes. The contour of the polygon itself is not drawn and if desired It may be drawn explicitly by a call to AGGPLG. The coordinate values are referred to the current graphic mode (either NORMALIZED, USER or SPECIAL) and mapped accordingly. Graphic mode is affected by: AGWDEF, AGTRNS, and AGSSET items "NORMAL","USER" and "SPECIAL". Anyway the "SPECIAL" coordinate mode will NOT produce a proper drawing because the routine assumes that the sides of the polygon are straight lines. subroutine AGFILL(x,y,n,space,angle,sset) real x(1),y(1) Coordinate arrays integer n real space Spacing between filling lines. Lines of pattern will be spaced "spacing" times the basic char width. if Spacing = 0.0, the spacing will be set so that the polygon is filled completely. Note: filling with double line width will usually prodice best results. Also note that this feature may be pretty slow. real angle Angle of filling lines with respect to X-axis character*(*) sset A command string which will be used in a call to AGSSET prior of drawing. It may be used to set various items such as line width and style, colours and so on. This argument is placed here for convenience in that it has exactly the same effect as calling AGSSET(sset) before calling AGFILL. See AGSSET for specifications. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 8 AGHIST This module draws various forms of histogram plots from a couple of coordinate vectors. NOTE: a window must be defined and the mode USER must be selected before calling AGHIST (see: AGWDEF and AGSSET). Here follows a typical calling sequence for histogram plotting: AGVDEF (.......) Define graphic device AGAXES(x0,x1,y0,y1,sel) Define and draw axes AGHIST(xv,yv,np,0,0) Draw the histogram from data in vectors xv,yv (length=np) AGCLS() Close AGL subroutine AGHIST(xv,yv,np,mode,join) real xv(1),yv(1) Coordinate arrays integer np Array length integer mode Histogram type selection. Types available are the following: mode=0 simple staircase. mode=1 staircase steps joined to x-axis. mode<=2 data points joined to x-axis with boxes (current line width and style) with width starting from 0 (simple line) and increasing with mode value in steps of small character width integer join Flag to join more than one call into a single histogram (used with modes: 0, 1) join=0 : histogram closed at both ends. (used when all data points are plotted with a single call) join=1 : histogram opened at the right end (used for the first block of an histogram built with many calls) join=2 : histogram opened at the left end (used for the final block of an histogram built with many calls) join=3 : histogram opened at both ends (used for the middle blocks of an histogram built with many calls) N.B.: when using the join feature to plot a long histogram built up with pieces DO NOT intermix calls to other AGL routines between calls to AGHIST. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 9 AGNLIN This module computes and draws a grid on the currently active viewport using one of a set of non-linear coordinate projections. The position of the grid is computed so that quotes, labels and title will fit into viewport. A variety of options and axes drawing modes can be selected by means of an option selection string, this will also select the actual projection to be applied. After the call the the selected projection will remain active, so that subsequent graphic operations will be referred to the selecte corrdinate system. After the plot is drawn, the box enclosing it may be addressed by re- storing the cartesian transformation via a call: AGTRNS(NULL,NULL,NULL) After the call the graphic status will be "USER" and a window suitable to enclose the polar plot is selected (see also WINDOW below) N.B.: Character dimensions and orientation as set prior of the call are not preserved subroutine AGNLIN(c1l,c1u,c2l,c2u,select) real c1l,c1u User window limits on first axis Limits depend on the actual transformation selected. real c2l,c2u User window limits on second axis Limits depend on the actual transformation selected. Actual axes meaning depends on the particu- lar projection selected. Angular values are interpreted as Radians by default, but it can be changed to Degrees or Hours (See items: DEG and HOUR below) character*(*) select Option string (see below) Option string specifications: Syntax: "keywd[=value,value...][;keywd[=value...]]" The keyword spacifying the type of transformation is required, it must be one of the following: AITOFF Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 10 Selects the transformation: X=2*cos(c2)sin(c1/2)/d Y=sin(c2)/d with: d=sqrt((1+cos(c2)cos(c1/2))/2) This transformation will map the sphere onto an ellipse with conser- vation of surfaces When this transformation is selected the user window arguments are only used in order to determine the center of the projection, the projection limits will always be [-180,+180] degrees on first axis and [-90,+90] on the second axis. ARC Selects the arc transformation (Schmidt plates projection) X=(sin(c1)cos(c2))*acos((cos(c1)cos(c2)))/d Y=sin(c2)*acos((cos(c1)cos(c2)))/d where: d=sqrt((sin(c1)cos(c2))**2+sin(c2)**2) GLS Selects the Global Sinusoidal transformation: X=c1*cos(c2) Y=c2 This transformation will map the sphere into two opposite sinusoids GNOMONIC Selects gnomonic transformation: X=((sin(c1)cos(c2))/(cos(c1)cos(c2))) Y=(sin(c2)/(cos(c1)cos(c2))) The transformation is centered in the center point of the defined data window. Limits: (maxc1 - minc1) < pi (maxc2 - minc2) < pi MERCATOR Selects the Mercator transformation: X=c1 Y=atanh(sin(c2)) POLAR Selects polar Transformation. X=c1*cos(c2) Y=c1*sin(c2) Limits: 0 < minc1 < maxc1 Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 11 S2 selects the sin2 transformation: X=(sin(c1)cos(c2))*sqrt(2/(1+(cos(c1)cos(c2)))) Y=sin(c2)*sqrt(2/(1+(cos(c1)cos(c2)))) This transformation will map the sphere onto a circle SIN Selects the Sin transformation: X=(sin(c1)cos(c2)) Y=sin(c2) STEREO Selects the stereographic transformation: X=(2(sin(c1)cos(c2))/(1+(cos(c1)cos(c2)))) Y=(2*sin(c2)/(1+(cos(c1)cos(c2)))) The following keywords are not required in that suitable defaults are provided: DEG DEG1 DEG2 Select interpretation of values on the selected axis (or both) to degrees. Default interpretation depends on the particular transformation selected. DIV1=[start[,stop]] DIV2=[start[,stop]] Draw divisions and corresponding quotes only between given coordinates FACT1 FACT2 Specifies a multiplying factor for quotes. Numbers written at tik marks are computed as follows: quote = offst? + ( coord * fact? ) where: coord is the coordinate value at the tik, fact? is the factor set with this command (? = either 1 or 2) offst? is an offset value (see OFFST1, OFFST2) quote is the numerical value actually written at the tik Default is 1.0 FIXIT Forces the plot area (i.e.: the axes box) to cover exactly the current clipping area, instead of computing a new clipping area in order to fit all the plot (quotes, labels, title, included) in the clipping Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 12 area. When using this mode the caller must define a clipping area suitably smaller than the current viewport if everything that must be plotted outside the clipping area (quotes and so on ) is to be seen HOUR HOUR1 HOUR2 Select interpretation of values on the selected axis (or both) to hours. Default interpretation depends on the particular transformation selected. LABB=string Specifies a label to be written on the bottom of plot LABL=string Specifies a label to be written to the left of plot LOG LOG1 LOG2 Select logarithmic transformation on the selected axis (or both) Default is Linear MAN1=mjstep[,mnstep] MAN2=mjstep[,mnstep] Select manual definition of tik positions. Mjstep define the spacing of major divisions; mnstep define the spacing of minor divisions. If mjstep is <= 0.0, then no divisions are traced; if mnstep is not specified, minor divisions are not traced. If logarithmic transformation is selected for the axis, mjstep and mnstep are multiplicative increments for major and minor divisions, respectively. Mjstep must be a power of 10 (but not equal to 1.0), and mnstep may be either 5 or a power of 10 not equal to 1.0. The default is automatic tik computation. NGRID NGRID1 NGRID2 do not draw grid lines along the corresponding axis NQUOT NQUOT1 NQUOT2 Suppresses quotes on the corresponding axis. OFFST1 OFFST2 Offset for quotes. Values written at tik marks are computed as: quote = offst? + ( coord * fact? ) where: coord is the coordinate value at the tik, Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 13 fact? is the multiplicative factor (see FACTR, FACTT) offst? is an offset set with this command (? = either x or y) quote is the numerical value actually written at the tik Default is 0.0 QDEG QDEG1 QDEG2 Select degrees format for quotes on angular valued axis It also affects preferred tiks positions when automatic tik computing is enabled. Default format depends on the particular transformation selected. QHOUR QHOUR1 QHOUR2 Select hour format for quotes on angular valued axis Default format depends on the particular transformation selected. QRAD QRAD1 QRAD2 Select radiant format for quotes on angular valued axis It also affects preferred tiks positions when automatic tik computing is enabled. Default format depends on the particular transformation selected. RAD RAD1 RAD2 Select interpretation of values on the selected axis (or both) to radiants. Default interpretation depends on the particular transformation selected. TITLE=string Specifies a title to be written on top of the plot. TXDIM=mult Specifies a multiplying factor to apply to all text strings WINDOW=xmin,xmax,ymin,ymax Specifies limits for the cartesian window. E.g.: WINDOW=-1,1,-1,1 would enclose all the four quadrants of a polar plot, WINDOW=0,1,0,1 would enclose the first quadrant only, and so on. By default the window limits are automatically adjusted. Here follows a typical calling sequence: AGVDEF (.......) Define graphic device AGNLIN(r0,r1,t0,t1,"polar") Define and draw axes Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 14 ... plot data .... AGCLS() Close AGL REMARKS: Title and label strings may contain AGL standard metacharacters for superscripts, subscripts and font definition (See: AGGTXT) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 15 AGORAX This module draws an axis of given orientation. The routine AGORAX allows the drawing of an axis with arbitrary orientation angle. The axis scales and quotes are defined independently of the current graphic status. To draw horizontal or vertical axes with a greater detail of specifica- tion the AGAXIS() routine can be used instead. subroutine AGORAX(flags,ends,data,form,label) integer flags Specification flags. The inclusive or of the following values: 1 - Draw ticks below the axis (Default is above). Quotes are drawn on the opposite side of the axis 2 - Draw tiks with specified angle (see data[6]). Default is to make tiks perpendicular to the axis. Setting flag 1 above, will add 180 degrees to the specified angle; i.e. with the same angle value tiks are drawn in the opposite direction when flag 1 is set. 4 - Draw quotes parallel to the axis. The default is to draw quotes always horizontally. real ends(1) Axis starting and ending points: (ends[0],ends[1]) = (xstart,ystart) (ends[2],ends[3]) = (xend,yend) Values are referred to the currently active coordinate system real data(1) Array of specifications, with the following meaning: (N.B.: array base is 0 for C and 1 for Fortran !!) The following values are independent on the active coordinate system. [0] Axis starting point coordinate [1] Axis ending point coordinate. N.B.: data[0] < data[1] Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 16 [2] Divisions (ticks) starting coordinate. This may differ from the axis starting coordinate if the latter is not at an even multiple of the division step. [3] Divisions (ticks) ending coordinate. This may differ from the axis ending coordinate if the latter is not at an even multiple of the division step. N.B.: data[2] < data[3] [4] Step distance between major ticks or grid lines. If <= 0.0 no ticks or grid lines will be drawn. If the logarithmic option is selected it is a multiplicative factor. [5] Step distance between minor ticks or If <= 0.0 no minor ticks will be drawn. If the logarithmic option is selected it is a multiplicative factor. [6] Tiks drawing angle. This value has effect only if flag 2 is set (see above). The angle must be given in the proper units (see: AGSSET, items DEGREES and RADIANS) and with respect to the currently defined coordinate system, independently on the actual aspect ratio of the vieport. E.g. while in user mode with a window defined as AGWDEF(0.,10.,0.,10) specifying an angle of 45 degrees will result in tik marks parallel to the diagonal of the window. To obtain the same result with a window defined as: AGWDEF(0.,10.,0.,1) will require to specify an angle of 5.71 degrees (it corresponds to atan(1/10)) character*(*) form Format specification to draw quotes The string may contain some standard C format specifications PLUS a set of special ones as listed below (standard specifica- tion are marked with (C) and special with (S)) If the string has not the '%' as first character quotes are not drawn %[w.p]d (C) : Decimal integer %[w.p]f (C) : Floating point %[w.p]e (C) : Exponential format w=width, p=precision Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- HIGH Page 17 %g (S) : as the %f above, but strips all trailing zeroes and deci- mal point (not the same as the C standard %g format!) %p (S) : Writes only the power of 10 %x (S) : Writes only the power of e %au (S) : Degrees %aum (S) : Degrees minutes %aums (S) : Degrees minutes seconds %ams (S) : minutes seconds %amss (S) : minutes seconds fraction %hu (S) : Hours %hum (S) : Hours minutes %hums (S) : Hours minutes seconds %hms (S) : minutes seconds %hmss (S) : minutes seconds fraction NOTE: Add more s' to the end of the format string to get more fraction digits character*(*) label String to be drawn as label. If the string is empty, obviously no label is drawn. Note: quotes and label are both drawn in the current setting of character strings (see AGSSET for details on how to set various items affecting how characters are drawn), and with the same char- acter size. You can modify the way the label is drawn by means of the standard AGL metacharacter sequences (see AGGTXT) Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- ERRORS Page 1 AGL ERROR CODES NOTE: codes in the range 1..99 are INFORMATION codes in the range 101..199 are WARNINGS codes in the range 201..299 are ERRORS codes in the range 301..399 are SEVERE ERRORS INFOTRSH 0 Information threshold WARNTRSH 100 Warning threshold ERRTRSH 200 Error threshold SEVTRSH 300 Severe error threshold MAXERRCD 399 Max error code from AGL SYMB.NAME CODE DESCRIPTION AGLNOERR (-1) No error ++ UNSFEATINF 2 Unsupported feature (information). Requested operation cannot be performed because the required optional feature is not supported by the device driver. CLPOUTINF 3 Coordinate out of current clipping area. The result of a coordinate conversion yields a point which lies outside the clipping area. NOPIXINF 4 Pixel value in locator not available. Returning of pixel value corresponding to given locator position is an optional feature and may not be supported by some device drivers. TOOMANYINF 5 Too many parameters. Too many parameters have been specified. See the called routine documentation to know the maximum number of parameters allowed. ILLBOUWNG 101 Illegal bounds requsted to routine. Viewport bounds must be in the range [0.0 1.0], upper bound on any axis must be greather than the corresponding lower bound. Clipping area bounds must be within the viewport bounds. CMDBOVFWNG 102 Device close command too long for AGL buffer. Command associated to the device description in the configuration file agldevs.dat is too long. ILLCLRWNG 103 Error in color/pen request. Required color or pen is not available for the given device, or the color specification is not legal. The color is not changed. DEVCMDWNG 104 Close command execute error. Execution of the device close command associated with the device type in the file agldevs.dat results into an error condition. STRCLPWNG 105 Text string clipped. The text string passed to the module is too long, It is truncated to the maximum allowed length. LOCCLPWNG 106 Locating device outside viewport. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- ERRORS Page 2 The position of the locator lies outside the current viewport. ERRFILWNG 107 Error opening error log file. The requested redirection of AGL run time errors to the specified file is not performed. ILLCODWNG 108 Illegal request code. Check AGL User's Guide for a list of currently currently defined request codes for the called module. ILLMRKWNG 109 Illegal marker specifier. Marker symbol specification is outside the cur- rently defined range. See AG_GPLM documentation in the AGL User's Guide. SETSYNWNG 110 AG_SSET string syntax error. Check the string passed to AG_SSET for syntax errors. MFEOFWNG 111 Unexpected end of file on input metafile The metafile was probably improperly closed. VECLNGWNG 112 Illegal vector length in AG_GPLx. Zero or negative vector length is illegal for AG_GPLM, a length less than or equal to 1 is illegal for AG_GPLL. MFNOTWNG 113 No Metafile is currently active. A metafile must be currently active to allow the requested operation. MFACTVWNG 114 Metafile is already active. An attempt to open or activate a metafile when another metafile is already active has been made. STRSTXWNG 115 Illegal string syntax. Usually due to misuse of metacharacter sequences or to unexpected end of string (i.e. untermina- ted metacharacter sequence). ILLPOSWNG 116 Illegal TEXT position specifier. Check AGL User's Guide for legal values of the text string relative position specifier. ASPECTWNG 117 Illegal aspect ratio request. The requested aspect ratio is well beyond any reasonable value. ILLFONTWNG 118 Illegal font name or number. The font specification is illegal or the font file cannot be read. Default font is selected. UNSFEATWNG 119 Unsupported feature (warning). Requested operation cannot be performed because the required optional feature is not supported by the device driver. VWPOUTWNG 120 Coordinate outside the current viewport. Coordinate values resulting from the operation are outside the currently defined viewport ILLSETWNG 121 Illegal value for parameter An illegal value was specified for the parameter to be set. TOOMANYWNG 122 Too many parameters. Too many parameters have been specified! See the called routine documentation to know the maximum number of parameters allowed. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- ERRORS Page 3 POSCNVERR 202 Coordinate conversion error. Coordinate conversion cannot be performed due to computation errors (e.g.: log(negative)). NOWNDERR 203 Window is undefined (ERROR). The requested operation cannot be performed if the user window has not been previously defined (see AG_WDEF). ILLWNDERR 204 Illegal window bounds. Requested user window bounds cannot be set (e.g: negative values with log scaling in effect). NOVWPERR 205 No viewport is currently active. The requested operation cannot be performed if a viewport has not been previously opened (see AG_VDEF). UNSFEATERR 206 Unsupported feature (error). Requested operation cannot be performed because the required optional feature is not supported by the device driver. ILLDEVERR 207 Illegal device specifier. The requested device specifier is not known to AGL. Check for possible misspelling in device name, wrong definition either into agldevs.dat files or into environment variables. You must understand AGL device naming conventions (refer to AGL User's Guide and to AGL Installation and Customization Guide). NOLOGERR 208 Log.transf. not applicable on current window. Logarithmic transformation cannot be applied to currently defined user window (e.g: because of zero or negative bounds). NOARGERR 209 Required argument not specified in the call. Some device drivers will return this error VWPSELERR 210 Illegal viewport identifier. The requested viewport has not been previously defined. BUFOVFERR 211 Escape command buffer overflow. Device specific command is longer than related buffer. See AG_ESC in the AGL User's Guide for max allowed length. ILLCLPERR 212 Illegal clipping area definition. Clipping area bounds must be contained within the viewport, lower bound must be less than upper bound. MFILLCDERR 214 Illegal metafile code. Either the metafile is corrupted, or it may have been generated by older versions of AGL. MFOPENERR 215 Error opening metafile. Check the file name, reading rights on the de- vice, etc. MFCLOSERR 216 Error closing metafile. Close error is usually due to O.S. problems. MFWRITERR 217 Error writing onto metafile. Check for device full, device failure, etc. MFREADERR 218 Error reading from input metafile. Read errors are usually due to O.S. problems. MFFMTERR 219 Specified file is not a standard AGL metafile. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- ERRORS Page 4 Standard AGL metafile header has not been found at the beginning of the file: this is not an AGL metafile. NODEVICE 220 No device specified at viewport definition. The device specification string in the AG_VDEF call doesn't contain any recognizable device na- me. FNTNUMERR 221 Given font number is not defined. Check AGL User's Guide for legal values of the font specifier (see AG_SSET or AG_GTXT). FNTFILERR 222 Error opening font file. This may be due to incorrect installation of AGL. Refer to AGL Installation and Customization Guide. Also check read permission to the font files on the standard AGL directory. MEMORYERR 223 Error allocating memory (not enough space). Many dynamic structures are allocated when need- ed. Your program is too big to allow the opera- tion. You may try to kill unused viewports or to avoid to use character fonts other than the de- fault. FNTRDERR 224 Font file read error. Read errors are usually due to O.S. problems. USRTRSERR 225 Error in user defined transformation. The user defined coordinate transformation returns with an error condition. The origin of the error depends on the transformation currently active. MODEERR 226 Set mode error. The selected graphic mode cannot be set, probably because the SPECIAL mode was selected without a previous call to AG_TRNS() for setting the special user transformation RANGEERR 227 Range error. Some argument passed to the module is outside required range ILLDRVSEV 301 Illegal driver version. The accessed driver has not version greater than 34. You shouldn't get this error code when using officially supportde AGL drivers. You might get it, anyway, if you're using a locally developed device driver. DEVIOSEV 302 Unspecific I/O error on graphic device. I/O error when reading from or writing to a de- vice are usually due to O.S. problems. DEVOPNSEV 303 Device open error. The device cannot be opened. Check for access rights, then ask the system manager. VWPOVFSEV 304 Too many viewports active. There is a system limitation on the number of viewports which can be opened concurrently. Try to kill unused ones (see AG_VKIL in AGL User's guide). UNUSED005 305 Currently unused code. Oct 26 09:19 1994 AGL Fortran Interface - Vers. 3.61 -- ERRORS Page 5 You should not get this error message !! Be sure you're using the correct AGL version. CNFOPNSEV 306 Error opening agldevs.dat file Either AGL was not properly installed or you have not read access to the file. CAPOPNSEV 307 Error opening caps file. Either AGL was not properly installed or you have not read access to the file. CAPRDSEV 308 Error reading caps file. Read errors are usually due to O.S. problems, such as access conflicts and the like, but check also for possible syntax errors within the file, if it is not provided in the standard AGL kit. DEVOVFSEV 309 Too many devices concurrently active. You may try to kill all viewports connected to unused devices. UNDDRVSEV 310 Device driver name cannot be found. The required device driver is not installed. You must check for misspellings in the agldevs.dat files. Then you may get a list of installed dri- vers (see AG_DRIV in AGL User's Guide). If the required driver is supported you may follow di- rections in AGL Installation and Customization Guide to include it into your configuration. CHGBUFOVSEV 311 Character generator polyline buffer overflow. This problem must be reported to the author for a check of the consistency of the character ge- nerator code. NOTIMPLSEV 312 Module not implemented yet. The called module has not yet been implemented. ILLCHGSEV 313 Inconsistent definition of character. The character generator is not well formed. If Any of the loadable character fonts is in use this may depend on a bad definition in the font file (named *.nfn). Check for possible corrup- tion of font files on the AGL standard directory (files *.nfn). MEMALLOCSEV 314 Memory allocation error Somewhere in AGL a memory allocation request has failed. Maybe your program is too big!