           RAL-CGM Interpreter Version 3.00 - Installation Guide
           =====================================================

Introduction
============

RAL-CGM is an Interpreter/Translator for CGM files. This new release fixes all
known bugs in the previous release 2.00 and also adds a Tektronix 4200 and a
HPGL driver. It also adds configuration files for HPUX, ULTRIX and RS6000.

General Description
===================

The Interpreter (ralcgm)
------------------------

The RAL-CGM Interpreter consists of a number of separate modules which
read and translate or interpret a CGM. The modules provided with this
release are as follows:

    cgmmain    - Main Interpreter Routine

    cgmibin    - Read a Binary encoded CGM
    cgmichar   - Read a Character encoded CGM
    cgmitext   - Read a Clear Text encoded CGM

    cgmobin    - Output a Binary encoded CGM
    cgmochar   - Output a Character encoded CGM
    cgmotext   - Output a Clear Text encoded CGM

    cgmops     - Output a Postscript file
    cgmoxw     - X-windows driver
    cgmoigl    - Iris Graphics Library driver
    cgmotek    - Tektronix 4200
    cgmohpgl   - HPGL
    cgmovga    - PC VGA driver (using Microsoft C 6.0)


Plus the following Utility routines:

    cgmatt     - attributes resolving utilities
    cgmcell    - Cell Array utilities
    cgmcolr    - Colour handling utilities
    cgmerr     - error handler
    cgmfile    - file handling utilities
    cgmfill    - fill area utility
    cgmfont    - font handling utility
    cgmgdp     - utilities for handling circular and elliptical elements
                 (see GKS or CGM standards)
    cgmgraph   - graphical output utilities
    cgmpts     - Point handling utilities
    cgmrand    - random access frame utilities
    cgmtext    - text handling utilities

    cgmbez     - Bezier text output utility (optional)
    cgmher     - Hershey text output utility (optional)

An installation may not include all of the above files.


INSTALLATION under UNIX
=======================

You will find a shell script files: CGMinstall and the following directories:

     src/        - C source files
     include/    - Header files
     data/       - Text system data files
     docs/       - Man pages
     examples/   - Various CGM's
     bin/        - Module and Library (this starts empty)

To install RAL-CGM 'CGMinstall' should be executed. It only requires one
argument which is the system to 'make'.
Currently in release 2 possible values are as follows:

      sun3    - Sun 3
      sun4    - Sun 4
      iris    - Silicon Graphics Iris 3130
      indigo  - Silicon Graphics Iris Indigo
      iris4d  - Silicon Graphics Iris 4D
      rs6000  - IBM RS6000
      hpux    - Hewlett Packard Workstation
      ultrix  - DECstation
      cray    - Cray Unicos (using cc)
      crayscc - Cray Unicos (using scc)
      craypcc - Cray Unicos (using pcc)
      topaz   - Primagraphics Topaz (incomplete source provided, but
                  available on request)

The script will ask several questions which require 'y' or 'n' answers to
tailor the system to your own requirements. These options allow you to choose
whether to create 'cgmlib', include X-Windows, PostScript, HPGL, Tektronix,
Bezier Text and/or Hershey Text. If you choose X-Windows, you will be asked
where the include files are to be found. If you choose PostScript, you will be
asked whether to use the 13 or 35 set of fonts.

The Bezier Text system is a set of 10 fonts to provide filled characters,
whilst the Hershey system provides 15 line drawn fonts. Both these text sytems
are optional.

The CGMinstall script will also create a 'Makefile' in the 'src' directory
so that if any changes are made you can simply type 'make' or make 'cgmlib'
in the top level directory.



INSTALLATION under VAX/VMS
==========================

There is a DCL command procedure `GEN_RALCGM.COM' in the top level of
the file structure along with the following directories:

   [.SRC]
   [.INCLUDE]
   [.DATA]
   [.DOCS]
   [.EXAMPLES]
   [.BIN]     (starts empty)

Invoking 'GEN_RALCGM.COM' will compile the entire system and link it to an
executable program `RALCGM.EXE' in the [.BIN] directory. It will ask several
questions allowing for some local tailoring of the system. These options allow
you to choose whether to include X-Windows, PostScript, Bezier Text and/or
Hershey Text. The Bezier Text system is a set of 10 fonts to provide filled
characters, whilst the Hershey system provides 15 line drawn fonts. Both
these text sytems are optional. If the PostScript option is included then the
installation procedure will ask whether the 35 or 13 PostScript font set is
required. This determines which fonts are known about by the PostScript
output module. The 35 font set is the fonts found on an Apple LaserWriter II,
the 13 font set is the font set of the original Apple LaserWriter.

The object library `RALCGM.OLB' is also created in the [.BIN] directory.  At
present this does not contain the `CGMLIB' callable interface to the system,
although it is present in source form in the [.SOURCE] directory.

A further DCL command procedure `RALCGM_STARTUP.COM' is created by
'GEN_RALCGM.COM' which, when invoked, defines the logical names required by the
RAL-CGM system.  This should be run before running `RALCGM'.

The font used for the menu text in the X-windows previewer can be set by
defining the logical name CGMMENUFONT. A default value (set in mc_vms.h) is
taken if this is not defined. The logical name CGMDATA which points to the
location of the data file directory MUST be defined. These two logicals are
assigned values in'RALCGM_STARTUP.COM'

