Logo Ygl Version 4.2 Description

©opyright 1993-2007 by Fred Hucht (fred(AT)thp.Uni-Duisburg.DE)

Ygl is distributed in terms of the GNU Lesser General Public License (LGPL). Please see the file LICENSE for further details. You may not distribute this project without this file (ReadMe.html) and the license file included.

Here you can read the Changes history and the Ygl FAQ.

Description

Ygl emulates SGI's GL routines under X11. It compiles fine under AIX >3.2, HP-UX >7.0, Linux with XFree/Xorg, SunOS, ConvexOS, Mac A/UX, Mac OS/X and many others, but needs an ANSI-C compiler (gcc is ok). It was written for two reasons: Included are most of the two-dimensional graphics routines, the queue device routines, the query routines, doublebuffering, RGB mode with dithering, window attribute routines, FORTRAN bindings and more (see below).

3D stuff was added with version 4.0 using OpenGL calls.

Since Version 2.8, all Ygl functions do have a FORTRAN interface. The FORTRAN versions of all functions have an underscore appended, so the FORTRAN compiler must append a '_' to all function names. f2c does this, xlf (under AIX 3.2) requires the option -qextname. See smile_f77.f for an example program. Set FortranBindings to 0 in Imakefile or change Makefile.std if you don't want these bindings. FORTRAN bindings are not tested because I have no programs.f to test. If you find bugs, feel free to report them to me.

You can always find the latest version of Ygl in the directory ftp.thp.Uni-Duisburg.de/pub/source/X11/.

Note that perl, python and tcl bindings for Ygl are available here thanks to Prabhu Ramachandran.

Details

Environment variables:

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

Doublebuffering:

Ygl supports doublebuffering via the XServer extensions "DOUBLE-BUFFER" (new in X11R6.1) and "Multi-Buffering". The related routines are doublebuffer(), swapbuffer() and singlebuffer().

Notes:

OpenGL:
You can use the routine gsync() to wait for the next vertical retrace. If you use doublebuffering, it might help to set the environment variable __GL_SYNC_TO_VBLANK to 1 to swap buffers at a vertical retrace.
X11R6.1:
If you have X11R6.1 or later, set DoubleBuffer to 1 in Imakefile.
AIX < 3.2.5:
The extension "Multi-Buffering" 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").
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.
AIX >= 4.1:
You need the LPP X11.adt.ext to compile Ygl with doublebuffering enabled.

RGB mode:

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, i.e.:
 Colormap mode <-> PseudoColor, StaticColor,
                   GrayScale, StaticGray,
                   TrueColor or DirectColor visual

 RGB mode      <-> TrueColor or DirectColor visual
A RGB mode window is a child of the initially created colormap mode window. Ygl uses the property WM_COLORMAP_WINDOWS to tell the window manager, which colormaps are to be installed. To toggle the colormaps when a RGB window is subwindow of a colormap window, use the window manager function f.colormap in twm or f.next_cmap in mwm. Ygl will automatically dither all output if the X-Server doesn't support 24 bits. See the section environment variables for details.

Multiple Expose events (REDRAW) in qread:

Ygl ignores all Expose events that have e.xexpose.count != 0 (see XExposeEvent(3X11)) AND all Expose events when another Expose event for the same window is in the Event queue. This procedure minimizes unnessesary redraws. Nevertheless, a REDRAW event is generated when a window is moved even when the contents of the window does not have to be redrawn. This is to be compatible with SGI's GL, where no extra event for window moves exist :-(

Automatic 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 above). The system 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.

Supported routines

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

Window related routines:

minsize, maxsize, prefsize, prefposition, stepunit, keepaspect, winopen, winclose, gconfig, gexit, wintitle, winset, winget, getsize, getorigin, getXdpy, getXwid, getbutton, getvaluator, winmove, winposition, ginit, winpop, winpush, windepth, swinopen, winconstraints, noport, noborder, winX.
Note: The routine winX(Display *dpy, Window win) will ignore the first argument dpy. Ygl always uses the XServer specified in the environment variable DISPLAY.

Color related routines:

