Greetings,

I've enclosed the README file and the (formatted) man(1)ual page.

If you decide to join the mailing-list, then please send a request to

	xgks-request@unidata.ucar.edu

Regards,
Steve Emmerson

--------Begin README
                            INTRODUCTION
                            ------------

This directory contains all source code and documentation associated
with the XGKS library.  XGKS is an X11 window system based version of
the ANSI Graphical Kernel System.  XGKS is a full GKS system (level
2C).  This library was developed at the University of Illinois, Urbana
campus, department of Computer Science and was funded by IBM TCS.  The
project was headed by Prof.  Bill Kubitz and Prof. Roy Campbell.
Development of XGKS was done by Greg Rogers, Sung Hsien Ching, and Yu
Pan.  Testing and improvements to XGKS were performed by IBM Technical
Computing Systems in Cambridge, Mass.  The IBM developers were Todd
Gill, Bruce Greer, David Owens, and Michael Wojcik, and Project Leader
Amy Pitts.

Neither the University of Illinois nor IBM support XGKS anymore.
Fortunately, however, Steve Emmerson of Boulder, Colorado has accepted
the maintenance of XGKS as a hobby.  There is also a mutual-aid-society
mailing-list for XGKS user's.  To join the mailing-list, send email to

    xgks-request@unidata.ucar.edu	(IP address: 128.117.140.3)

An archive of the XGKS mailing-list is available from the gopher(1)
server on host gopher.unidata.ucar.edu.  First select the category on
Unidata support databases, then select the category on the XGKS email
archive.




                   SOURCE DIRECTORY OVERVIEW
                   -------------------------

The structure of the XGKS source directory-tree is


	       |-progs--
	       |
	       |        |-binding--
	       |-doc----|
	       |        |-userdoc--
	|-xgks-|
	       |-fontdb-
	       |
	       |        |-fortran--
	       |        |
	       |-src----|          |-cgm--
			|          |
			|-lib------|-gksm-
				   |
                                   |-x----

where:

    xgks	Is the root directory (the one containing this file)

    progs	Contains utility programs

    doc		Contains documentation (e.g. "xgks.3")

    doc/binding	Contains the source for a document describing the
		1988 C language binding for XGKS

    doc/userdoc	Contains the source for a document describing the
		GKS implementation-specific details of XGKS

    fontdb	Contains the XGKS fonts

    src		Contains the implementation of the XGKS runtime-library

    src/fortran	Contains the source for the Fortran interface to XGKS

    src/lib	Contains the source for the XGKS library.

    src/lib/cgm	Contains the source for the Compute Graphics Metafile
		"backend" to XGKS.

    src/lib/gksm
		Contains the source for the GKS Metafile (GKSM) "backend"
		to XGKS.

    src/lib/x	Contains the source for the X Window System "backend" to 
		XGKS.




                           INSTALLATION
                           ------------

Installation instructions can be found in the file INSTALL.

XGKS has been installed on many platforms, including:
    
	Apollo DN3000	under DomainOS 10.2,   BSD4.3, with C compiler
			68K Rev 6.7(316)
	Apollo DN4000	under DomainOS 10.3.2, BSD4.3, with C compiler
			68K Rev 6.8(168)
	Apollo 425T	under DomainOS 10.3.5
	VaxStation II	under Ultrix 3.5, 4.0, & 4.1
	DECstation 3100	under ULTRIX 4.1 & 4.2
	HP 9000/720	under HPUX 8.0
	Sun3		under SunOS 4.0.3, 4.1, & 4.1.1 (using both 
			    /usr/bin/cc and /usr/5bin/cc)
	Sun4		under SunOS 4.1 & 4.1.1
	IBM RS6000	under AIX 3.1
	Cray Y-MP	under UNICOS 5.1.11

The structure of the installation is nominally:

                            |-defcolors
                            |-font
                            |-mi
                  |-bin-----|-pline
                  |         |-pmark
                  |         |-hanoi
                  |         |-star
                  |         |-gksdemo
                  |
         |-prefix-|-include-|-xgks.h
                  |
                  |         |-libxgks.a
                  |-lib-----|
                  |         |-xgksfonts-
                  |
                  |-man-----|-man3-|-xgks.3

