SPD Update 3.1a - August 17, 1993
=================================

Document by Eduard Schwan

Introduction
------------

SPD is a suite of raytracer scene generators, which can be used as benchmark
databases for timing tests.

The SPD source code is being distributed as "Public Domain".  These Macintosh
applications are also being distributed as public domain, no copyrights, no
guarantees, no restrictions on their use or distribution.

The Macintosh port of SPD is contained in two archives:  SPDSCM.CPT contains
the SPD Mac Source code, for Think C or MPW C.  SPDAPM.CPT contains the SPD
Mac Applications, ready to run.

There are also IBM PC versions of these archives available.

This document will describe the Macintosh-specific information for these SPD
archives.

These programs were written to be very simple.  There are no frills, and not
much error checking.  They are meant to quickly crank out source files for
raytracers.  Specifically, the "Display to Screen" code for the Macintosh is
not very robust.  It works as a simple previewer on color Macintoshes, but it
does not buffer offscreen, nor does it check for Color Quickdraw before
calling display routines.  Be forewarned!  :-)


Requirements
------------

The software requires a minimum Macintosh hardware and software configuration
to run:
- System 6.0.4 or higher, Runs fine on 7.0 and 7.1.
- 68020 or higher CPU, does not require an FPU (Mac LC's and Quadras work
  fine.)
- Under System 6, at least 1 MB memory is recommended.  Under System 7, at
  least 2 and preferably 4 MB is recommended.
- Color Quickdraw*.  If running System 6, you must have a color Macintosh (not
  an SE or Plus.)  Under System 7, Color Quickdraw is installed on all
  machines.

* Color QD is not required if writing to an output file, only if displaying
  the image to the screen.


Features
--------

The Mac SPD is relatively MultiFinder friendly, letting you switch out on
large file generations.  SPD will continue to work in the background.
However, please see the Bugs section for some cosmetic annoyances with
switching out.


How to Use
----------

To run any one of the SPD applications:
(1) Double-click the application you want to run.
(2) Select the output format from the popup menu.
(3) Type in a number for the size,
-or- Select an input DXF file for the SHOWDXF application.
(4) Click the OK button, and the scene will be generated.
    - If it is to the screen, the scene will be displayed immediately, in a
      window.
    - If it is for a specific raytracer, it will create a textfile in the same
      folder as the application, called APPNAME.out (e.g., the application
      "rings" would create a file called "rings.out".)
(5) Now run your favorite raytracer, and display and time the image.

NOTE:  POV-Ray Macintosh cannot open scene files larger than 32k bytes, and
many SPD files will be much bigger than this.  To get around this, just create
a POV-Ray file whose sole purpose in life is to include the large .OUT file
(e.g.  "rings.pov".)  If you want to edit the .OUT file, you will need to use
a "real" text editor or word processor that doesn't have the 32k limitation.


Bugs
----

MacSPD does not set the file creator to anything.  The output file is of type
text, but with no creator.

If you switch out while drawing to the screen, and then switch back, the
display window is not refreshed.

If you switch out and then switch back while writing an output file, the
"Please Wait" dialog is not refreshed.

Low memory conditions are not gracefully handled.  If you get an error, try
increasing the application memory size from the Finder.

Color Quickdraw is not explicitly checked for on program startup.  If your run
an SPD program on a non-Color QD Mac, it will run OK if you write to a file,
but if you try to display to the screen, it will display an error dialog and
quit.


Notes
-----

Larger size values may require that you increase the Application Memory Size.
If you have limited memory and only want to create small sized files, you can
get away with lowering the App.  Memory Size, probably down to about 500K.

Currently, the only raytracers I know about for the Macintosh that the SPD
programs support are:
  POV-Ray
  RTrace
  RayShade
The Macintosh versions of these raytracers can be found on the internet (ask
Eric Haines at erich@eye.com for addresses), and POV-Ray can also be found on
CompuServe (GO GRAPHDEV) and on America Online (Keyword:PGR, Company Support.)


Source Notes
------------

To compile under MPW 3.x, you will first need to rename the file
"makefile.mac" to "makefile".  Then you can build the apps.

To compile under Think C, you will need to create a project for each app.
Files needed by every app:
  MacSPD.rsrc
  lib.c
  libvec.c
  mac.c

Files needed by each app:

Balls:
  Balls.c

Driver
  Driver.c

Gears
  Gears.c

Mount
  Mount.c

Rings
  Rings.c

ShowDXF
  ShowDXF.c

Teapot
  Teapot.c

Tetra
  Tetra.c

Tree
  Tree.c

App Signature	should be	'SPDm'


Credits & Information
---------------------

Eric Haines wrote the original SPD software.

Alexander Enzmann added the additional Raytracer support and did the original
port to the IBM PC and the Macintosh (in Think C.)  He also created the DRIVER
and SHOWDXF data bases.

Eduard Schwan updated the Macintosh code to work with MPW C as well as Think
C, added the initial dialog box to prompt for the "command line parameters",
and created the PLATFORM_XXX stuff to make the code even more portable.

If you have any comments, questions or bug reports for the Macintosh version
of these applications, please feel free to contact me.

Enjoy!

Eduard [esp] Schwan
  CIS: 71513,2161
  internet: 71513.2161@compuserve.com
  AppleLink: JL.Tech
