//****************************************************************************//
//
// Softimage XSI / Mental Ray Dirtmap Shader
//
// by Daniel "thebigMuh" Rind
//
// Version 1.20, 18.10.2003
//
//****************************************************************************//

//*********//
// HISTORY //
//*********//

Version 1.20, 18.10.2003
 - Added Bent Normals output. Very simple stuff, really.
 - Removed the adaptive sampling part. The few cases where it helped improving
   performance did not outweigh the many standard cases in which it only slowed
   things down.
 - Added the mi_ray_falloff function to the shader. This has mainly two
   consequences:
   a.) Performance can increase a LOT in large scenes with lots of geometry when
       you use low falloff values.
   b.) The shader will not work with Mental Ray 3.1 and below. Only 3.2+ is
       supported now.
       
Version 1.11, 26.04.2003
 - No real changes on the software, but now there's also the necessary files
   included to make the dirtmap work with Maya! See Credits section for more
   info.
   
Version 1.10, 09.04.2003
 - Added adaptive sampling capabilities to the shader.
 - Added switch for turning off geometry probing (for simple pass-rendering
   setup).
 - Added switch to disable map for secondary illumination computations (greatly
   reducing the time needed for Final Gathering in scenes with the Dirtmap).
 - Few minor changes to the source code.
 - Linux version now available, too! See Credits section for more info.

Version 1.01, 29.03.2003
 - A few people were reporting errors when they tried rendering with the shader
   ('phen 0.2 error 051011 shader "dirtmap" not found.'). Seems like MSVC 7.0
   was the problem. I simply recompiled it with MSVC 6.0, so it should work now.

Version 1.0, 29.03.2003
 - Initial release

//**************//
// WHAT THIS IS //
//**************//

The Dirtmap is a procedurally generated occlusion map for Mental Ray 3.2+. It
was written for Softimage XSI 3.5, but should theoretically work for any Mental 
Ray implementation.

This shader uses raytracing to determine the amount of occluding geometry in the
neighborhood of a rendered point, and outputs the result as a blend of two
colors.

//**************//
// INSTALLATION //
//**************//

Note: Since version 1.1, a XSIADDON file is included. It is recommended that
you install using this file instead of directly installing the SPDL.

However, to install using the SPDL, simply start XSI. Goto 
"File"->"Add-On"->"Plugins (SPDL)...". In the dialog that opens, click the 
"Install..." button. In the "Install SPDL" dialog, choose the path to where 
you unpacked the shader, make any additional settings you want, and click the 
"Install" button. If everything went right, you now have an additional entry in 
the "Plugins (SPDL)" list.

//*******//
// USAGE //
//*******//

The Dirtmap is a texture shader for Mental Ray 3.2+ / Softimage 3.5. To use it,
simply open the render tree. Click on "Nodes"->"Texture"->"More...". In the
dialog that opens, click on the "Paths" button right of the path input field.
If you installed using the XSIADDON file, there should be an additional path in
the "Addons" part of the context menu. It _should_ put you in the correct 
directory, your Dirtmap addon directory.

A relatively detailed description of what each parameter does is enclosed in the
"doc" subdirectory.

//************//
// THE SOURCE //
//************//

The complete C source to the shader is enclosed in the "source" subdirectory,
along with a VC 6 and a VC 7 project. You are free to do with it whatever you 
want, but should you manage to produce something usefull/interesting/nice/cool 
with it, please be so kind and give me credit. Of course, if you find any 
"unintentional features", please e-mail me so I can fix it.

One of the files included (shadehlp.h) is a small .H file I started, which I am
going to fill with usefull helper functions for writing shaders. It will likely
grow over time, so you might want to put it in your %XSISDK_ROOT%\include
directory, and always replace it with the latest version.

//*********//
// CREDITS //
//*********//

Very special thanks go out to Jan Walter from TheMill (http://www.mill.co.uk)
for compiling and assembling the Linux version for me (and you!). (Also thanks
to Jordi Bares for giving him the thing in the first place :-).

An extra big "thank you" goes to Horvatth Szabolcs for continually supplying the 
necessary files for Maya!

I would also like to thank all the people that posted new ideas and critics, or
that sent me an e-mail telling me that they actually find the shader usefull.

I am a 23 year old computer science student from Vienna/Austria. I love computer
graphics (which is the field I am studying in), I love XSI, and I love Mental 
Ray, so starting to program for it was only natural ;-).

If you want to contact me, you can do so at:

thebigMuh@chello.at

or by lurking for my presence on the XSI Base (www.xsibase.com) or the
3rd-Dimension (www.3rd-d.co.uk) internet boards. 

Eventually I might even update my homepage (www.animusartis.com).
