--- ray/doc/man/man1/rtcontrib.1	2005/10/06 16:28:59	1.13
+++ ray/doc/man/man1/rtcontrib.1	2007/09/04 17:36:41	1.16
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rtcontrib.1,v 1.13 2005/10/06 16:28:59 greg Exp $"
+.\" RCSid "$Id: rtcontrib.1,v 1.16 2007/09/04 17:36:41 greg Exp $"
 .TH RTCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
 rtcontrib - compute contribution coefficients in a RADIANCE scene
@@ -7,6 +7,10 @@ rtcontrib - compute contribution coefficients in a RAD
 [
 .B "\-n nprocs"
 ][
+.B \-V
+][
+.B \-fo
+|
 .B \-r
 ][
 .B "\-e expr"
@@ -37,7 +41,7 @@ rtrace options
 .B "rtcontrib [ options ] \-defaults"
 .SH DESCRIPTION
 .I Rtcontrib
-computes ray contributions (i.e., color coefficients)
+computes ray coefficients
 for objects whose modifiers are named in one or more
 .I \-m
 settings.
@@ -52,6 +56,34 @@ this file.
 (No search takes place if a file name begins with a '.', '/' or '~'
 character.)\0
 .PP
+By setting the boolean
+.I \-V
+option, you may instruct
+.I rtcontrib
+to report the contribution from each material rather than the ray
+coefficient.
+This is particularly useful for light sources with directional output
+distributions, whose value would otherwise be lost in the shuffle.
+With the default
+.I -V-
+setting, the output of rtcontrib is a coefficient that must be multiplied
+by the radiance of each material to arrive at a final contribution.
+This is more convenient for computing daylight coefficeints, or cases
+where the actual radiance is not desired.
+Use the
+.I -V+
+setting when you wish to simply sum together contributions
+(with possible adjustment factors) to obtain a final radiance value.
+Combined with the
+.I \-i
+or
+.I \-I
+option, irradiance contributions are reported by
+.I \-V+
+rather than radiance, and 
+.I \-V-
+coefficients contain an additonal factor of PI.
+.PP
 The output of
 .I rtcontrib
 has many potential uses.
@@ -66,7 +98,7 @@ systems, such as luminaires, light pipes, and shading 
 .I Rtcontrib
 calls
 .I rtrace(1)
-with the -oTW option to calculate the daughter ray
+with the \-oTW (or \-oTV) option to calculate the daughter ray
 contributions for each input ray, and the output tallies
 are sent to one or more destinations according to the given
 .I \-o
@@ -74,9 +106,12 @@ specification.
 If a destination begins with an exclamation mark ('!'), then
 a pipe is opened to a command and data is sent to its standard input.
 Otherwise, the destination is treated as a file.
-An existing file of the same name is clobbered, unless the
+An existing file of the same name will not be clobbered, unless the
+.I \-fo
+option is given.
+If instead the
 .I \-r
-option is specified, in which case data recovery is attempted.
+option is specified, data recovery is attempted on existing files.
 If an output specification contains a "%s" format, this will be
 replaced by the modifier name.
 The
@@ -198,26 +233,26 @@ replaced by the contents of the given file.
 To compute the proportional contributions from sources modified
 by "light1" vs. "light2" on a set of illuminance values:
 .IP "" .2i
-rtcontrib -I+ @render.opt -o c_%s.dat -m light1 -m light2 scene.oct < test.dat
+rtcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
 .PP
 To generate a pair of images corresponding to these two lights'
 contributions:
 .IP "" .2i
-vwrays -ff -x 1024 -y 1024 -vf best.vf |
-rtcontrib -ffc `vwrays -d -x 1024 -y 1024 -vf best.vf`
-@render.opt -o c_%s.pic -m light1 -m light2 scene.oct
+vwrays \-ff \-x 1024 \-y 1024 \-vf best.vf |
+rtcontrib \-ffc `vwrays \-d \-x 1024 \-y 1024 \-vf best.vf`
+@render.opt \-o c_%s.pic \-m light1 \-m light2 scene.oct
 .PP
 These images may then be recombined using the desired outputs
 of light1 and light2:
 .IP "" .2i
-pcomb -c 100 90 75 c_light1.pic -c 50 55 57 c_light2.pic > combined.pic
+pcomb \-c 100 90 75 c_light1.pic \-c 50 55 57 c_light2.pic > combined.pic
 .PP
 To compute an array of illuminance contributions according to a Tregenza sky:
 .IP "" .2i
-rtcontrib -I+ -b tbin -o sky.dat -m skyglow -b 0 -o ground.dat -m groundglow
-@render.opt -f tregenza.cal scene.oct < test.dat
+rtcontrib \-I+ \-b tbin \-o sky.dat \-m skyglow \-b 0 \-o ground.dat \-m groundglow
+@render.opt \-f tregenza.cal scene.oct < test.dat
 .SH ENVIRONMENT
-RAYPATH		path to search for -f and -M files
+RAYPATH		path to search for \-f and \-M files
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"