LIBXG : A LIBRARY FOR GRAPHICS UNDER X11 & Xt This is the second major update of my graph widget and related code. This work is quite old, and it is provided only because I still see requests for doing simple 2-D and 3-D graphics under X, and wanted to add this to the growing list of software that programmers have access to. WHAT IS THIS PACKAGE? This package is a set of library functions targeted toward application developers who want a straightforward way to do simple 2-D and 3-D graphics. The package provides a Display Widget which forms the lowest level and is designed to handle primarily 2-D objects like points, lines, arcs, text. It also has the capability to display gray-scale images. Built on top of this are the Graph and MultiGraph widgets, which are designed mainly to display 2-D data (although Graph can also produce simple contour plots). All the widgets are built directly on top of Xt, and do NOT depend on other widget sets. Consequently, you can (and I frequently do) use them freely with other widgets. Besides the widgets there is an extensive set of functions to create and manipulate 3-D views, and to create and manage lists of polygons. The graphics portion of the library allows such lists of polygons to be associated with an underlying Display widget and a view. Also included are functions to display such polygons in shaded form, in wireframe mode, or with hidden-lines removed. Since these functions use a Display Widget to display the shaded image, you can mix 2D graphics with this 3-D information freely (for example, you can very easily display a text string near a 3-D vertex associated with a polygon). The library by itself is designed to run under bare X, meaning the Display Widget uses Xlib calls to do most of its work. To use this, you DO need to know about what widgets are, and how to use them. It does not currently use any vendor-specific hardware, libraries or optimizations. For interactive performance, the Display Widget provides support for double buffering (with 2 pixmaps) and a host of other features. This is obviously not fast enough to do 3-D shaded polygons but wireframe display is quite smooth without flicker for hundreds of polygons. Just to illustrate how the library can be used, I've included sample plotting programs (in 2/3D), and a viewer for 3-D objects (polygons, lines, points, text). These are meant only to be examples, but since they read their input data from files, they can actually be used directly if this is what you want to do. The 3-D viewer also responds to the mouse and so you can interactively move through your data -- nowhere close to the speeds you can get on special-purpose graphics hardware, but fast enough at times to be acceptable. And last, but not the least, the Display Widget can produce postscript dumps of what was drawn on it. HOW TO INSTALL? Currently the library resides in the subdirectory src. The example programs reside in the subdirectory examples. All include files related to the library are in the subdirectory include. o If you understand imake to compile and test this out: 1. xmkmf -- this will make a Makefile in the current directory 2. make Makefiles -- this will make the Makefile in src and examples 3. make -- try compiling src/libXG.a and examples/{hide,plot,...} o If you don't understand imakefiles. 1. cd src; make -f Makefile.simple ; cd .. 2. cd examples; make -f Makefile.simple ; cd .. As it stands the library will compile in place, and you will be left with the libXG.a archive. You can then copy / install it wherever you wish. To test if things worked, typing ./hide -in hide-1.dat in the examples directory should get you started. Once the data is displayed press shift-Left, shift-Middle and shift-Right and move the mouse to see what it does. As illustrated by this program all you really need to use this library is to link your code with libXG.a and the rest of the usual X libraries like -lXaw -lXmu -lXt -lX11 etc. WHERE IS THE DOCUMENTATION NEEDED TO USE THIS? The man subdirectory contains rudimentary man pages to go with the programs in the examples subdirectory. The doc directory contains a postscript file which, when printed out, should result in a 30 or so page manual wherein most of the functions in the library relating to graphics are documented. WHAT MACHINES DOES THIS RUN ON? I wrote the package originally on Sun-3's. Since then, the package has been compiled and runs successfully on Sparcs and SGI boxes. The original Graph Widget has been, to my knowledge, compiled and run on a variety of architectures. If you port this to other architectures and let me know of the changes you had to make, I will try to incorporate them into the code. If you find bugs, have feedback regarding the code, or suggestions for enhancements, please send them to sundar@ai.mit.edu. WHAT IS THE COPYRIGHT STATUS OF THIS CODE? You will see that most of the code contains something like: (c) Copyright 1989-1992 Sundar Narasimhan, MIT Artificial Intelligence Laboratory. Most of this work was performed at the MIT Artificial Intelligence Laboratory. Permission to use, copy, modify, and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation. This software is provided "as is" without express or implied warranty. I would, of course, appreciate it if you could let me know, should and if you decide to use this piece of software in your work. This is just so I can maintain a list of people whom I might be able to notify in case I (or someone else) finds a major bug in this code. You can reach me at sundar@ai.mit.edu. Have fun.