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.

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.

In the doc/ subdirectory you will find the user manual, a short
introduction to RIB, and any platform-specific README files.

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
BMRT and RenderMan-related stuff on the net.  The BMRT page is at:

	http://www.seas.gwu.edu/student/gritz/bmrt.html

Enjoy,

	-- Larry Gritz
	   gritzl@acm.org


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


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

The Blue Moon Rendering Tools (BMRT) are a collection of programs
which allow previewing and rendering of 3-D scene models.  All are
compatible with the RenderMan Interface Standard, developed by Pixar.

The BMRT is:

    (c) Copyright 1990-1997 by Larry I. Gritz.  All Rights Reserved.

Please note that:

    The RenderMan (R) Interface Procedures and RIB Protocol are:
        Copyright 1988, 1989, Pixar.  All rights reserved.
    RenderMan (R) is a registered trademark of Pixar.


The BMRT consists of the following programs:

	rendrib - a high-quality renderer which uses both ray tracing and
		  radiosity to create (potentially) photorealistic images.

	slc - a compiler for the RenderMan Shading Language.

	rendribv - a RIB previewer which rapidly displays wireframe
		   images on an X11 terminal.

	rgl - a RIB previewer which rapidly displays Gouraud shaded
	      polygons using OpenGL.

        composite - a simple TIFF image compositing program.

In addition, BMRT also supplies a RIB client library (a binding of the
RenderMan procedural interface which results in the output of RIB to
stdout or to a file), and some other utilities of interest to
developers.

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

	* SGI machines running IRIX 5.2 or later (mips2, mips3, and
	  mips4 compilations are available)
	* Sun SPARC machines running SunOS or Solaris
	* Machines running NEXTSTEP (Intel 486/Pentium, HP-PA, SPARC,
	  or M68k chips).
	* Intel 386/486/Pentium running the Linux or FreeBSD operating
	  systems.
	* Intel 386/486/Pentium running MS Windows 95 or Windows NT.

I do not currently support any other hardware or OS platforms, though
I may in the future if there is enough demand (and if I can get access
to the proper development platforms).  I don't particularly intend
to port to any non-UNIX platforms, however.

I don't want to be too harsh about this, but think carefully before
swamping me with mail asking "will you port to platform XXX".  Cray
asked me to port to their supercomputers and I turned them down, so
chances are slim that you'll convince me to support the Mac.  It's not
that I have anything against the Mac, it's just an example of a
machine that would be difficult to support because it's incompatible
and I don't have easy access to it.  There are many other examples of
machines that I don't wish to support for similar reasons.

I do not distribute any of the source code for the BMRT.


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


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

./
	README		This file
	License		The terms of use for this software.
	.rendribrc	Run control file for the tools.

doc/			Documentation directory
	bmrt.html	  HTML documentation for the BMRT.
	poets.ps	  "RenderMan for Poets" - a quick intro to the API.

bin/			The various executable files:
	rendrib		  high-quality renderer of RIB (radiosity/ray tracing)
	rendribv	  quick previewer of RIB using X11 (wireframe).
	rgl		  quick previewer of RIB using OpenGL (polygons).
	slc		  Shading Language compiler (converts .sl to .so)
	slctell		  lists the arguments to a compiled shader
	composite         simple image compositing.

lib/
	libribout.a	Linkable library of RenderMan procedure calls which
			  results in RIB being output to stdout or a file.
	libslcargs.a	Allows a developer to parse the arguments to a
			  compiled shader.

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


shaders/
	constant.sl, matte.sl	       \
	metal.sl, shinymetal.sl         \
	plastic.sl, paintedplastic.sl    |   the standard shaders required
	ambientlight.sl, distantlight.sl | - by the RenderMan standard
	pointlight.sl, spotlight.sl      |
	depthcue.sl, fog.sl,		/
	bumpy.sl, null.sl	       /

	arealight.sl	light shader for area light sources

	*.slc		Compiled (with slc) versions of the various .sl files.


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
	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.

	background.sl, brick.sl, brickbump.sl,         \
	castucco.sl, clamptoalpha.sl, dented.sl,        |
	funkyglass.sl, glass.sl, gmarbltile_polish.sl,  |- some extra shaders 
	noisysmoke.sl, screen.sl, screen_aa.sl,         |  for the examples
	shiny.sl, stucco.sl, superplank.sl,             |
	wallpaper_2stripe.sl, windowlight.sl, wood2.sl /

	*.slc		  Compiled versions of the various .sl files


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


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 the files in 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
   and *.slc files from the shaders/ and examples/ subdirectories into your
   shaders directory.  Make sure all these files have read permission.

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:~/myshaders

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

	setenv SHADERS .:/usr/local/shaders:~/myshaders

   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!