where:

    prefix      is whatever you made it when you invoked `configure' (see
		file INSTALL).

    defcolors   displays the default X colormap (set DISPLAY first);

    font        displays the fonts used by XGKS (set DISPLAY first);

    mi          is a simple GKS Metafile (GKSM) interpreter 
                (usage: mi <display> <file>);

    pline       displays the polyline types used by XGKS (set DISPLAY
                first);

    pmark       displays the marker types used by XGKS (set DISPLAY
                first);

    hanoi       is a Towers-of-Hanoi demonstration (set DISPLAY first);

    star        is a imple fortran program to draw a star (set DISPLAY first);

    gksdemo     is a Fortran program that demonstrats most of XGKS 
		capabilities (set DISPLAY first);

    xgks.h      is the header-file that every XGKS application must
                #include;

    libxgks.a   is the XGKS runtime library.

    xgksfonts   is a directory which contains the XGKS fonts;

    xgks.3      contains the XGKS man(1)ual pages.

Fonts used by XGKS are dynamically loaded when first referenced.  Thus,
the fonts must be installed on the machine where the XGKS application
executes.

The font path is compiled into the library.  However, it is possible to
move the fonts without having to recompile XGKS by setting the
environment variable "XGKSFontDir" to the new path before executing an
XGKS application.  This variable setting will tell XGKS at runtime
where to find its fonts.




                            DOCUMENTATION
                            -------------

In addition to the man(1)ual pages that will be installed during the
installation procedure, there are two other documents you should be aware
of.  The first describes the C-language binding used by XGKS.  To obtain
hardcopy, go to directory "doc/binding", edit the makefile (if necessary),
and type "make hardcopy".

The second document details the implementation-specific aspects of GKS
particular to XGKS.  To obtain hardcopy, go to directory "doc/userdoc",
edit the makefile (if necessary), and type "make hardcopy".

A good general book on GKS is "Computer Graphics Programming: GKS - The
Graphics Standard" by G. Enderle, K. Kansy, and G. Pfaff.  It's published
by Springer-Verlag and its ISBN numbers are 3-540-16317-4 and
0-387-16317-4.




                               A PLEA
                               ------

Please send any contributions to the evolution of XGKS to

	xgks-request@unidata.ucar.edu

They'll be incorporated so that the next poor grunt won't have such a tough
time.


Regards,
Steve Emmerson          xgks-request@unidata.ucar.edu
--------End README

--------Begin XGKS manual page



XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



NAME
     XGKS - A GKS library for the X Window System

SYNOPSIS
     #include <xgks.h>


     Gint gopenws (Gint wsid, Gchar *connection, Gchar *ws_type);

     Gint gclosews (Gint wsid);

     Gint gclearws (Gint wsid, Gclrflag control_flag);

     Gint gopengks (Gfile *err_file, Glong memory);

     Gint gclosegks (void);

     Gint gsetasf (Gasfs *asf);

     Gint gsetcolorrep (Gint wsid, Gint idx, Gcobundl *rep);

     Gint  ginqcolorrep  (Gint  wsid,  Gint  idx,  Gqtype   type,
         Gcobundl *rep);

     Gint ginqcolorindices (Gint wsid, Gintlist *indices);

     Gint ginqcolorfacil (Gchar *ws_type, Gcofac *fac);

     Gint ginqpredcolorrep (Gchar *ws_type, Gint index,  Gcobundl
         *rep);

     Gint gactivatews (Gint wsid);

     Gint gdeactivatews (Gint wsid);

     Gint gsetwindow (Gint trans, Glimit *window);

     Gint gsetviewport (Gint trans, Glimit *viewport);

     Gint gsetviewportinputpri (Gint trans, Gint ref_trans, Gvpri
         priority);

     Gint gselntran (Gint trans);

     Gint gsetclip (Gclip ind);

     Gint gsetwswindow (Gint wsid, Glimit *window);

     Gint gsetwsviewport (Gint wsid, Glimit *viewport);

     Gint  gevaltran  (Gpoint  *ppoint,  Gpoint  *pshift,  Gfloat
         angle, Gpoint *pscale, Gcsw coord, Gfloat result[2][3]);



XGKS Version 2      Last change: 23 July 1991                   1






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint  gaccumtran  (Gfloat  segtran[2][3],  Gpoint   *ppoint,
         Gpoint  *pshift,  Gfloat  angle,  Gpoint  *pscale,  Gcsw
         coord, Gfloat result[2][3]);

     Gint gemergencyclosegks (void);

     Gint  gerrorhand  (Gint  errnum,  Gchar   *funcname,   Gfile
         *perrfile);

     Gint  gerrorlog  (Gint  errnum,   Gchar   *funcname,   Gfile
         *perrfile);

     Gint gpolyline (Gint num_pts, Gpoint *pts);

     Gint gsetlineind (Gint idx);

     Gint gsetlinetype (Gint type);

     Gint gsetlinewidth (Gfloat width);

     Gint gsetlinecolorind (Gint idx);

     Gint gsetlinerep (Gint wsid, Gint idx, Glnbundl *rep);

     Gint gcreateseg (Gint name);

     Gint gcloseseg (void);

     Gint grenameseg (Gint old, Gint new);

     Gint gdelseg (Gint name);

     Gint gdelsegws (Gint wsid, Gint name);

     Gint gsetsegattr (Gint name, Gsegattr *segattr);

     Gint gsetpickid (Gint pick_id);

     Gint gassocsegws (Gint wsid, Gint seg_id);

     Gint gcopysegws (Gint wsid, Gint seg_id);

     Gint ginsertseg (Gint seg_id, Gfloat segtran[2][3]);

     Gint gredrawsegws (Gint wsid);

     Gint ginqmodsegattr (Gchar *ws_type, Gmodseg *dyn);

     Gint ginqnameopenseg (Gint *seg);

     Gint ginqsegattr (Gsegattr *segattr);




XGKS Version 2      Last change: 23 July 1991                   2






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginqassocws (Gint seg, Gintlist *asswk);

     Gint ginqsegnames (Gintlist *segs);

     Gint ginqsegnamesws (Gint wsid, Gintlist *segs);

     Gint ginqnumsegpri (Gchar *ws_type, Gint *numpri);

     Gint ginqcurpickid (Gint *pickid);

     Gint gpolymarker (Gint num_pts, Gpoint *pts);

     Gint gsetmarkersize (Gfloat size);

     Gint gsetmarkertype (Gint type);

     Gint gsetmarkercolorind (Gint color);

     Gint gsetmarkerind (Gint idx);

     Gint gsetmarkerrep (Gint wsid, Gint idx, Gmkbundl *rep);

     Gint gfillarea (Gint num_pts, Gpoint *pts);

     Gint gsetfillcolorind (Gint color);

     Gint gsetfillind (Gint idx);

     Gint gsetfillintstyle (Gflinter style);

     Gint gsetfillrep (Gint wsid, Gint idx, Gflbundl *rep);

     Gint gsetfillstyleind (Gint idx);

     Gint gsetpatrep (Gint wsid, Gint idx, Gptbundl *rep);

     Gint gcellarray (Grect *rect, Gipoint *dim, Gint  row,  Gint
         *color);

     Gint ginitloc (Gint wsid, Gint dev, Gloc  *init,  Gint  pet,
         Glimit *area, Glocrec *record);

     Gint gsetlocmode (Gint wsid, Gint  dev,  Gimode  mode,  Gesw
         echo);

     Gint greqloc (Gint wsid, Gint dev, Gqloc *response);

     Gint gsampleloc (Gint wsid, Gint dev, Gloc *response);

     Gint ginqlocst (Gint wsid, Gint  dev,  Gqtype  type,  Glocst
         *state);




XGKS Version 2      Last change: 23 July 1991                   3






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginqdefloc (Gchar *type, Gint dev, Gdefloc *data);

     Gint gawaitevent (Gfloat timeout, Gevent *event);

     Gint gflushevents (Gint wsid, Giclass class, Gint dev);

     Gint ginqinputoverflow (Gqueue *overflow);

     Gint ginqmoreevents (Gsimultev *events);

     Gint ggetloc (Gloc *response);

     Gint ggetstroke (Gstroke *response);

     Gint ggetchoice (Gchoice *response);

     Gint ggetpick (Gpick *response);

     Gint ggetval (Gfloat *response);

     Gint ggetstring (Gchar *response);

     Gint gupdatews (Gint wsid, Gregen regenflag);

     Gint gsetcharexpan (Gfloat expansion);

     Gint gsetcharheight (Gfloat height);

     Gint gsetcharspace (Gfloat spacing);

     Gint gsetcharup (Gpoint *up_vector);

     Gint gsettextalign (Gtxalign *txalign);

     Gint gsettextcolorind (Gint color);

     Gint gsettextfontprec (Gtxfp *txfp);

     Gint gsettextind (Gint idx);

     Gint gsettextpath (Gtxpath path);

     Gint gsettextrep (Gint wsid, Gint idx, Gtxbundl *bundle);

     Gint gtext (Gpoint *at, Gchar *string);

     Gint  ginqtextextent  (Gint  wsid,  Gpoint  position,  Gchar
         *string, Gextent *extent);

     Gint  gsetdeferst  (Gint   wsid,   Gdefmode   deferral_mode,
         Girgmode regen_mode);




XGKS Version 2      Last change: 23 July 1991                   4






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginitchoice (Gint wsid, Gint dev, Gchoice  *init,  Gint
         pet, Glimit *area, Gchoicerec *record);

     Gint gsetchoicemode (Gint wsid, Gint dev, Gimode mode,  Gesw
         echo);

     Gint greqchoice (Gint wsid, Gint dev, Gchoice *response);

     Gint gsamplechoice (Gint wsid, Gint dev, Gchoice *response);

     Gint ginqchoicest (Gint wsid, Gint dev, Gchoicest *state);

     Gint  ginqdefchoice  (Gchar  *type,  Gint  dev,   Gdefchoice
         *data);

     Gint ginitpick (Gint wsid, Gint dev, Gpick *init, Gint  pet,
         Glimit *area, Gpickrec *record);

     Gint gsetpickmode (Gint wsid, Gint dev,  Gimode  mode,  Gesw
         echo);

     Gint greqpick (Gint wsid, Gint dev, Gpick *response);

     Gint gsamplepick (Gint wsid, Gint dev, Gpick *response);

     Gint ginqpickst (Gint wsid, Gint dev, Gqtype  type,  Gpickst
         *state);

     Gint ginqdefpick (Gchar *type, Gint dev, Gdefpick *data);

     Gint ginitval (Gint wsid, Gint dev, Gfloat init,  Gint  pet,
         Glimit *area, Gvalrec *record);

     Gint gsetvalmode (Gint wsid, Gint  dev,  Gimode  mode,  Gesw
         echo);

     Gint greqval (Gint wsid, Gint dev, Gqval *response);

     Gint gsampleval (Gint wsid, Gint dev, Gfloat *response);

     Gint ginqvalst (Gint wsid, Gint dev, Gvalst *state);

     Gint ginqdefval (Gchar *type, Gint dev, Gdefval *data);

     Gint ginitstring (Gint wsid, Gint  dev,  Gchar  *init,  Gint
         pet, Glimit *area, Gstringrec *record);

     Gint gsetstringmode (Gint wsid, Gint dev, Gimode mode,  Gesw
         echo);

     Gint greqstring (Gint wsid, Gint dev, Gqstring *response);




XGKS Version 2      Last change: 23 July 1991                   5






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint gsamplestring (Gint wsid, Gint dev, Gchar *response);

     Gint ginqstringst (Gint wsid, Gint dev, Gstringst *state);

     Gint  ginqdefstring  (Gchar  *type,  Gint  dev,   Gdefstring
         *data);

     Gint ginitstroke (Gint wsid, Gint dev, Gstroke  *init,  Gint
         pet, Glimit *area, Gstrokerec *record);

     Gint gsetstrokemode (Gint wsid, Gint dev, Gimode mode,  Gesw
         echo);

     Gint greqstroke (Gint wsid, Gint dev, Gqstroke *response);

     Gint gsamplestroke (Gint wsid, Gint dev, Gstroke *response);

     Gint  ginqstrokest  (Gint  wsid,  Gint  dev,  Gqtype   type,
         Gstrokest *state);

     Gint  ginqdefstroke  (Gchar  *type,  Gint  dev,   Gdefstroke
         *data);

     Gint ginqlinefacil (Gchar *ws_type, Glnfac *fac);

     Gint ginqpredlinerep (Gchar  *ws_type,  Gint  idx,  Glnbundl
         *rep);

     Gint ginqlineindices (Gint wsid, Gintlist *idxlist);

     Gint ginqlinerep (Gint wsid, Gint idx, Gqtype type, Glnbundl
         *rep);

     Gint ginqmarkerfacil (Gchar *ws_type, Gmkfac *fac);

     Gint ginqpredmarkerrep (Gchar *ws_type, Gint  idx,  Gmkbundl
         *rep);

     Gint ginqmarkerindices (Gint wsid, Gintlist *idxlist);

     Gint  ginqmarkerrep  (Gint  wsid,  Gint  idx,  Gqtype  type,
         Gmkbundl *rep);

     Gint ginqfillfacil (Gchar *ws_type, Gflfac *fac);

     Gint ginqpredfillrep (Gchar  *ws_type,  Gint  idx,  Gflbundl
         *rep);

     Gint ginqfillindices (Gint wsid, Gintlist *idxlist);

     Gint ginqfillrep (Gint wsid, Gint idx, Gqtype type, Gflbundl
         *rep);



XGKS Version 2      Last change: 23 July 1991                   6






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginqpatfacil (Gchar *ws_type, Gint *fac);

     Gint ginqpredpatrep  (Gchar  *ws_type,  Gint  idx,  Gptbundl
         *rep);

     Gint ginqpatindices (Gint wsid, Gintlist *idxlist);

     Gint ginqpatrep (Gint wsid, Gint idx, Gqtype type,  Gptbundl
         *rep);

     Gint gmessage (Gint wsid, Gchar *string);

     char *gescinqversion (void);

     Gint gescinqxattr (Gint wsid, Display **dpy, Window *win, GC
         *gc);

     void gescsetbackingstore (Gint wsid, Gint i);

     void gescsetprogname (char *name);

     Gint gescsetcolormask (Gint wsid, unsigned long mask);

     Gint gescsetdcsize (Gint wsid, Gpoint size);

     Gint gescstoreprimi (Gint wsid, Gstore store);

     Gint gescredrawnotify (Gint wsid, Gint  (*funcp)(Gint  wsid,
         typedef enum Gredraw who));

     Gint ginqtextfacil (Gchar *ws_type, Gtxfac *fac);

     Gint ginqpredtextrep (Gchar  *ws_type,  Gint  idx,  Gtxbundl
         *rep);

     Gint ginqtextindices (Gint wsid, Gintlist *idxlist);

     Gint ginqtextrep (Gint wsid, Gint idx, Gqtype type, Gtxbundl
         *rep);

     Gint ginqavailwstypes (Gstrlist *wstypes);

     Gint ginqdisplayspacesize (Gchar *ws_type, Gdspsize *dspsz);

     Gint ginqwscategory (Gchar *ws_type, Gwscat *cat);

     Gint ginqwsclass (Gchar *ws_type, Gwsclass *class);

     Gint ginqmodwsattr (Gchar *ws_type, Gmodws *dyn);

     Gint ginqdefdeferst (Gchar *ws_type, Gdefer *def);




XGKS Version 2      Last change: 23 July 1991                   7






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginqmaxwssttables (Gchar *ws_type, Gwstables *tables);

     Gint ginqnumavailinput (Gchar *ws_type, Gnumdev *num);

     Gint ginqwsconntype (Gint wsid, Gwsct *ct);

     Gint ginqwsst (Gint wsid, Gwsstate *state);

     Gint ginqwsdeferupdatest (Gint wsid, Gwsdus *du);

     Gint ginqopst (Gos *state);

     Gint ginqlevelgks (Glevel *lev);

     Gint ginqwsmaxnum (Gwsmax *maxws);

     Gint ginqopenws (Gintlist *wsids);

     Gint ginqactivews (Gintlist *wsids);

     Gint ginqprimattr (Gpriattr *primattr);

     Gint ginqindivattr (Gindattr *indivattr);

     Gint ginqcurntrannum (Gint *tran);

     Gint ginqntrannum (Gintlist *tranlist);

     Gint ginqntran (Gint num, Gwstran *tran);

     Gint ginqclip (Gcliprec *clipping);

     Gint ginqmaxntrannum (Gint *maxtran);

     Gint ginqwstran (Gint wsid, Gwsti *wstran);

     Gint ginqpixelarraydim  (Gint  wsid,  Grect  *rect,  Gipoint
         *dim);

     Gint  ginqpixelarray  (Gint  wsid,  Gpoint  *point,  Gipoint
         *dimen, Gpxarray *pxarr);

     Gint ginqpixel (Gint wsid, Gpoint *ppoint, Gint *pix);

     Gint gwritegksm (Gint wsid, Gint type,  Gint  length,  Gchar
         *data);

     Gint ggetgksm (Gint wsid, Ggksmit *result);

     Gint greadgksm (Gint wsid, Gint length, Gchar *record);





XGKS Version 2      Last change: 23 July 1991                   8






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     Gint ginterpret (Ggksmit *recInfo, Gchar *data);

DESCRIPTION
     XGKS is an implementation of the ANSI Graphical Kernel  Sys-
     tem for use with the X Window System.  XGKS was developed at
     the University of Illinois, Urbana, Illinois, and  supported
     by IBM ACIS.  After being made freely available in the X11R4
     distribution, XGKS was adopted by the Unidata Program Center
     (UPC) of the University Corporation for Atmospheric Research
     (UCAR) in Boulder, Colorado.

STANDARDS
     XGKS is an  implementation  of  the  ANSI  Graphical  Kernel
     System  as  defined  by  the  functional description and the
     draft 1988 C language binding.  Thus, the  ultimate   refer-
     ence  for  any  programmer is the C binding manual which de-
     tails the data types and functions available.   XGKS  is   a
     level  2C implementation  of  the  GKS  specification.    It
     supports REQUEST, SAMPLE, and EVENT input modes for all  six
     logical  input   devices,  workstation  independent  segment
     storage, and metafiles.

CAPABILITIES
     The XGKS library supports all  functions  specified  by  the
     ANSI standard with the exception of :

          ESCAPE (in its most general form)
          GENERALIZED DRAWING PRIMITIVE (in its most general form)
          INQUIRE GENERALIZED DRAWING PRIMITIVE
          INQUIRE LIST OF AVAILABLE GENERALIZED DRAWING PRIMITIVES
          SET PATTERN REFERENCE POINT
          SET PATTERN SIZE

     The escape and gdp functions are implemented  as  a  set  of
     functions which follow the naming convention outlined in the
     C  binding.    That   is,   escape   functions   are   named
     gescfunction   and   gdp  functions  are named ggdpfunction,
     where function is a  descriptive  name  for   the   function
     performed.

ESCAPE FUNCTIONS
     gescinqversion() returns a string identifying the XGKS  ver-
     sion.

     gescinqxattr() returns the attributes of the opened X window
     for workstation wsid.

     gescsetbackingstore() enables  (disables)  backingstore  for
     workstation  wsid  if i is non-zero (zero).  Backingstore is
     enabled by default if it is available on the workstation and
     the  backingstore X resource (see X-RESOURCES) doesn't indi-
     cate otherwise.



XGKS Version 2      Last change: 23 July 1991                   9






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     gescsetprogname() sets the program name by which the  appli-
     cation  will  be known to X to name.  This name will be used
     to access X resouces by  prepending  it  to  resource  names
     (along  with  a  separating  period `.').  The X window will
     also be named name.  By default, the name XGKS is used.

     gescsetcolormask () changes the color-plane mask on worksta-
     tion wsid to mask via the X function XSetPlaneMask().

     gescsetdcsize()  changes  the  device  coordinate  space  on
     workstation wsid to size.

     gescstoreprimi() enables  (disables)  the  storing  of  non-
     segment  output  primitives  on workstation wsid if store is
     non-zero (zero).  Storing  is  enabled  by  default  and  is
     necessary for an X refresh (after an expose or resize event)
     to include primitives which are not stored in any segment.

     gescredrawnotify() registers the user-defined  redraw  func-
     tion  funcp  with workstation wsid.  When a redraw action is
     initiated, the final action will be to call funcp  with  the
     first  argument set to the workstation number and the second
     argument set to GRD_GKS (if the redraw was initiated by GKS)
     or  to  GRD_X (if the redraw was initiated by X).  Both sym-
     bolic constants are defined in the header-file xgks.h.

