Provided by: libxgks-dev_2.6.1+dfsg.2-12_amd64 bug

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]);

       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);

       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);

       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);

       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);

       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);

       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);

       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);

       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);

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

DESCRIPTION

       XGKS  is  an  implementation of the ANSI Graphical Kernel System 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
       reference  for  any  programmer  is  the C binding manual which details 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

       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 indicate otherwise.

       gescsetprogname() sets the program name by which the application 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 workstation 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 function 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
       symbolic 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
            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  application  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   general, 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  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 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
       workstation  identifier,   which  is  an   integer   used   to  identify  this workstation
       throughout the application; 2) 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 character  pointer  for  the  X11  workstation  (if  null,  then  the
       environment  variable  DISPLAY  is  consulted);  and 3) the  workstation  type,  which  is
       either one of the strings "MI",  "MO", or "WISS" (in  which  case  a  workstation  of  the
       appropriate  type will be opened) or a null character pointer (in which case an X11 window
       will be created); The workstation connection parameter  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 XAllocColor() function to obtain the pixel value of the  colorcell  having  the  color
       closest  to  the  requested  one.   The  association  between  GKS  colour indices and X11
       colorcells is 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 background color while GKS color  index
       one refers to the X window 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  encoding  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 primitives  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 assumed 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:

       program.backingstore: on|off
           Whether  or  not the server should use the X backing-store feature for windows created
           by this application.  Whether 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; otherwise 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 applications.

       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 applications.

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

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

       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.beep: on|off
           Controls whether or not the bell sounds during interactive input in the XGKS window of
           program program.  The default is off.

       Xgks.Beep: on|off
           Controls  whether or not the bell sounds during interactive input for the entire class
           of XGKS applications.  The default is off.

       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 primitives 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 extraneous 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 additional computational overhead.   Because  this
           behavior  is  server-dependent, we suggest you use the default (i.e. no soft-clipping)
           until the problem manifests itself.

       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 taken to initialize  the  program-
       specific,  internal,  X-resource  database.   Definitions  encountered  during later steps
       override earlier ones.

           Clear internal X-resource database;

           if (file /usr/lib/X11/app-defaults/program exists)
                  Merge its definitions into the database;

           if (environment variable XAPPLRESDIR exists)
                  Merge the definitions in file $XAPPLRESDIR/program 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 (environment variable XENVIRONMENT exists) {
                  Merge the definitions in file $XENVIRONMENT into the database;
           } else if (file ~/.Xdefaults-X-server_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.

       2)  Program is the name of the program as  set  by  the  gescsetprogname()  function  (see
           ESCAPE FUNCTIONS).

       3)  X-server_hostname  is the name of the first host to which XGKS connects as returned by
           the X function DisplayString().  (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 <string.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"
        */
       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 (strchr(argv[i], ':'))
                   conn = argv[i];
               /* Application dependent options here */
           }

           gopengks(stdout,0);

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

           PrintHello();
           WaitForBreak(wsid);

           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 programs.
       ${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 possible.

MAILING-LIST

       A mutual-aid society, electronic mailing-list exists.  Requests 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,  at
       the  University of Illinois in Urbana, Illinois.  Special thanks go to David Berkowitz and
       Terry Rowan, our IBM contacts, who helped us get early versions of the X  server  for  our
       workstations.

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