NAG Graphics Library, Mark 4 GLUNX04SA (GLUNX04S) Generic UNIX Single Precision Users' Note Contents 1. Introduction 2. NAG Graphical Software 3. General Information 3.1. Accessing the High-level Library and Interfaces 3.2. Initialisation of Underlying Plotting Package 3.3. Output from Graphics Library Routines 3.4. Interpretation of Bold Italicised Terms 3.5. Example Programs 3.6. User Documentation 3.7. Naming of Routines 4. Routine-specific Information 4.1. J06AQE 4.2. Constants 4.3. Auxiliary Routines 5. Interface-specific Information 5.1. DEC ReGIS 5.2. Hewlett Packard HPGL 6. Additional Services from NAG 7. Support from NAG 8. NAG Users Association 1. Introduction This document is essential reading for every user of the NAG Graphics Library Implementation specified in the title. It provides implementation-specific detail that augments the information provided in the NAG Graphics Library Reference Manual. NAG recommends that users read the following minimum reference material before calling any library routine: (a) Essential Introduction (b) Chapter Introduction (c) Routine Document (d) Implementation-specific Users' Note Items (a), (b) and (c) are included in the NAG Graphics Library Reference Manual; item (d) is this document. Each NAG Graphics Library Service site is supplied with at least one copy of each of the above. Please ask your NAG Site Contact for further information. 2. NAG Graphical Software The NAG Graphics Library can be considered to consist of three distinct parts: high-level graphics routines, low-level routines and support routines. When calling the NAG Graphics Library to draw a contour map or graph you are invoking what are termed 'high-level' or package-independent graphics routines. These are written in terms of a small set of primitive, or 'low-level', routines known collectively as the NAG Graphical Interface. NAG Graphical Interface routines in turn call routines in a locally available plotting package, and perform such functions as drawing a line or changing the current text font. The support routines are a subset of the routines available in the NAG Fortran or Foundation Libraries, and hence are optional if one of those Libraries is available at an installation, but are needed otherwise to ensure that the NAG Graphics Library is complete. There is a version of the NAG Graphical Interface for each plotting package (or protocol) supported. The Interface translates drawing requests into a form which can be accepted by the underlying plotting software. As an appropriate interface is selected at link time, only one version of an application program need be written and maintained. Irrespective of the plotting software used, all routines in the NAG Graphical Interface have the same parameter sequence. The main new feature at Mark 4 is the improved text handling. The following capabilities have been included: (a) Hershey fonts have been included, guaranteeing the presence of fully scalable fonts irrespective of the underlying plotting software used. As the plotting of Hershey font characters is fully under control of the NAG Graphics Library, it was also possible to introduce the use of proportional spacing for these fonts. Several Greek alphabet fonts and a mathematical symbols font are perhaps the most significant among a total of 25 Hershey fonts supplied as part of Mark 4. (b) Strings to be plotted may include keywords; this facilitates the plotting of subscripts and superscripts and in-line changing of fonts, as well as typesetting of fairly complex mathematical formulae. (c) Character strings may be plotted along an arbitrary (i.e. non-horizontal) direction, with the base line of individual characters pointing in the same direction. This is useful for example in the plotting of y axis labels which no longer need to be plotted as `hotel signs'. (d) Definition of character size may be independent of the user co-ordinates currently in force; character size and spacing may now be defined as a fraction of the maximum plotting area, in addition to the method of defining them in terms of user co-ordinates. This enables the use of fixed size character strings which are the same for plots which may have different user co-ordinates and/or viewport sizes. (e) Text may be aligned in relationship to the current point; text can begin (left-justified), end (right-justified) or be centred at the current pen position. (f) Text may be underlined. Further improvements to the presentational aspects of the Library have been made by allowing user-specified margins and the plotting of axis labels on all sides of the plots (rather than to the left-hand side and bottom only). The high level code was extensively revised to make full use of the new features introduced. The NAG Graphics Library, Mark 4 is distributed with the following interfaces. Please note that not all of them may have been installed. aps - Adobe PostScript Interface dcr - DEC ReGIS Interface gks - GKS Interface gli - GL Interface hpg - HPGL Interface lpr - NAG Lineprinter Interface X11 - X11 Interface 3. General Information 3.1. Accessing the High-level Library and Interfaces A user's compiled program will need to be linked with the following libraries (in the given order): - NAG Graphics Library high-level routines (/usr/lib/libnaggl04s.a) - NAG Graphical Interface Library (e.g. /usr/lib/libnaggkss.a) - NAG Fortran support routines (/usr/lib/libnagflss.a or the NAG Fortran or Foundation Libraries) - underlying Graphics package (e.g. GKS) For example, to compile, link and execute the program, driver.f, using data, driver.d, and using the PostScript Graphical Interface, the steps would be: f77 -o driver driver.f -lnaggl04s -lnagapss -lnagflss driver < driver.d The default output channel for the PostScript interface (and similarly for any of the interfaces that generate command output) is specified by J06VCE (See Section 4.2). 3.2. Initialisation of Underlying Plotting Package Usually the first step when using a graphics package is to initialise the system and/or select a particular graphical output device. Users must make an explicit call to the local graphics software to perform this step, before calling any NAG graphical routine. The Interface Usage section of the NAG Graphics Library Reference Manual gives recommended initialisation statements. However, for generality, the example programs contain the dummy initialisation statement: CALL XXXXXX Users who adapt the example programs for their own use must replace this statement by an appropriate initialisation call if local versions of XXXXXX have not been established at installation time. 3.3. Output from Graphics Library Routines It is important to note that a file must always be attached to the current error and warning message units (see routines J06VAE and J06VBE), even when graphs are the only expected output. This is because warning messages may be output by some interface routines if they are called with invalid parameters and error messages may be output by some high-level routines when an error condition is detected. Additionally, if the Lineprinter interface is in use then plots are output on the current advisory message unit (see routine J06VBE). Command sequence output may also be produced by the DEC ReGIS, HPGL and Adobe PostScript interfaces (see routine J06VCE). Some routines for contouring or the plotting of the solution of ordinary differential equations use option-setting facilities. Routine J06VEE specifies the unit number of any corresponding option-setting SAVE file. 3.4. Interpretation of Bold Italicised Terms For this implementation, the bold italicised terms used in the NAG Graphics Library Reference Manual (and shown here as //.....//) should be interpreted as: //basic precision// - single precision //real// as a type declarator - REAL //real// as an intrinsic function name - REAL //e// in constants, e.g. 1.0//e//-4 - E, e.g. 1.0E-4 //e// in formats, e.g. //e//12.4 - E, e.g. E12.4 Thus a parameter described as //real// should be declared as REAL in the user's program. 3.5. Example Programs The example programs published in the NAG Graphics Library Reference Manual are presented in a generalised form, using bold italicised terms as described in Section 3.4. The programs supplied to a site in machine-readable form have been modified as necessary to run on this system. They are suitable for immediate execution, except for initialisation of the underlying plotting package (see Section 3.2). Users of DEC ReGIS, HPGL or PostScript interfaces may also need to include a call to J06VCE to direct the resultant command sequences to a chosen Fortran unit. 3.6. User Documentation The following machine-readable information files are provided by NAG on the library release medium. Please consult your local advisory service or NAG Site Contact for further details: un - Users' Note (this document) summary - a brief summary of the routines calls - a list of routines called directly or indirectly by each routine in the library, and by each example program called - for each routine in the library (including auxiliaries) this gives a list of those routines and example programs which call it directly or indirectly. 3.7. Naming of Routines To ensure a single precision implementation is completely distinct from any double precision version also available, all single precision routine names have been modified by changing the sixth character from F to E. Thus, for example: J06AAF denotes the double precision version J06AAE denotes the single precision version The names of auxiliary routines have also been modified by interchanging the first three and the last three characters, e.g. J06AAJ has been changed to AAJJ06. In the NAG Graphics Library Reference Manual all library routine names end in F. Therefore, when using the manual in conjunction with this single precision implementation, all such names must be understood to refer to the single precision versions with names ending in E. Some routines in the Library require users to specify particular auxiliary routines. Again, when using this implementation it is necessary to specify the amended names, as given in Section 4.3 of this note. The names of COMMON blocks have also been modified, e.g. AJ06AA is renamed AAJ06A. This is unlikely to affect the user. 4. Routine-specific Information 4.1. J06AQE Users are warned that axis annotation produced by J06AQE may show variations in tick mark positioning and numbering on different systems. This is due to differences in machine precision. 4.2. Constants Graphics Library routines make use of the following implementation-dependent constants: J06VAE = 0 (site dependent) J06VBE = 6 (site dependent) J06VCE = 7 (site dependent) J06VEE = 8 (site dependent) X02AJE = 5.96046D-08 (machine dependent) X02AKE = 1.17549D-38 (machine dependent) X02ALE = 3.40282D+38 (machine dependent) X02AME = 1.17549D-38 (machine dependent) X02BBE = 2147483647 (machine dependent) X02BEE = 6 (machine dependent) X02DAE = .FALSE. (machine dependent) 4.3. Auxiliary Routines Some routines in the Library require users to specify particular auxiliary routines. For this single precision implementation the auxiliary routine names have been changed from those specified in the NAG Graphics Library Reference Manual, as follows: J06GBE - Auxiliary routines J06GBU, J06GBV, J06GBW, J06GBY and J06GBZ have been renamed GBUJ06, GBVJ06, GBWJ06, GBYJ06 and GBZJ06 respectively. J06GDE - Auxiliary routines J06GBU, J06GBV, J06GBW, J06GBY and J06GBZ have been renamed GBUJ06, GBVJ06, GBWJ06, GBYJ06 and GBZJ06 respectively. J06GGE - Auxiliary routines J06GGY and J06GGZ have been renamed GGYJ06 and GGZJ06 respectively. 5. Interface-specific Information The in-string keyword delimiter referred to in the Details of Plot Control section of the NAG Graphics Library Reference Manual is the exclamation mark ('!'). 5.1. DEC ReGIS The form and standard use of the ReGIS instruction set does not lend itself to easy incorporation into Fortran code. It has, therefore, been necessary to develop a set of emulator routines for this Interface. This should not affect the user, except that the names used for these routines should not be duplicated. Details of the 'reserved names' can be found in the DEC ReGIS Interface Usage section of the the NAG Graphics Library Reference Manual. 5.2. Hewlett Packard HPGL The form and standard use of the HPGL instruction set does not lend itself to easy incorporation into Fortran code. It has, therefore, been necessary to develop a set of emulator routines for this Interface. This should not affect the user, except that the names used for these routines should not be duplicated. Details of the 'reserved names' can be found in the Hewlett Packard HPGL Interface Usage section of the NAG Graphics Library Reference Manual. 6. Additional Services from NAG (a) Printed Manuals Where a manual has been provided as part of the contract issue, this manual is updated automatically at each new release of the software, by the supply of a manual update set or a complete new manual. If additional manuals have been ordered in the past then updates to these manuals may be ordered separately. They are NOT sent automatically. Additional complete manuals and the manual updates (where relevant) are available at prices published in the NAG documentation order form. (b) On-line Information Supplement To complement the manuals NAG produces an On-line Information Supplement which fulfills two roles: - it gives key-word-driven guidance on the selection of the appropriate NAG routine - it gives abbreviated on-line documentation of the NAG routines, to enable the user to call the routines and investigate any IFAIL messages without recourse to the manual. 7. Support from NAG (a) Contact with NAG Queries concerning this document or the implementation generally should be directed initially to your local Advisory Service. If you have difficulty in making contact locally, you can write to NAG directly, at one of the supplied addresses. Users subscribing to the support service are encouraged to contact one of the NAG Response Centres (see below). (b) NAG Response Centres The NAG Response Centres are available for general enquiries from all users and also for technical queries from sites with an annually licensed product or support service. The Response Centres are open during office hours, but contact is possible by fax, email and phone (answering machine) at all times. When contacting a Response Centre please quote your NAG user reference and NAG product code. (c) Network Network, NAG's newsletter, is produced quarterly and sent free of charge to sites with a supported product or service. (d) NAG Bulletin Board The NAG Bulletin Board is an information service providing items of interest to users and prospective users of NAG products and services. The information is regularly updated and reviewed; new features are added and special interest groups are continually developing. 8. NAG Users Association NAGUA, the NAG Users Association, is a self-financing, non-profitmaking body. It exists to promote communications between NAG and users of its products and services. It provides information to NAG on the requirements of users, who are in turn kept informed of developments in services. Membership is available to any institution or individual which holds a licence for any NAG product or service. Members receive discounts on the registration fees at conferences and workshops. Members also receive 'NAGUA News', NAGUA's own newsletter. For an information pack and membership application form, please contact NAGUA at the supplied address. Appendix - supplied addresses NAG Ltd Wilkinson House Jordan Hill Road OXFORD OX2 8DR NAG Ltd Response Centre United Kingdom email: support@nag.co.uk Tel: +44 865 511245 Tel: +44 865 311744 Fax: +44 865 310139 Fax: +44 865 310139 NAG Inc 1400 Opus Place, Suite 200 Downers Grove IL 60515-5702 NAG Inc Response Center USA email: infodesk@nag.com Tel: +1 708 971 2337 Tel: +1 708 971 2345 Fax: +1 708 971 2706 Fax: +1 708 971 2346 NAG Users Association PO Box 426 OXFORD OX2 8SD United Kingdom email: nagua@nag.co.uk Tel: +44 865 311102