OUTPUT PRIMITIVES
     Polylines of any width and  color  can  be  displayed  while
     seven line styles are supported they are:

          GLN_DASH       long dash
          GLN_DDOTDASH   double dot dash
          GLN_SDASH      short dash
          GLN_SOLID      solid
          GLN_DASH       medium dash
          GLN_DOT        dotted
          GLN_DOTDASH    dot dash

     Polymarkers of any size and color  can  be  displayed,  five
     marker styles are provided:

          GMK_POINT      filled circle
          GMK_PLUS       +
          GMK_STAR       *
          GMK_O          unfilled circle
          GMK_X          X

     All text within XGKS is implemented  through  stroke  fonts,
     thus  text  primitives  are  fully transformable.  Nine font
     styles are supported:

          1    SanSerif Roman



XGKS Version 2      Last change: 23 July 1991                  10






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



          2    Serif Roman
          3    SansSerif Bold Roman
          4    Serif Bold Roman
          5    Sanserif Italic Roman
          6    Serif Italic Roman
          7    SanSerif Script
          8    Serif Script
          9    Gothic

     Fill Area output primitives  can  be  displayed  as  hollow,
     solid,   hatched   and  patterned.   Twenty (numbered one to
     twenty)  hatch and pattern styles are predefined.   The  ap-
     plication  program can redefine these patterns; however, the
     programmer should be aware that  the  gsetpatrep()  function
     expects  patterns  to  be  stored in column major order from
     bottom to top.  This means that cell[0][0]  is  the  bottom-
     left  corner,  cell[dx-1][dy-1] is the top-right corner, and
     cell[0][1] is directly above cell[0][0].

     GKS  Cell  Arrays  are  supported  in   their   most    gen-
     eral, transformable form.

