			U S A r m y   B R L

		S O L I D   M O D E L I N G   S Y S T E M
				a n d
		R A Y - T R A C I N G   B E N C H M A R K

		D I S T R I B U T I O N   P A C K A G E

Please note that this software and the associated databases and images are
Copyright (C) 1985 by the United States Army.  Unauthorized redistribution
in any form is prohibited.  To obtain authorization for use at additional
sites, or for permission to use this work as part of a commercial
package, please contact the author at the address below.  The intent
is to have a record of all distributions at BRL to facilitate
distribution of updates.

This file describes how to set up the GED and RT programs, and how to
run a benchmark test of the RT ray-tracing program on the three sample
databases provided.  Each run will produce a 512x512x24 bit color
shaded image in a "bench/xxx.pix" file, and a run log in
"bench/xxx.log". Reference copies of are provided as "pix/xxx.pix" and
"pix/xxx.log".  The three sample databases provided are processed in
order of increasing difficulty, and each produces a colorful image.  In
each picture there are two light sources; the primary source is located
near the center of the model (the white ball), and the secondary light
source is located at the "eye" position.

moss-world.g  --  This is a simple model, containing a yellow torus,
a green ellipsoid, a blueish cube, a pink truncated (distorted) cone,
all sitting on a blue plate.  Note the shadowing, and "specular splash".

star.g  --  A familiar sight to Star Trek fans;  a low-detail exterior
of the ship "Enterprise".  The hull is white, with some other structures
in other colors.  The default light position is used.

building.g  --  An exploded view of a two-story imaginary computer site,
including various walls, red stairways, green disk drives, etc.

The RT benchmark requires a binary database for input ("pix/xxx.g"), and
produces a binary image as output ("bench/xxx.pix"), along with a log
file ("bench/xxx.log").  To make this distribution machine independent,
both the databases and the reference copies of the images are provided
in an ASCII format in the "db" and "pix" directories, and
ascii-to-binary converters are provided.

If you have a suitable framebuffer, you are encouraged to try and display
the pictures.  An xxx.pix file is a sequence of 3-byte pixels, written as
RGB tripples in the range 0 to 255.  The first pixel goes in the lower left
corner of the screen, and subsequent pixels write to the right; the next
scan line is displayed above the first one.  (First quadrant display).
Example programs for display on Adage (Ikonas) RDS-3000 displays are
in the "util" directory (pix-ik.c).

If the images computed on your machine do not match the reference images,
the program "util/pixdiff" will compute a .pix file that will highlight
the differences for you.

CONFIGURATION.  The sources have a variety of configuration options.

The file "h/machine.h" has a number of configuration
options, including the setting of:

fastf_t		select the fastest "C" floating point type (float|double)
LOCAL		static|auto, for fastest local data type.
FAST		LOCAL|register, if register fastf_t is faster.

VAX, GOULD, and HEP examples are provided.

Also, "h/vmath.h" has macros for numerous common vector operations; if
your system has hardware support for vector operations, after getting the
program working you would profit greatly from changing these macros to
machine-specific code.  The most important macros are MAT4X3VEC and
MAT4X3PNT.  If you do this, please submit the "rays/sec" figures
for the original as well as the optimized runs.

The file "rt/Makefile" MUST be edited.  First, be certain to uncomment
the "CFLAGS=-O -DBENCHMARK".  This will turn off the penumbra effects,
which if left on would make comparison to reference files impossible.
If your system does not have a framebuffer, run
	cp iklib-dummy.c iklib.c
	cc -c iklib.c

The file "librt/Makefile" MUST also be edited to select the proper
version of "timer*.c", based on the version of UNIX you are using.
Possible choices include 4.2 BSD (timer42.c), System V Release 2
(timer52.c) [this option includes System V Release 1 and System III],
and System V-under-4.2 (timer52brl.c).  The timer*.c module is for
providing CPU and elapsed time indications; if your system has a
vendor-specific clock with more resolution than the normal UNIX libarary
provides, you should create your own system-specific timerXXX.c module.
Also, be sure to specify a special assembler version of sqrt, or delete
the reference to sqrt.vax.o from the end of RTLIB_OBJS.

