This is the readme file for the Blue Moon Rendering Tools (BMRT)
distribution.  This file describes the following:

	* What is the BMRT?
	* Contents of the distribution
	* How to install BMRT on your system.

Before proceeding, please read the License file.

In the doc/ subdirectory you will find the user manual in both
PDF form and in HTML.

Please read Win32README.html if you are installing on a
Windows 95/98/Me/NT/2000 machine.

After installing, the next thing to do is go to the examples/
subdirectory and check out the README file there.  This will explain
how to run through the examples, showing off some of BMRT's unique
features.

If you are upgrading from a previous version of BMRT, please check the
Changes file, which outlines functional differences from previous
versions of BMRT.  Be sure to update all your files, including
shaders.  It's also a good idea to recompile all your old shaders
using the new slc, just in case compilation bugs have been fixed or
slc has been optimized in some way to produce more efficient shader
code.

Don't forget to check the BMRT homepage periodically.  There you can
find notices about new versions, news, examples, and pointers to other
related stuff on the net.  The BMRT page is at:  http://www.bmrt.org



===========================================================================


What is the BMRT?
-----------------

The Blue Moon Rendering Tools (BMRT) are a collection of programs
that allow previewing and rendering of 3-D scene models.  BMRT is:
(c) Copyright 1990-2000 Exluna, Inc. and Larry Gritz.  All Rights Reserved.

BMRT uses some APIs that are very similar to those described in the
published RenderMan Interface Specification.  However, BMRT is not
associated with Pixar, and no claims are made that BMRT is in any way
a compatible replacement for RenderMan.  Those who want a licensed
implementaion of RenderMan should contact Pixar directly.

Despite these technical/legal terms, you may find that most
applications, scene files, and shaders written to conform to the
RenderMan Interface can also use BMRT without modification.

RenderMan (R) is a registered trademark of Pixar.



The BMRT consists of the following programs and scripts:

	rendrib - a high-quality renderer that uses ray tracing and
		  radiosity to create photorealistic images.

	slc - a compiler for shaders

	mkmip - converts regular scanline TIFF images into tiled, 
		multiresolution TIFF images, which allows optimizations
		for texture access.

	rgl - a scene previewer which rapidly displays Gouraud shaded
	      polygons or wireframes using OpenGL.

        iv - a nice image viewing program for TIFF, JPEG, zfile, texture,
		environment, and shadow map files.

        composite - a simple TIFF image compositing program.

	farm - a script that lets you divide a frame into several
		crop windows, rendering each on a separate machine and
		assembling the results into a mosaic image.

	mkmosaic - used by "farm", this utility assembles separately
		rendered crop windows into a single TIFF image.

	frankenrender - if you are a PRMan (3.8 or later) user, this
		script drives the "ray server" which allows you to
		use PRMan and BMRT together for the same image.

In addition, BMRT also supplies a client library (a binding of the
procedural interface that results in the output of a scene file that
can be rendered later), and some other utilities of interest to
developers.

Currently, the programs and libraries in the BMRT are distributed as
binaries for the following platforms:

    * Intel 386/486/Pentium running MS Windows 95, 98, or Windows NT.
    * Intel 386/486/Pentium running Linux or FreeBSD.
    * SGI machines running IRIX 6.2 or later
    * DEC Alpha machines running either OSF1 or Alpha Linux.
    * Sun SPARC machines running SunOS or Solaris

We do not currently support any other hardware or OS platforms, though
we may in the future if there is enough demand.  Please think carefully
before swamping us with mail asking "will you port to platform XXX".
We are quite aware of what platforms are out there, and make very
careful decisions to support the ones that we think will be most
widely used by BMRT power users.

We do not distribute any of the source code for the BMRT, not even
under nondisclosure agreements.  So please don't even ask.



===========================================================================


Contents of the distribution:
-----------------------------

./
	README		This file
	Win32README.html Windows-specific README
	License		The terms of use for this software.
	.rendribrc	Run control file for the tools.

doc/			Documentation directory
	bmrtdoc.pdf	  User manual for BMRT (PDF)
        html/*            HTML version of the BMRT user manual

bin/			The various executable files:
	rendrib		  high-quality renderer (radiosity/ray tracing)
	rgl		  quick scene previewer using OpenGL
	slc		  shader compiler (converts .sl to .slc)
	slctell		  lists the arguments to a compiled shader
	iv                image viewer program
	composite         simple image compositing.
	mkmip		  preprocesses textures for rendrib.
	mkmosaic	  Joins separately rendered crop windows.
	farm		  Sends different crops to different machines.
	frankenrender	  Lets you use PRMan and BMRT together.
	

lib/
	libribout.a	Linkable library of procedure calls that
			  results in output of a scene file.
	libslcargs.a	Allows a developer to parse the arguments to a
			  compiled shader.
	rayserver.so    Allows you to use PRMan and rendrib together.

include/
	ri.h		ANSI C and C++ header file for the procedural API.
	slc.h		Goes along with libslcargs.a.


shaders/
	This directory contains a variety of sample shaders (both source
	code and fully compiled) as well as header (.h) files containing
	useful functions for writing your own shaders.

examples/		Examples of how to use the rendering tools.
	README		  Explanation of the examples
	cornell.rib	  RIB for the 'Cornell Box' radiosity test scene
	disptest.rib	  Tests several cool displacement shaders
	dresser.rib       Tests radiosity and caustics
	limbo.rib         Frames from a pencil test of an animation (for
			      testing the previewers)
	shadtest.rib      Tests shaders and shadows
	smokebox.rib      Example of atmospheric effects with volume shaders.
	teapots.rib	  Example of ray traced reflection & refraction.
	texbox1.rib	  Example use of some procedural shaders.
	tpdisp.rib	  Example of limited support of true displacements.
        hybridtest1.rib   Test the use of BMRT & PRMan together



===========================================================================


How to Install the BMRT on your system
--------------------------------------

0. Please register.  See the License file for details.

1. Copy the files in the bin/ subdirectory someplace where you like your
   executables to reside, and/or be sure your execution PATH includes this
   directory.  Make sure the files have read and execute permission.

2. Copy libribout.a and libslcargs.a from the lib/ 
   subdirectory to wherever you like your library files to go (for 
   example, /usr/local/lib).  Make sure they have read permission.

3. Copy the files in the include/ subdirectory to wherever you like your
   include files (for example, /usr/local/include).  Make sure they have
   read permission.

4. Make a directory for shaders (e.g. /usr/local/shaders).  Copy the *.sl,
   *.slc, and *.h files from the shaders/ and examples/ subdirectories 
   into your shaders directory.  Make sure all these files have read 
   permission.  

   If you have PRMan 3.8 or later and wish to use the "ray server"
   (to allow use of PRMan and BMRT together), then copy 
   lib/rayserver.so to wherever you keep your PRMan shadeop
   DSO's (someplace that is in your shader search path).

5. To be sure that rendrib can find the shaders, set a shell environment
   variable SHADERS to a path which includes the shaders directory.  For
   example, if you use ksh, you can put the following line in your .profile:

	export SHADERS=.:/usr/local/shaders

   or, alternatively, put the following in your .cshrc:

	setenv SHADERS .:/usr/local/shaders

   This works much like the PATH environment variable.

6. The slc (Shading Language Compiler) needs cpp in its path.  Be sure to
   find out where cpp lives on your system and add that directory to your
   execution path.

7. Individual users can copy the file .rendribrc to their HOME area and
   alter it to customize some of the functionality of rendrib.  The
   .rendribrc file is simply RIB which will be read prior to any other
   files sent to any of the renderers.

8. You're all set.  Please register!