LOGIAL INPUT DEVICES
     XGKS supports the full GKS input model.  Thus,  all  logical
     input  devices  operate in request, sample, and event modes.
     Any number of logical input devices can be created for  each
     of the six input classes.  All logical devices are triggered
     through the use of  the  mouse  and  its  buttons  with  the
     exception of the choice device where one prompting technique
     uses the  keyboard's  function  buttons.   A  logical  input
     device is only active when the mouse is within the echo area
     of the device and one  or  more  of  the  mouse  buttons  is
     pressed.   When  the  mouse button is released, the physical
     device triggers all logical  input  devices  in  request  or
     event mode whose echo area surrounds the cursor.  Devices in
     sample mode are triggered whenever the  mouse  moves  within
     the  echo  area  while  the  mouse  is  pressed.   Any input
     operation can be aborted by pressing the Break  key  on  the
     keyboard.

     Five prompting types are defined for the locator:

          1    tracking cross
          2    crosshair spanning X window
          3    tracking cross
          4    rubberband line
          5    rubberband rectangle

     The only restriction placed on these prompts is that  prompt
     and  echo  type  5 does not allow the rectangle to be a fill
     area  style  other  than  hollow.   The  fixed  end  of  the
     rubberband  line  and  rubber  rectangle  is  at the initial



