4th July, 1998 RayChase README
-----------------------------------------------------------------------------

1) platform specific notes
2) introduction
3) how the heck do I use it ?
4) misc notes

1) platform specific notes

    - Linux (tested on redhat 5.0 hurricane kernel 2.0.32)

    the Xwindows code is just plain silly (I'm a bit rusty in
    coding X apps) still, it should work without any problems, if you
    do have problems *please* let me know so I can try to fix them.
    (Question - does X align 24 bpp modes on 32bpp by default ?
    anybody know ?)

    Anyway, as you might have guessed, the X version needs
    a 24 or 32-bpp display (and MIT's shm extensions)
    
    Also note that I'm polling keys from the startup window
    (the terminal window) - so if you wanna press a key move
    your mouse over this window (and not the actual image window)
    
    - DOS32 bit extended

    Not much to note on DOS, the only thing ; you're gonna need
    a VESA 2.0 video card wich is able to set up a linear pointer
    to video mem. The Watcom version uses the (excellent) pmode/w
    extender and the djgpp uses the default dpmi server (or cwsdmpi
    if it can't find one). Both run fine on the windows dos prompt
    (dos 7.0) and Caldera's DOS.

    - OS/2 

    The OS/2 version has not been tested, please report any problems.
        
    - Windows NT/Windows95 

    The windows versions work differently from the other versions in that
    they will use the desktop as the target surface, e.g. they will change
    your background. This is quite neat, you can run RayChase in the background
    and it will change your background once in a while. If you want to have
    a fast tiling background do something like 'RayChase -x32 -y32', if you
    want a full screen desktop background do 'RayChase -x640 -y480' (or
    whatever your resolution is) The lcc version is compiled with lcc-win32,
    The metrowerks version is optimized for the pentium-II and uses MMX 
    (if available). They both work fine on both win95 and NT (tested on 
    Win95 4.00.95.B and NT 4.0 service pack 3)

    - PowerPC

    The PowerPC version is not tested, but should work fine. If not
    please report any problems.


2) introduction

Here's the 2nd version of RayChase, RayChase still isn't a
'real-program' ; it's more of a test case for my various routines.
The thing is I'm writing a realtime render engine (HyperRender, check
it out on my web page) and I want to be able to create random textures
for it. RayChase started out as a simple raytracer wich could create
fiarly nice looking pictures. It was also pretty darn fast (about
1 second per frame - wich is pretty decent for a raytracer). Now
however it is a lot slower because it has tons of additional stuff,
here's a quick list of features ;

	- Creates random scene's all by itself in any resolution 
	- Ambient, diffuse, reflection (including glossy and full mirror) properties
	- Refraction (including translucency) and specular properties 
	- True (correct) shadow casting 
	- Supports multiple (colored) lights, 
	- Output in true color (24 or 32 bpp) 
	- Supports triangles, quads and spheres 
	- fast recursive algorithm 
	- lots of effects including

		- camera (sun) flares
		- nova bursts
		- plasma's
		- procedural textures (wood, zebra, fbm, granite, marble, etc)
		- water waves 
		- whirling
		- embossing
		- sky/cloud/snow rendering
		- motion blurring
		- lots of filters (100+)
		- etc, etc. (to get a full list use -list_bitmapfx_drivers)

	- very portable source, ported to *nix, dos, winNT/95, etc in a jiffy.
	- lots of output gfx file formats (-list_bitmapio_drivers)
	- portable stream drivers (-list_streamio_drivers)
	- lots & lots more.

4) How the heck do I use it ?

Well, the simplest way is just to run it without any parameters,
this will open up a screen (or window) of 320x200 24bpp and will
start rendering pretty pictures. You can change the resolution by
using the -x and -y options on the command line, for example ;

RayChase -x 640 -y 480

or 

RayChase -xres 512 -yres 384

If you want to open a screen (or window) in 32bpp add the -alpha
command line option. If you want to save the produced pictures
to disk add the -save option, for example ;

RayChase -xres64 -yres64 -save foo%04d.tga

or 

RayChase -s/tmp/pretty-pictures-%4d.ppm

The %...d is the standard ANSI-C format for specifeing an integer,
RayChase will try to find a output format for the specified extension
(e.g. .tga for target, .ppm for portable pixmap) if it can't find
a output format for the specifeid extension it will use the first
available format wich supports 24 or 32bpp saving.

If you want to change some of RayChases variables you need to write
its 'preset' file first, do this by typing

RayChase -W* -exit

Now goto the directory ./data/etc/bitmapfx/presets and change the
RayChase.preset file to your needs (or any other preset file if
you like) make sure that you re-read the changed preset whenever
running RayChase again, for example ;

RayChase -Rmy_preset.preset

or 

RayChase -R*

(wich will read all presets)

There are tons more things to fiddle with but it's too much
to write them all down. Fiddle for example with the config.ini
file (the $default.pigment$ variable for example is pointing
to a (optional) pigment file for the procedural textures)

And finally, here are the command line options for RayChase

(use 'RayChase -h' to re-produce)

 -h                  -help                   display simple help
 -H                  -more_help              display advanced help
 -S <driver>         -streamio_driver        use driver as default streamio
 -x <nnn>            -xres                   set video's x-resolution
 -y <nnn>            -yres                   set video's y-resolution
 -A                  -alpha                  render alpha channel
 -a <nn>             -alloc_alignment        set allocation alignment
 -s <template>       -save                   save pictures to disk
 -M <string>         -meta                   run bitmapfx meta command
 -W <filename|*>     -write_presets          save bitmapfx driver preset(s)
 -R <filename|*>     -read_presets           load bitmapfx driver preset(s)
 -X                  -exit                   exit application
 -d                  -no_display             don't display images
 -p                  -no_progress            don't display progress bar
 -0                  -list_streamio_drivers  list streamio drivers
 -1                  -list_bitmapio_drivers  list bitmap io drivers
 -2                  -list_bitmapfx_drivers  list bitmapfx drivers
 -3                  -show_bitmapfx_drivers  list bitmapfx drivers (long)
 -8                  -list_particle_drivers  list 3d particle drivers
 -9                  -list_video_modes       list all available video modes

4) misc notes ;

I've included 2 versions of RayChase a debug and a standard version,
If you run into trouble try to reproduce the problem with the debug
version. If you have any questions or remarks feel free to drop me
a line !

Cheers, flux.

flux@iea.nl
http://www.geocities.com/SiliconValley/7845/