The file "ged/Makefile" has to be edited if MGED (the model editor)
is to be used.  MGED is not needed to run the benchmark. To compile for a
System V, remove the "-DBSD42" flag. To select the display hardware
supported, edit the last line of the GED_CFILES and GED_OBJS define,
plus change the ATTACH define. Note that the "vg", "mg", "tek", and
"rat" displays are always included. The "ps" (PS300), and "ir" (SGI
IRIS) are optional.  Each also requires a vendor-supplied library
which you must include on the CFLAGS= line.

WARNING:  If you are attempting to run this software on an SGI
IRIS, beware of the "long float" -vs- double controversy.  Software
up to version 3.3.1 (at least) have a defective library version of
hypot(), so you need to add one to complex.c that reads:

long float hypot(a,b)
double a,b;
{
	return( sqrt( a*a + b*b ) );
}
This is less desirable, and slower, but will avoid core dumps.

THE BENCHMARK.

The steps involved in loading the software and running the benchmark
on a UNIX system are these:

1)  Load the distribution.
	mkdir cad
	cd cad
	tar x

2)  Edit the various header files and Makefiles.
	ed h/machine.h
	ed rt/Makefile
	ed ged/Makefile		# not required for benchmark

3)  Compile everything, and convert the databases and reference images.
	make
	make ged		# not required for benchmark

4)  Run the benchmark.  Make sure that the answers match the reference files.
	cd bench
	sh run			# takes several VAX hours.
	cd ..

5)  Compare the execution times in the "bench/xxx.log" files with the
VAX-11/780 (with hardware FPA) times which are given in the
"pix/xxx.log" files.  The significant figure is the "rays/sec" figure,
and should only be compared between different runs on the same model.

5a) FILE:  "pix/moss-world.log"

Rays/sec	*780	Machine & OS
--------	----	------------
12.3		0.18	ISI 68020, no FP hardware (nrtc-gremlin)
69.8		1.00	VAX 780+FPA, 4.2 BSD (brl-vgr)
86.7		1.24	VAX 785+FPA, VMS+Eunice 4.1 (nrtc-??)
254.1		3.64	Gould 9050, no MACC, UTX 1.2, 4Mb mem bds (brl-spark)

5b) FILE:  "pix/star.log"

Rays/sec	*780	Machine & OS
--------	----	------------
30.4		0.18	ISI 68020, no FP hardware
165.9		1.00	VAX 780+FPA, 4.2 BSD
219.9		1.33	VAX 785+FPA, VMS+Eunice 4.1
737.3		4.44	Gould 9050, no MACC, UTX 1.2, 4Mb memory boards

5c) FILE:  "pix/building.log"

Rays/sec	*780	Machine & OS
--------	----	------------
18.9		0.20	ISI 68020, no FP hardware
95.8		1.00	VAX 780+FPA, 4.2 BSD
129.2		1.34	VAX 785+FPA, VMS+Eunice 4.1
443.4		4.63	Gould 9050, no MACC, UTX 1.2, 4Mb memory boards

I would appreciate it if you would return to me any statistics that you
gather, including the manufacturer of the machine, hardware and
software version numbers, presence or absence of floating point hardware,
and the name (ARPANET or UUCP) of the machine used.

Of course, if you find bugs, please report your experiences (by electronic
mail only).  If you develop additional software for this environment that
you would be willing to share, please also send it by electronic mail.

Best,
 -Mike Muuss

(301)-278-6678
  AV  283-6678
  FTS 939-6678

ArpaNet:  Mike @ BRL.ARPA
Postal:
  Mike Muuss
  Leader, Advanced Computer Systems Team
  Computer Science and Mathematics Branch
  Systems Engineering and Concepts Analysis Division
  U.S. Army Ballistic Research Laboratory
  Attn: SLCBR-SECAD (Muuss)
  APG, MD. 21005-5066  USA