XGKS Version 2      Last change: 23 July 1991                  11






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     locator position while  the  floating  end  is  the  current
     value.

     The stroke input device differs from the locator by allowing
     more  than  one  coordinate  point to be entered.  There are
     three stroke prompts supported:

          1    tracking cross
          3    polymarker at each point
          4    polyline joining points

     The closeness  of  selected  points  can  be  controlled  by
     specifying  a  minimum  X  and minimum Y displacement in the
     stroke data record during stroke  initialization.   Although
     specified  as  a  distance  in  World  Coordinate space, the
     restriction is enforced in Normalized Device space.

     The valuator input device allows the user to select  a  real
     numbered value within the application specified range.  Only
     one  visual  representation  is  currently  supported:   the
     valuator appears as a bar with a sliding knob whose relative
     position determines the current value.  A horizontal bar  is
     displayed  if  the  echo  area  is  wider  than  it is tall,
     otherwise a vertical bar is used.  This prompt technique  is
     selected by valuator prompt and echo types one and two.

     Two types of choice devices are provided.    Choice  prompts
     one  and  two  use  the  keyboard  function keys as a choice
     device, thus function key  F1  returns  choice  number  one.
     Prompt  and  echo  type  one enables all function keys while
     prompt type two enables only those  keys  specified  in  the
     data  record  when the device is initialized.  Choice prompt
     type three presents the user with  a  menu  from  which  the
     current  choice  is  selected.  These  menus  appear and act
     similar to most X11 window  manager  menus.   That  is,  the
     current  selection  is  highlighted and selection is made by
     releasing the mouse button when the desired choice  is  lit.
     A  word  of warning, these menus are displayed in the choice
     echo  area  and  DO  NOT  attempt  to  restore  any   output
     primitives that they cover.

     Currently only two pick prompt types are supported: one  and
     three.   Both  prompt types highlight the currently selected
     segment by flashing a  bounding  box  around  the  segment's
     extent.   Also,  picking  is only implemented at the segment
     extent level.   Thus, if two segments overlap and  the  user
     points  at  the  area  of  intersection, then the segment of
     highest priority will  be  picked  even  if  the  cursor  is
     directly over a primitive contained in the other segment.

     The string device has only one prompt and echo type:  number
     1.   This  prompt  type  gives the user one line on which to



