SPD Update 3.3f4 - August 7, 1994
=============================

Macintosh SPD
Document by Eduard Schwan

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

SPD is a suite of raytracer scene generators, which can be used as benchmark
databases for timing tests.  For a full description, see the file README.

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 the archive MACSPD.SIT contains
the SPD Mac Source code, for Think C or MPW C, and 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 Mac 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 unless
calling the screen 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, your Macintosh should have at least 2 MB memory.  Under
  System 7, at least 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 QuickDraw 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.  It is a straight Macintosh application, with an initial
dialog box to gather input (i.e. command line) information.


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

To run any one of the SPD applications:
(1) Double-click the application you want to run.
(2) Select the output raytracer format from the popup menu.
(3) Type in a number for the size,
    -or-
    Select an input file for the READDXF/READNFF applications.
(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 main scene files larger than 32k bytes,
and many SPD files will be much bigger than this.  To get around this, create
a small 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. As an un-typed text file, you should not
double-click it to open it.  Instead drag-n-drop it on your favorite word
processor, or run the word processor and open it from the file menu.

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

Low memory conditions are not gracefully handled.  If you get an error, try
increasing the application memory size from the Finder's "Get Info" window.

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 Application Memory Size, probably down to about 600K.

Currently, the only raytracers I know about for the Macintosh that the SPD
programs support are:
  POV-Ray
  RTrace
  RayShade
  Renderman
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.)
MacRenderman is a commercial application, and is available from Pixar.


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

MPW:
To compile under MPW 3.x, just type the following:
  BuildProgram MacSPD
That's it, every program will be created.

Symantec:
To compile under Symantec C 7.x, you will need to create a project for each
app.  An empty project file for the Balls application is supplied, ready to
go.  To create the other project files, just duplicate this project file &
rename it for the next application, then remove the "balls.c" source file and
add the new source file in its place.  Compile the project and change its
output application file name from "Balls" to the new application name. For
example, to create the "Gears" application, do the following:
1. Duplicate Balls.¹, and rename the copy to Gears.¹
2. Open Gears.¹, Remove the "balls.c" file, and Add the "gears.c" file
3. Build the Application, and when prompted for an app. file, type Gears
4. Do steps 1 through 3 for each application (balls, gears, lattice, mount,
   readdxf, readnff, rings, sample, shells, teapot, tetra, tree)
Note that I have created an "ANSI-NoConsole" library for these to link to.
You will need to do the same.  Instructions on how to do this are in the
Symantec manual, sorry for the cop-out on instructions.
The project info is:
  Creator: SPDm
  Partition: 800K
  Size Flags: 58C0
  Separate Strs: ON

Metrowerks:
No project file is yet included, simply because I haven't had time.  I have
started to add compiler directives, and it does compile, I just haven't tested
it yet.


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 5.)  He also created the
SAMPLE and READDXF (was showdxf) data bases.

Eduard Schwan updated the Macintosh code to work with MPW C as well as
Symantec C 6 & 7, added the initial dialog box to prompt for the "command
line parameters", added the READNFF database, and created the PLATFORM_XXX
stuff to make the code even more portable, and broke the lib.c file into several
smaller pieces so as to be more grokkable by humans and toy Symantec
compilers.  Metrowerks support is coming soon.

If you have any comments, questions or bug reports for the Macintosh version
of these applications, please feel free to contact me.  General questions on
SPD should be directed to the original author, Eric Haines.

Enjoy!

Eduard [esp] Schwan
  CompuServe: 71513,2161
    internet: 71513.2161@compuserve.com

[eof]
