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 in both
PDF form and in HTML.

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

Enjoy,

	-- Larry Gritz
	   lg@bmrt.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-1999 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 and scripts:

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

	slc - a compiler for the RenderMan Shading Language.

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

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

        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 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 6.2 or later (mips2, mips3, and
	  mips4 compilations are available)
	* Intel 386/486/Pentium running the Linux or FreeBSD operating
	  systems.
	* Sun SPARC machines running SunOS or Solaris
	* Intel 386/486/Pentium running MS Windows 95, 98, or Windows NT.
	* DEC Alpha machines running either OSF1 or Alpha Linux.

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 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.  Not
even under nondisclosure agreements.  So please don't even ask.



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


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
	bmrtdoc.pdf	  User manual for BMRT (PDF)
        html/*            HTML version of the BMRT user manual

bin/			The various executable files:
	rendrib		  high-quality renderer of RIB (radiosity/ray tracing)
	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.
	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 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.
	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:
	  * Shaders required by the RenderMan standard:
		constant.sl, matte.sl, metal.sl,
		plastic.sl, paintedplastic.sl, shinymetal.sl,
		ambientlight.sl, distantlight.sl, pointlight.sl, spotlight.sl
		depthcue.sl, fog.sl
	  * Header files with useful SL functions and macros:
		displace.h, filterwidth.h, locillum.h, material.h,
		noises.h, oak.h, patterns.h, project.h, pshad.h,
		rayserver.h, raysphere.h, reflections.h
	  * More nonstandard shaders:
		arealight.sl, background.sl, brick.sl, brickbump.sl,
		castucco.sl, ceramic.sl, ceramictiles.sl, 
		clamptoalpha.sl, clay.sl, defaultsurface.sl, 
		dented.sl, funkyglass.sl, glass.sl, 
		gmarbtile_polish.sl, lensflare.sl, 
		oak.sl, oakplank.sl, parquet_plank.sl, 
		screen.sl, screen_aa.sl, shiny.sl,
		shinyplastic.sl, smoke.sl, superplank.sl, supertexmap.sl,
		uberlight.sl, wallpaper_2stripe.sl, windowlight.sl, wood2.sl
	  * Compiled (with slc) versions of the various .sl files.
		*.slc


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.so (or 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!