After running 'GEN_RALCGM.COM' there is a help file `RALCGM.HLP' in the DOCS
directory. This contains more detailed information on running RALCGM and the
use of other logical names.

VAX/VMS users who do not have a C compiler but who wish to use RALCGM should
contact Nick Hill at RAL ( NMH1@UK.AC.RL.VE )



INSTALLATION under VM/CMS
=========================

All the files should be copied to either a single minidisk with at least 8
cylinders or a set of minidisks. To install first copy 'MC_CMS H' to 'MACH H'
and edit to specify which compiler you are using (either WATC for Waterloo C
or C370 for IBM C/370 in the second #define statement).
If you do not require PostScript, X-Windows or the Bezier or Hershey text
systems should delete the relevant '#define' lines in 'MACH H'.
Note that in order to use X-Windows you must have TCP/IP and you can not use
X-Windows with the Waterloo C Compiler. because the wrong linkage conventions
are used.

A REXX exec 'GENCGM EXEC' is provided which will compile each of the modules
to create a file called 'CGM200 MODULE' and a Library 'CGMLIB TXTLIB' on your
A-Disk. This EXEC will also compile and run the modules to create the Bezier
and Hershey Text systems (if required).

A REXX exec 'RALCGM EXEC' is also provided which should be used to run the
interpreter. This accepts standard CMS file names and converts them to Unix
style names which RALCGM uses.

The Library 'RALCGM TXTLIB' can be used to create CGMs directly from a C
program.

VM/CMS users who do not have a C compiler, but who wish to use RALCGM, please
contact Roy Platon at RAL (RTP@UK.AC.RL.IB ).


INSTALLATION under MS-DOS
=========================

The RAL-CGM Interpreter is now available under MS-DOS and a screen driver has
been written using the Microsoft C version 6.0a graphics library. The translator
and PostScript drivers should work with other C compilers but have not been
tested. The driver 'cgmovga.c' is provided in source form, but no installation
file is given as there are still some problems with the microsoft C compiler
which are being investigated.

MS-DOS users who do not have a Microsoft C compiler, but who wish to use
RALCGM, please contact Roy Platon at RAL (RTP@UK.AC.RL.IB ).

LIBRARY (cgmlib)
----------------

The RAL-CGM library consists of a 'C' callable interface and one or more of the
output modules. A header file 'cgmlib.h' defines the interface to the routines
together with some typedefs defined in 'cgmtypes.h'. There is one routine for
each CGM element plus a routine 'cgminit' to choose an Output driver and
initialise the system. All CGM element routines have 'm_' prefixed to the
corresponding clear text encoded name. The prototype function for each element
are listed in 'cgmlib.h'.

All Points should be stored in the struct 'Point', which is a set of two floats
regardless of whether REAL or INTEGER VDCs or being used (this is to simplify
the user interface). Some parameters are dependent on the encoding used.
In most cases the character encoding form is used as this is the most flexible.
'Enum' are parameters defined as 'Enumerated' in the standard. These are
defined in 'cgmpar.h' and follow the Clear text encoding except for
TEXT PATH, where 'P_' is added to avoid confusion with TEXT ALIGNMENT.
NOTE that 'm_cellarray' has pointers to both Indexed and Direct Colours.
Only the array determined by the current COLOUR MODE should be used.

A program 'testcgm.c' is supplied in 'examples' which uses most of the graphics
primitives.

LIMITATIONS
===========

This section describes known limitations & bugs in RAL-CGM. These are divided
into General Limitations and driver specific limitations.

General
-------
Auxillary colour is not supported on most drivers.
Character Sets other than UK are not recognised.

X-Windows
---------
Small Text using an X Font will be drawn at its minimum size, which may be
unreadable.
On a Sun some fill areas will 'bleed'. This is due to a bug in the Sun X server.

PostScript
----------
Polygon Set is not yet implemented.
Large and complex fill areas may not be displayed, due to the 1500 point limit
in PostScript level 1.

Iris Graphics Library
---------------------
Fill areas use hardware fill area which can not handle complex areas or
Polygon set.
Direct colour is only supported on systems with 24-bit planes or which have
a virtual 24-bit system (eg Indigo).
Setting of Colour indices 1-8 may upset your console window.
Pattern size and reference point are not used. Only user bit patterns using
powers of 2 are supported.

Tektronix 4000
--------------
Clipped Polygon and Polygon Set may not be correct.
No Hatched fill style.
Direct colour is limited to the first 16 colours defined, unless more
bit-planes are available.
Linewidth not yet supported.
No random frame access.
Error messages must be diverted to a file or the Graphics state is lost.

HPGL
----
Only Hollow Polygons are supported.
Cell Arrays are only plotted as an outline.

VGA
---
Polygon set is not supported.
Error messages may corrupt the Graphics screen.
If many Bezier Fonts are used an 'out of memory' message appears which can
only be cleared by rebooting the PC.
Clipped Fill areas are not always filled, due to bugs in Microsoft library.

+--------------------------------------------------------------------------+
|                                                                          |
|  Copyright (C) Rutherford Appleton Laboratory 1990, All Rights Reserved. |
|                                                                          |
|  This source may be copied, distributed, altered or used, but not sold   |
|  for profit or incorporated into a product except under licence from     |
|  the authors.                                                            |
|                                                                          |
|  It is not in the public domain.                                         |
|                                                                          |
|  This notice should remain in the source unaltered, and any changes to   |
|  the source made by persons other than the authors should be marked as   |
|  such.                                                                   |
|                                                                          |
+--------------------------------------------------------------------------+

RALCGM INSTALL version 2.3
