Provided by: libxgks-dev_2.6.1+dfsg.2-2_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.