RGBmode, RGBcolor, cmode, color, mapcolor, getplanes, getmcolor, getmcolors, getcolor, gRGBcolor, c3s, c3i, c3f, cpack.

Device related routines:

tie, noise, isqueued, qdevice, unqdevice, qreset, qtest, qread, qenter,
Notes:

Menu routines:

defpup, newpup, addtopup, dopup, freepup, setpup.
Note: The routines addpup() and defpup() accept an additional modifier '%M'. If you define a submenu anchor with '%M' instead of '%m', Ygl calls the function defined with '%F' with the two arguments menu-return and submenu-return, i.e.:
int callback(Int32 m, Int32 s) {
  sleep(s);
  switch(m) {
  case 1: explode(); break;
  case 2: implode(); break;
  }
  return(m << 8 + s);
}

main() {
  ...
  sub  = defpup("Seconds%t|1|2|3|4|5");
  menu = defpup("Menu%t%F|Explode%M|Implode%M",	callback, sub, sub);
  ...
}
See examples/popup.c for details.

Font routines:

loadXfont, font, getfont, getfontencoding, getheight, getdescender, strwidth, charstr.

Doublebuffer routines:

singlebuffer, doublebuffer, swapbuffers, frontbuffer, backbuffer.

Misc routines:

gflush, gsync, gversion, rectzoom, lrectread, lrectwrite, rectcopy, readsource, rectread, rectwrite, readpixels, writepixels, readRGB, writeRGB, blendfunction, linewidth, getlwidth, deflinestyle, setlinestyle, getlstyle, lsrepeat, getlsrepeat, logicop, getdisplaymode, getgdesc, setbell, ringbell.

Coordinate transformation routines:

ortho2, viewport, getviewport, reshapeviewport, pushviewport, popviewport, getmatrix.

Drawing routines:

clear, pnt2s, pnt2i, pnt2, move2s, move2i, move2, rmv2s, rmv2i, rmv2, draw2s, draw2i, draw2, 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, sboxf, concave, pmv2s, pmv2i, pmv2, rpmv2s, rpmv2i, rpmv2, pdr2s, pdr2i, pdr2, rpdr2s, rpdr2i, rpdr2, pclos, poly2s, poly2i, poly2, polf2s, polf2i, polf2, bgnpoint, endpoint, bgnline, endline, bgnclosedline, endclosedline, bgnpolygon, endpolygon, v2s, v2i, v2f, v2d, cmov2s, cmov2i, cmov2, getcpos.
Note: It's not possible to change drawing attributes (color, ...) in the middle of a vertex pipeline in Ygl. This affects the routines {bgn|end}{point|line|closedline|polygon}() and pdr(), rpdr().

3D routines

Drawing:

c4s, c4i, c4f, cmovs, cmovi, cmov, pnts, pnti, pnt, moves, movei, move, draws, drawi, draw, rmvs, rmvi, rmv, rdrs, rdri, rdr, pmvs, pmvi, pmv, rpmvs, rpmvi, rpmv, pdrs, pdri, pdr, rpdrs, rpdri, rpdr, polfs, polfi, polf, v3s, v3i, v3f, v3d, v4s, v4i, v4f, v4d, swaptmesh.

Coordinate Systems:

ortho, lookat, window, perspective, polarview, rot, rotate, scale, translate, loadmatrix, multmatrix, pushmatrix, popmatrix, getmmode, mmode.

Polygon specs:

shademodel, n3f, normal, backface, frontface.

z-Buffer:

zbuffer, zclear, zdraw, zfunction, czclear, depthcue, lRGBrange, lsetdepth, lshaderange.

Display lists:

genobj, isobj, makeobj, getopenobj, closeobj, callobj, delobj.

Misc:

lmbind, lmcolor, lmdef, RGBwritemask, pushattributes, popattributes, scrmask.

Picking/Names:

pick, endpick, picksize, initnames, loadname, pushname, popname.

NOPs:

foreground, drawmode, iconsize, overlay, fullscrn, endfullscrn.

Routines not in SGI's GL:

The following routines are added to standard GL:

Acknowledgements

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

GL is a registered trademark of Silicon Graphics, Inc.