XGKS Version 2      Last change: 23 July 1991                  12






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     type.  This line is positioned in the upper-left  corner  of
     the  string echo area and is displayed as a hollow fill area
     within which  an  insertion  point  cursor  and  typed  text
     appear.   As  the  user  types,  the  only  special keys are
     Backspace, Delete,  and  Enter  which  perform  the  obvious
     functions.   The  length of the line is limited by the width
     of the echo area and  the  size  of  the  string  buffer  as
     specified   by   the   application   program  during  string
     initialization.

LIMITS
     Four workstation types are defined by XGKS:  MI,  MO,  WISS,
     and  X11.   When  calling  the open workstation function the
     application must specify three  parameters:  1)  a  worksta-
     tion  identifier,   which  is an  integer  used  to identify
     this workstation throughout the application; 2) the   works-
     tation   type,   which   is  either one of the strings "MI",
     "MO", or "WISS" (in which case  a  workstation  of  the  ap-
     propriate  type  will be opened) or a null character pointer
     (in which case an X11 window will  be  created);  and  3)  a
     workstation  connection, which is either a file name for the
     metafile workstations  (MI  and  MO)  or  an   X11   DISPLAY
     specification string (see the X man page), or a null charac-
     ter pointer for the X11 workstation (if null, then  the  en-
     vironment variable DISPLAY is consulted).  This last parame-
     ter is  ignored  for  the  workstation  independent  segment
     store   (WISS) workstation.  Ten   workstations    can    be
     open simultaneously;  however,  only  one  WISS  workstation
     can be open.

     There are thirty-one normalization transformations, numbered
     0  to  30.   Transformation  number  zero  is  the  identity
     transformation and cannot be changed.

     Every X11 window workstation has a fixed  device  coordinate
     space that is 0 to 1279 on the X axis and 0 to 1023 on the Y
     axis.  This is not to say that the X window is that big, the
     GKS  workstation  will  be  scaled to fit the X window; this
     scaling preserves the aspect ratio.

     There are twenty bundle  table  entries  for  each  type  of
     bundle table.

     The size of the color table is determined by the X11  window
     server   and   the  hardware  being  used.   The  IBM  apa16
     monochrome display  provides  two  colors  and  the  Megapel
     display supports 255 out of 4096 possible colors.  Each XGKS
     workstation shares the default color  map  of  the  display.
     The  GKS SET COLOR REPRESENTATION function uses the X11 XAl-
     locColor() function to obtain the pixel value of the  color-
     cell  having the color closest to the requested one. The as-
     sociation between GKS colour indices and X11  colorcells  is



XGKS Version 2      Last change: 23 July 1991                  13






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     maintained  in a lookup table.  This mechanism decouples GKS
     colour indices from X11 pixel  values  and  makes  the  XGKS
     client  "friendly"  in  relation to other X11 clients in the
     handling of the X11 colormap.

     GKS color index zero always refers to  the  X  window  back-
     ground  color while GKS color index one refers to the X win-
     dow foreground color.

METAFILES
     Two Metafile formats are supported: GKSM and CGM.  The  GKSM
     format  is a formatted audit-trail of the GKS session: there
     is an almost isomorphic mapping between GKS calls  and  GKSM
     records.   Because  GKSM  is  a formatted encoding, however,
     this format can impose a considerable  storage  requirement.
     Also, the GKSM format is not widely used.

     The CGM format used by XGKS is a subset of the binary encod-
     ing  specified in the ANSI X3.122-1986 standard.  Because it
     is a binary encoding, this format is  more  space  efficient
     than the GKSM format.  It is not quite as powerful, however,
     as it does not record an audit-trail of  the  GKSM  session;
     rather,  it describes a set of independent, static pictures.
     The CGM format is a widely used graphics standard.

     The standard allows several alternative encodings for primi-
     tives  such as floating-point and integer values.  XGKS uses
     the default encodings only.  These are

         REAL PRECISION           Fixed point; whole part 16 bits;
                                  fractional part 16 bits.
         INTEGER PRECISION        16 bits
         COLOUR PRECISION         1 octet (per colour component)
         COLOUR INDEX PRECISION   1 octet
         INDEX PRECISION          16 bits
         VDC TYPE                 INTEGER
         VDC INTEGER PRECISION    16 bits
         VDC EXTENT               (0,0) to (32767,32767)
         COLOUR VALUE EXTENT      minimum is (0,0,0) and maximum
                                  is (255,255,255).

     This CGM form is compatible with the NCAR Graphics package.

     The type of Metafile is selected by the Metafile's filename.
     Filenames  containing  the string ".cgm" (or ".CGM") are as-
     sumed to be in CGM format; all other files are assumed to be
     in GKSM format.

