DKBTrace 2.04




This ray tracer was written by David K. Buck and is released as freely
distributable software. The author retains all copyrights but permits
free distribution of the software through any medium. The software may
be used without charge so long as the code is not included in any
commercial product.


The Amiga archive contains two versions of the raytracer:

traceffp - Fast Floating Point version of the raytracer.
This version will run on any Amiga with sufficient
memory.

trace881 - Math coprocessor version. This version will only
run on 68020 or 68030 based systems that have a
68881 or 68882 math coprocessor.


I usually like having a fairly large stack for this program. If it
crashes on you, try inceasing the stack size.


The IBM/MS-DOS archive also contains two versions of the raytracer:

dkbno87.exe - Emulated Floating Point version of the raytracer.
This version will run on any IBM P.C. or Compatible
machine, as it is compiled for 8088 opcodes.

dkb.exe - Math coprocessor and 80186 or better ('286, '386, etc.)
optimized version of the raytracer. Requires a 80x87 NPE.

These files were compiled using Microsoft C 6.0 with maximum optimization,
so it should be a LOT faster than previous versions. There are MAKEFILE's
and link files (.lnk) provided for both MSC and for Turbo-C 2.0, for
compatibility with prior versions. Note, however, that Microsoft C's
execution time is fully 20% faster than Turbo-C's!

This version has been fed through four different compilers at their
maximum warning levels, and then through a VERY picky "LINT", so it should
be edible by very nearly all decent "C" compilers. Also, all memory
allocation functions are checked carefully for memory size limitations.

The stack size in this version is set to about 12K which should be enough
to do tracing of scenes with about 550K free RAM. If it dies while it's
tracing (it hasn't for me, yet, but that should be about the only reason
it ever would, now...) chances are you may need to increase the stack size
a bit. I have the internal stack checking option off for additional speed
when tracing. Currently the stack size is set at 3000H, but more can be
easily allocated with the Microsoft EXEMOD or EXEHDR utilities, or even
with DEBUG, if you're a real die-hard hacker. I would suggest trying 3800
or 4000H, but not too much more. The more stack you have will mean less
memory will be available for complex objects.

If you run into a scene which is too complex to parse with 640K of memory
(as evidenced by an allocation error message during the "Parsing" phase),
QuarterDeck's QRAM or VIDRAM are programs which will extend DOS memory to
704K/740K using either EMM or Video RAM memory, respectively. There are
also Public Domain programs (such as 740K.COM/SYS (?)) that will accomplish
the same thing. MAKE SURE you use the -d (no display) option if you use
one of these programs or upper memory corruption could occur!!

The raytracer will use up to ALL available DOS linear memory, but no EMM
or XMS support is present at this time.

In addition, the following utilities are provided (these will run on any
Amiga system).

DumpToIFF - Converts the raw 24 bit output files of the raytracer into
hires HAM images.

syntax:
DumpToIFF [options] input-file [output-file [palette-file]]

options are:
-d Suppress Floyd Steinberg dithering
-pfilename Output a colour palette for the picture

The colour palette for one image may be used in other images.
This is useful for animations in order to force the entire
animation to use the same colour palette.

eg.
DumpToIFF -pmyImage.palette myImage.dis myImage.ham
DumpToIFF myImage2.dis myImage2.ham myImage.palette


Dump2RGB - Converts the raw 24 bit output files of the raytracer into
three separate dump files for red, green and blue. Note
that the extension .DIS is assumed for input files, so
"input-file" should not specify any file name extension.
The extensions .red, .grn, and .blu will be automatically
supplied for the color-separated output files.

syntax:
Dump2RGB [options] input-file

options are:
-wxxx Output image width
-hxxx Output image height

Dump2Raw - Same as Dump2RGB but takes the size from the input file
and uses less memory. This takes no size options.

syntax:
Dump2Raw input-file (no extension, .DIS assumed for input)

Sculpt2DKB - Converts a Sculpt-Animate 3D .scene file into DKB format.
At the current time, smoothed triangles are not supported. The
only information converted is the information on the polygons,
the colours, and the textures. Lightsources, viewpoints, and
world information is currently ignored.

syntax:
Sculpt2DKB scene-file dkb-dat-file

You must edit this file after the conversion to add a viewpoint
and lightsources as needed.

The IBM / Compatible version has all the above but DumpToIFF, plus the
following two utilities:


GlueTGA - Glues several .TGA (TARGA-24) files together into one.
Uses the Y-offset in the header to insert the pieces
into their respective positions in the final image.
Takes the image size from the first supplied input file's
header. This is for putting together several pars of
an interrupted trace. The .TGA extension is assumed, and
will be added to file names if not otherwise specified.

syntax:
GlueTGA output-file input-file [input-file]...

HalfTGA - Shrinks a .TGA (TARGA-24) file to half it's X and Y size.
For reducing size of output images on lower resolution
systems. Does not interpolate colour values, just drops
odd pixels. Extension of .TGA is also assumed and added
if not specified for files.

syntax:
HalfTGA input-file output-file

Also, a notable difference from the Amiga to the IBM is that the DUMP2RAW
utility writes .red, .grn and .blu file extensions on the Amiga, but uses
.r8, .g8, and .b8 respectively on the IBM. This is to be compatibile with
the PICLAB post-processor's "RAW" format


The main program documentation can be found in the file DKB.DOC and the
documentation for the Amiga specific utilities may be found in the
file AmigaUtils.doc. The IBM utilities are simple enough that the usage
messages should be practically self-explanatory.

This program is being distributed in four separate packages:


DKBTrace.zip: Executables for dkb.exe and dkbno87.exe
documentation files
Sculpt2DKB, Dump2RAW, GlueTGA, HalfTGA executables

DKBData.zip: Many sample data files

DKBSrc.zip: Source code for DKBTrace, Amiga utilities, and
IBM Utilities.

DKBPics.zip: Sample pictures produced by the raytracer.
(You could render these yourself using the
data files in the DKBData.zip archive).


There is a document in the DKBTrace.zip archive which describes the
conversions required to use data files for DKBTrace version 1.2 with
the new 2.04 version. This file is called 12to20.doc.

This readme file is in all three archives.