physics shaders for mental ray 2.1, 3.0, and 3.1
=======================================================================

Date: Fri Mar  1 16:38:16 MET 2002


LEGAL
-----

This directory contains unsupported shader source code by mental images
GmbH & Co. KG, Berlin. You may use this shaders without restriction and
without fee, at your own risk. mental images does not assume liability
or provide support for these shaders.

You may redistribute this package only if either (1) its contents are
completely unchanged, or (2) you clearly mark your changes both in the
changed source file comment header and in this README, including author
information and the nature of the change, *and* renaming the library
DSO/DLL and the tar or zip archive. In any case, mental images' name as
the original author may not be removed from any file.

The latter restrictions ensure that mental images does not receive bug
reports for libraries that appear to be supported standard libraries
but are really modified versions. This would be a real mess for us to
sort out. But if you fix bugs, we would appreciate to hear about it.


COMPILATION
-----------

Make.V.X creates a production version of the library for mental ray
version V (21 for 2.1, 30 for 3.0, or 31 for 3.1), for host type X.
Make.X-debug creates a shader library with debugging information. This
allows most debuggers (such as SGI cvd) to debug the shaders, but at a
significant performance cost. The names for "X" agree with the names
found in mental ray all-platform distributions.

Simply unpack the archive and run the Make file that matches your
environment. Note that the Make.* files assume native compilers; if you
use, say, gcc on IRIX instead of SGI's MipsPro compilers, you may have
to adjust or merge Make files. Some systems, such as Sun, ship with a
mock compiler for kernel relinking that is too restricted for compiling
shaders; you need the vendor's compiler product.

The Make.* files in this package were derived with make -n'' to
remove all dependencies on the particular environment at mental images,
including directory structure and "make" utility variants (we use gmake
everywhere, including NT).


RESOURCES
---------

The shader mailing lists hosted at www.mentalimages.com (follow the
"mental ray" / "Forum" links) are a useful resource for shader writers.
You must subscribe to a list before posting. Shader writers should read
the book Programming mental ray'', available as a book from Springer
Verlag (see http://www.mentalimages.com/books.html) and also with most
3D applications that include mental ray.

The home location of this shader library is
ftp://ftp.mentalimages.com/pub/shaders .


EDITING
-------

If you want to change the source code (see above for conditions), you
can find the necessary information in the Programming mental ray''
book. Here are some quick reminders for portability issues:

- pointers and longs may be either 32 bits or 64 bits.
- some systems allow 64-bit types such as doubles on non-8-byte
  boundaries (at some performance penalty); others hit bus errors.
- avoid fp underflow situations, Alpha processors are very brittle.
- do not use "if (!did_init) {initialize}"; use init shaders.
- don't forget mi_eval_* to access parameters.
- never write to shader parameters; use mi_query(miQ_FUNC_USERPTR) for
  precomputed shader instance data storage.
- avoid statics; they can cause much trouble on multithreaded hosts or
  applications that allow concurrent multi-frame rendering.
- locks protect critical sections but reduce parallel efficiency.
- don't assume that your shaders will never run on multiprocessor
  machines! If you haven't tested on multi-CPU machines, add a note to
  the README to spare future users much grief.
- do not use printf, you'll confuse slave networking.
- mi_debug and mi_vdebug carry a performance penalty even if disabled.