X-RESOURCES
     The following X-resources and their parameters are  searched
     for by the XGKS library:




XGKS Version 2      Last change: 23 July 1991                  14






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     program.backingstore: on|off
         Whether or not the server should use the X backing-store
         feature for windows created by this application.  Wheth-
         er  the  backingstore  feature  is  enabled  by  default
         depends on the capability of the X server: if the server
         can use backingstore, then it's enabled by default; oth-
         erwise it's disabled by default.

     Xgks.Backingstore: on|off
         Whether or not the server should use the X backing-store
         feature for the entire class of XGKS applications.

     program.background: color
         Color for the background of the XGKS window for  program
         program.   The string color must be understood by the X-
         server (.e.g "MidnightBlue").

     Xgks.Background: color
         Background color for the entire class of  XGKS  applica-
         tions.

     program.foreground: color
         Color for the foreground of the XGKS window for  program
         program.   The  string  colorP must be understood by the
         X-server (.e.g "white").

     Xgks.Foreground: color
         Foreground color for the entire class of  XGKS  applica-
         tions.

     program.geometry:  XSIZExYSIZE[+-]xoff[+-]yoff
         Geometry in pixels for the XGKS window of  program  pro-
         gram.

     Xgks.Geometry:  XSIZExYSIZE[+-]xoff[+-]yoff
         Geometry in pixels for the entire class of XGKS applica-
         tions.

     program.iconic: on|off
         Initially, map the XGKS window as an icon rather than as
         a normal window.

     Xgks.Iconic: on|off
         Initially, map the entire class of XGKS windows as icons
         rather than as normal windows.

     program.reverse: on|off
         Reverse foreground and background  colors  in  the  XGKS
         window of program program.

     Xgks.Reverse: on|off
         Reverse foreground and background colors for the  entire



XGKS Version 2      Last change: 23 July 1991                  15






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



         class of Unidata XGKS applications.

     program.softclipping: on|off
         Enable or disable the soft-clipping  of  polylines.   By
         default,  XGKS  defers the clipping of output primitives
         to the X Window System. This works reliably only if  the
         normalized device co-ordinates (NDC) of the output prim-
         itives are relatively  close  to  the  NDC  [0,1]  unit-
         square.  Due  to wrap-around in the NDC-to-X co-ordinate
         transformation, very large NDC values  might  cause  ex-
         traneous  lines to appear in the display window.  Though
         this behavior is server-dependent, it  typically  occurs
         when  displaying  a  small  portion  of a large graphic.
         Soft-clipping  causes  XGKS  to  clip  polyline   output
         against  the  current  NDC clip-window before calling X;
         thus eliminating extraneous lines but incurring some ad-
         ditional  computational overhead.  Because this behavior
         is server-dependent, we  suggest  you  use  the  default
         (i.e.  no soft-clipping) until the problem manifests it-
         self.

     Xgks.Softclipping: on|off
         Enable or disable soft-clipping for the entire class  of
         Unidata XGKS applications.

USING X-RESOURCES
     The following pseudo-code details the sequence of steps tak-
     en  to initialize the program-specific, internal, X-resource
     database.  Definitions encountered during later steps  over-
     ride earlier ones.

         Clear internal X-resource database;
         if (file /usr/lib/X11/app-defaults/program exists) {
                                  Merge its definitions into the database;
         }

         if (X-server has an X-resource database) {
                                  Merge its definitions into the database;
         } else if (file ~/.Xdefaults exists) {
                                  Merge its definitions into the database;
         }

         if (environmental variable XENVIRONMENT exists) {
                                  Merge the definitions in file $XENVIRONMENT into the database;
         } else if (file ~/.Xdefaults-hostname exists) {
                                  Merge its definitions into the database;
         }

     Notes:

     1)  The X-server may have its  X-resource  database  updated
         via the xrdb(1) utility.



XGKS Version 2      Last change: 23 July 1991                  16






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     2)  Program is the name of the program as given  in  argv[0]
         (e.g. "xsfcwx").

     3)  Hostname is the name of the host returned by hostname(3)
         (e.g. "groucho").

PROGRAMMING
     Here is a simple XGKS program that displays "Hello World" in
     the   center  of  the  default  workstation  window.   After
     displaying the greeting, the program  uses  a  choice  input
     device to wait for the user to press the break key.  This is
     done because the X window that represents  this  workstation
     is  removed  from  the  screen as soon as the workstation is
     closed.  The for loop in the main program  is  a  convenient
     way  for  the  application  to allow the user to specify the
     workstation  connection  id  on  the  command  line  via   a
     hostname:serverNumber  pair.   If  the  connection id is not
     specified  XGKS  will  use  the  value  of  the  environment
     variable DISPLAY in the users environment.

     #include <stdio.h>
     #include <xgks.h>

     /*
      * This function is called when the program is finished
      * and we just want to wait until the user is done looking
      * at the output.  Here we set up a choice device to use
      * the function keys. However, we ignore all choices and
      * wait for the user to press the Break key.
      */
         static void
     WaitForBreak(wsid)
         Gint wsid;
     {
         Gchoice init;
         Gchoicerec record;
         Glimit earea = { 0.0, 1279.0, 0.0, 1023.0 };

         gmessage(wsid, "Done, press Break to quit ...");

         init.status = GC_NOCHOICE;
         init.choice = 0;
         record.pet1.data = NULL;
         ginitchoice(wsid, 1, &init, 1, &earea, &record);
         gsetchoicemode(wsid, 1, GREQUEST, GECHO);
         while (init.status != GC_NONE)
             greqchoice(wsid, 1, &init);
     }

     /*
      * set up various text parameters and print "Hello World"
      */



