Gbench is a graphics benchmark tool.  It currently supports 2D immediate-mode
graphics and runs on top of the X Window System (both Version 10 and Version
11) and Unix.  It is written in C and it directly calls the low-level window
system client library; no toolkit is used.  It is being developed by Craig
Dunwoody and Mark Linton at Stanford University's Computer Systems Lab under
the Quantum project, through a gift from Digital Equipment Corporation.  It may
be freely distributed under the conditions listed in the accompanying copyright
notice.

Gbench is not a graphics benchmark.  Rather, it is a tool that lets you
construct and run your own benchmarks.  When gbench starts up, it creates an X
window and reads commands from standard input, one per line.  Each command
directs gbench to repeatedly perform a particular drawing operation.  Gbench
copies the command line to standard output, executes the command, and prints on
standard output the host load average, the time for each iteration, and the
number of iterations per second.  All times are measured in real (wall-clock)
time.

You can use gbench either interactively, by typing commands and viewing
the results immediately, or in batch mode, with standard input redirected
to a script file and output redirected to a log file.  If you don't want to
create your own script file, there is a built-in default script.

Gbench is primarily intended as a benchmarking tool.  You may also find it
useful as a graphics system exerciser.  If you are developing an application
program, and some graphics operation isn't behaving properly, you may be able
to use gbench to find out if the underlying graphics system implementation is
doing the right thing.  Gbench is NOT, however, intended as a graphics system
verification tool.  It allows you to exercise most of the drawing functions
supported by the graphics server, but for any given function, the only
parameters that gbench lets you vary are those (such as size) that we
consider to be likely to affect performance.

In the future, we hope to extend gbench and provide tools for combining and
formatting raw log files.  Proposed extensions include 3D graphics and
integration with a more comprehensive set of workstation benchmarks.  If there
is interest, we are willing to act as a clearinghouse for benchmark scripts and
results.

This version of gbench represents our first attempt to address the problem of
characterizing graphics performance in a distributed environment.  There are
many complex issues in this area that remain unresolved, and we expect that we
will be able to substantially improve gbench as we learn more.  By making
gbench widely available, we hope to hasten the process of making it as
portable, bug-free, complete, and fair as possible.

We would be most pleased to receive any comments, bugfixes, scripts,
or results that you might have.  We have created a mailing list,
gbench@lurch.stanford.edu, for discussions related to gbench.  To
join, send a message to gbench-request@lurch.stanford.edu.

Gbench source code is available in compressed and uncompressed shar and tar
formats through anonymous FTP to lurch.stanford.edu (36.22.0.14).

The CHANGES file in the distribution is the log of all changes made to
gbench since Version 1.0.

To build gbench:

1.  Copy Makefile-dist to Makefile.

2.  In Makefile, set MACHINE to your machine type.  Gbench has been tested
    with X10 and X11 on machine types VAX, SUN3, and SUN4.  The code should
    be quite portable.  The difference between the VAX and SUN versions
    is in the definition of GetLoad() in utils.c.  When there is a more
    reasonable way to get the load (suggestions are welcome), this problem
    will go away.

3.  In Makefile, set XVERSION to X10 or X11 as appropriate.

4.  In Makefile, add the indicated flags to CFLAGS and LDFLAGS if you want
    to do gprof profiling.

5.  If your X header files are not in /usr/include/${XVERSION},
    create the  symbolic link "X10" or "X11", pointing to the appropriate
    X header file directory, in the main gbench directory.

6.  Make sure that lib${XVERSION}.a exists in your standard library
    directory.

7.  "make"
