-*-Text-*-
			    /---------------\
			 --( Ygl Version 2.4 )--
			    \---------------/

Copyright (C) 1993/94 by

	Fred Hucht (fred@hal6000.Uni-Duisburg.DE)

Please see the LICENSE file for further details.  You may not
distribute this project without this file (README) and the
LICENSE file included.

Description:
------------
Ygl emulates SGI's GL routines under X11. It was written for two
reasons: 

 - On our RS/6000 GT4 hardware Ygl is up to twenty times faster than
   GL (strange, isn't it?...) 
 - 2D graphics runs on non GL hardware and even on remote X-Servers.

Included are most of the two-dimensional graphics routines, the queue
device routines, some query routines, doublebuffering, RGB mode and
some window attribute routines (see below).


Three environment variables are referenced in the library to control
the behavior of Ygl:

    1) 	The environment variable YGL_PRIVATECOLORMAP or YGL_PCM can be
	set to 1 to force Ygl to use a private colormap. Although GL
	also uses a private colormap, Ygl uses the global map by
	default to avoid technicolor effects on old sabine cards and
	XServers not capable of more than one colormap at a time. Note
	that you can only redefine the color of already drawn objects
	when using a private colormap. 

    2) 	The environment variable YGL_FLUSHTIME or YGL_FT (default
	value: 0.1) can be used to adjust the time in seconds between
	flushes of the graphics pipeline or can be set to 0 to disable
	the automatic update via interval timer.
	Setting YGL_FLUSHTIME to -1 will put the XServer into
	synchronous mode (see XSynchonize). This mode seems to be
	veeeryyy slooow, but is good for debugging... 

    3)  The environment variable YGL_BACKINGSTORE or YGL_BS can be set
	to 1 to enables BackingStore support for all Ygl windows.
	With BackingStore, the X-Server remembers the contents of a
	window when it gets obscured or iconified.
	You must start your X-Server with the option -bs to use this
	feature. 


Ygl supports doublebuffering via the "Multi-Buffering" server
extension.The related GL routines are doubleduffer, swapbuffer and
singlebuffer. 

   Note for AIX < 3.2.5:
   ---------------------
   This extension is new in X11R5 and is included in the lpp
   X11dev.src under AIX. To use doublebuffering you have to link the
   "Multi-Buffering" extension into your X-Server (under AIX, see
   /usr/lpp/X11/Xamples/README, "Linking the Sample Extensions into
   the Server").

   Note for AIX >= 3.2.5:
   ---------------------

   You don't need to recompile the X-Server anymore to use
   doublebuffering under AIX 3.2.5 (AIXWindows 1.2.3). You simply have
   to add the option "-x mbx" to the X-Servers command line on startup.


Ygl can run in a per window RGB mode, if the X-Server has a TrueColor
or DirectColor visual. Ygl will always select the appropiate visual
for the desired mode, independent of the default visual, ie: 

	Colormap mode <-> PseudoColor, GrayScale or StaticGray visual
	RGB mode      <-> TrueColor or DirectColor visual


A note to multiple Expose events (REDRAW) in qread: 
Ygl ignores all Expose events that have e.xexpose.count != 0 (see
XExposeEvent(3X11) AND all Expose events that are directly followed by
another Expose event for the same window. This procedure minimizes
unnessesary redraws.


Something must be said about the flushing of the graphics pipeline:

The process virtual interval timer (see setitimer(3)) is used to flush
the graphics pipeline every 0.1 seconds. This interval is adjustable
(see below). The systems functions sleep() and usleep() are covered by
the library to flush the pipeline, too. This had to be done because
the GL hardware flushes the pipeline automatically on every vertical 
retrace and has no command to flush.

Note that sleep() and usleep() always return 0.

You can use "sleep(0)" to flush the graphics pipeline explicitly.
If you have problems with sleep() and usleep(), undefine COVERSLEEP in
header.h. 


Finally a list of supported GL routines is included. For a detailed
description of the routines see the normal GL manuals in the Info-
Explorer (under AIX). 

Window related routines:
------------------------
  minsize, maxsize, prefsize, prefposition, stepunit, keepaspect,
  reshapeviewport, winopen, winclose, gexit, winset, winget, getsize,
  getorigin, getXdpy, getXwid, getbutton, getvaluator
  winmove, winposition, ginit

Color related routines:
-----------------------
 RGBmode, RGBcolor, cmode, color, mapcolor, 
 getplanes, getmcolor, getcolor, mRGBcolor

Device related routines:
------------------------
  qdevice, unqdevice, qreset, qtest, qread, qenter

Notes: 
  Currently supported devices are: 
  REDRAW, KEYBD, INPUTCHANGE, LEFTMOUSE, MIDDLEMOUSE, RIGHTMOUSE,
  MOUSEX, MOUSEY

  qenter does only support the REDRAW device.

Misc routines:
--------------
  loadXfont, font, strwidth, getheight, getdescender,
  gversion, singlebuffer, doublebuffer, swapbuffers,
  lrectread, lrectwrite, rectcopy, readsource
  rectread, rectwrite

Drawing routines:
-----------------
  ortho2,
  clear,  pnt2s,  pnt2i,  pnt2,
  move2s, move2i, move2,  draw2s, draw2i, draw2, 
  rmv2s,  rmv2i,  rmv2,   rdr2s,  rdr2i,  rdr2,
  arcs,   arci,   arc,    arcfs,  arcfi,  arcf,
  circs,  circi,  circ,   circfs, circfi, circf,
  rects,  recti,  rect,   rectfs, rectfi, rectf,
  sboxs,  sboxi,  sbox,   sboxfs, sboxfi, sboxi,
  pmv2s,  pmv2i,  pmv2,   pdr2s,  pdr2i,  pdr2,
  rpdr2s, rpdr2i, rpdr2,  pclos,  concave, 
  poly2s, poly2i, poly2,  polf2s, polf2i, polf2,
  cmov2s, cmov2i, cmov2,  charstr

Routines not in SGI's GL:
-------------------------
  (GC*) getXgc()
	return pointer to current graphics context.

  Int32 crectread(Screencoord x1, Screencoord y1,
		  Screencoord x2, Screencoord y2,
		  Uint8 *data)
	read screen data to array 'data'.

  void crectwrite(Screencoord x1, Screencoord y1,
		  Screencoord x2, Screencoord y2,
		  Uint8 *data)
	write array 'data' to screen;

  void arcx  (Coord x,Coord y,Coord rx,Coord ry,Angle s,Angle e)
	draw ellipse

  void arcx  (Coord x,Coord y,Coord rx,Coord ry,Angle s,Angle e)
	draw filled ellipse

Acknowledgements:
-----------------
The author would like to thank
Michael Staats (michael@thp.Uni-Duisburg.DE) and
Ralf Meyer (ralf@thp.Uni-Duisburg.DE) for some hints and tips.