XGKS Version 2      Last change: 23 July 1991                  17






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     PrintHello()
     {
         Gpoint tpt;
         Gpoint up;
         Gtxfp txfp;
         Gtxalign align;

         txfp.font = 4;           /* use Serif Bold Roman font */
         txfp.prec = GSTROKE;
         gsettextfontprec(&txfp);

         gsetcharexpan(0.5);
         gsetcharspace(0.2);
         gsettextcolorind(1);   /* should be white */

         gsetcharheight(0.05);

         up.x = 0.0; up.y = 1.0;  /* characters are straight up */
         gsetcharup(&up);

         align.hor = GTH_CENTER;
         align.ver = GTV_HALF;
         gsettextalign(&align);

         gsettextpath(GTP_RIGHT); /* print from left to right */

         tpt.x = 0.5; tpt.y = 0.5;/* center of the window */
         gtext(&tpt,"Hello World!");
     }

     main(argc,argv)
         int argc;
         char *argv[];
     {
         int i, wsid=1;
         char *conn = (char*)NULL;

         for (i=1; i<argc; i++) {
             if (index(argv[i], ':'))
                 conn = argv[i];
             /* Application dependent options here */
         }

         gopengks(stdout,0);

         if (gopenws(wsid, conn, conn) != 0)
             exit(0);
         gactivatews(wsid);

         PrintHello();
         WaitForBreak(wsid);




XGKS Version 2      Last change: 23 July 1991                  18






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



         gdeactivatews(wsid);
         gclosews(wsid);

         gclosegks();
         exit(0);
     }

     To compile the program, we use the following command line (NB: ${prefix}
     is the root of the installation-tree):

         cc hello.c -o hello -I${prefix}/include -L${prefix}/lib -lxgks -lX11 -lm

     Or, if on an Apollo workstation:

         cc hello.c -o hello -I${prefix}/include -L${prefix}/lib -lxgks -L/usr/lib/X11 -lX11 -lm

     To execute, just type:

         hello

     (NB: you must be running an X server when you run  any  XGKS
     application.)

     Similarly, to compile a  Fortran-based  XGKS  program  (e.g.
     hello.f), we use:

         f77 -O -o hello hello.f -L${prefix}/lib -lxgks -lX11 -lm

     or, if using an Apollo workstation:

         f77 -O -o hello hello.f -L${prefix}/lib -lxgks -L/usr/lib/X11 -lX11 -lm

     or, if using an HP 9000/720 workstation:

         f77 -O -o hello hello.f -Wl,-L,${prefix}/lib -lxgks -Wl,-L,/usr/lib/X11R4 -lX11 -lm

     When the program opens the GKS workstation  the  X11  window
     system  will  prompt  the  user  to  open a new window.  The
     program will display "Hello World!" and then  wait  for  the
     user  to  press  the  Break  key.  While the GKS workstation
     window is on the screen the user can  resize,  move,  cover,
     and   uncover   the  window  and  XGKS  will  take  care  of
     redisplaying the greeting.

FILES
     In the following, ${prefix} is the root of the  installation
     directory-tree  as defined by the Makefile macro of the same
     name.

     ${prefix}/lib/libxgks.a     The XGKS library.
     ${prefix}/lib/xgksfonts     Font data-base directory.
     ${prefix}/bin               Directory containing sample pro-



XGKS Version 2      Last change: 23 July 1991                  19






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     grams.
     ${prefix}/include/xgks.h    C header-file.

ENVIRONMENT
     XGKSFontDir, if set, contains the pathname of the  directory
     which  contains  the  XGKS  fonts.   If  not  set,  then the
     compiled-in pathname is used (see FILES).

SEE ALSO
     X(1), xrdb(1), xterm(1).

     Computer Graphics - Graphical Kernel System (GKS) Functional
     Description.  ANSI, X3.124-1985.

     C Language Binding of GKS. ANSI X3H34/83-12R5, March 1986.

     Computer  Graphics,  Donald   Hearn   and   Pauline   Baker,
     Prentice-Hall, 1986.

     The X Window System, Robert W. Scheifler and Jim Gettys, ACM
     Transactions  on  Graphics,  volume 5, number 2, April 1986,
     pp. 79-109.

BUGS
     The only workstations currently supported are X,  GKSM,  and
     CGM.

     Support for input Metafiles is primitive, at best.

     The decoupling between GKS colour-indices and X pixel values
     is  primitive at best.  Also, an XGKS window always uses the
     default colormap.

BUG REPORTING
     Bugs reports should be  sent  to  xgks-bugs@unidata.ucar.edu
     [128.117.140.3].   Please include a potential fix, if possi-
     ble.

MAILING-LIST
     A mutual-aid society, electronic mailing-list  exists.   Re-
     quests     to    join    should    be    sent    to    xgks-
     request@unidata.ucar.edu [128.117.140.3].

AUTHORS
     Greg Rogers (grogers@a.cs.uiuc.edu)
     Sung Hsien Ching (ksung@a.cs.uiuc.edu)
     Yu Pan
     Steve Emmerson (steve@unidata.ucar.edu)

     This project was supported by IBM ACIS and was  directed  by
     Professors  Bill  Kubitz  and  Roy  Campbell of the Graphics
     Workstation Research Group, Department of Computer  Science,



XGKS Version 2      Last change: 23 July 1991                  20






XGKS(3)                C LIBRARY FUNCTIONS                XGKS(3)



     at  the University of Illinois in Urbana, Illinois.  Special
     thanks go to David Berkowitz and Terry Rowan, our  IBM  con-
     tacts,  who helped us get early versions of the X server for
     our workstations.

     Maintenance of XGKS by the Unidata Program  Center  is  sup-
     ported  by  the National Science Foundation.  Special thanks
     to all those in the user community  who  contribute  to  its
     evolution.














































XGKS Version 2      Last change: 23 July 1991                  21



--------End XGKS manual page
