--- ray/doc/man/man1/rtcontrib.1	2007/11/17 01:13:50	1.17
+++ ray/doc/man/man1/rtcontrib.1	2009/06/14 18:21:58	1.22
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rtcontrib.1,v 1.17 2007/11/17 01:13:50 greg Exp $"
+.\" RCSid "$Id: rtcontrib.1,v 1.22 2009/06/14 18:21:58 greg Exp $"
 .TH RTCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
 rtcontrib - compute contribution coefficients in a RADIANCE scene
@@ -9,7 +9,7 @@ rtcontrib - compute contribution coefficients in a RAD
 ][
 .B \-V
 ][
-.B \-c
+.B "\-c count"
 ][
 .B \-fo
 |
@@ -58,6 +58,17 @@ this file.
 (No search takes place if a file name begins with a '.', '/' or '~'
 character.)\0
 .PP
+If the
+.I \-n
+option is specified with a value greater than 1, multiple
+.I rtrace
+processes will be used to accelerate computation on a shared
+memory machine.
+Note that there is no benefit to using more processes
+than there are local CPUs available to do the work, and the
+.I rtcontrib
+process itself may use a considerable amount of CPU time.
+.PP
 By setting the boolean
 .I \-V
 option, you may instruct
@@ -86,6 +97,26 @@ rather than radiance, and 
 .I \-V-
 coefficients contain an additonal factor of PI.
 .PP
+The
+.I \-c
+option tells
+.I rtcontrib
+how many rays to accumulate for each record.
+The default value is 1, meaning a full record will be produced for
+each input ray.
+For values greater than 1, contributions will be averaged together
+over the given number of input rays.
+If set to zero, only a single record will be produced at the very
+end, corresponding to the sum of all rays given on the input
+(rather than the average).
+This is equivalent to passing all the output records through a program like
+.I total(1)
+to sum RGB values together, but is much more efficient.
+Using this option, it is possible to reverse sampling, sending rays from
+a parallel source such as the sun to a diffuse surface, for example.
+Note that output flushing via zero-direction rays is disabled
+for accumulated evaluations.
+.PP
 The output of
 .I rtcontrib
 has many potential uses.
@@ -97,21 +128,6 @@ More generally,
 can be used to compute arbitrary input-output relationships in optical
 systems, such as luminaires, light pipes, and shading devices.
 .PP
-Setting the
-.I \-c
-option instructs
-.I rtcontrib
-to accumulate values rather than reporting one record per ray.
-With this option, only a single record will be produced at the very
-end, corresponding to the sum of all rays given on the input.
-This is equivalent to passing all the output records through a program like
-.I total(1)
-to sum RGB values together, but is much more efficient.
-Using this option, it is possible to reverse sampling, sending rays from
-a parallel source such as the sun to a diffuse surface, for example.
-Care must be taken to perform normalization based on the
-radiation density and the number of rays sampled.
-.PP
 .I Rtcontrib
 calls
 .I rtrace(1)
@@ -130,7 +146,7 @@ If instead the
 .I \-r
 option is specified, data recovery is attempted on existing files.
 (If 
-.I \-c
+.I "\-c 0"
 is used together with the
 .I \-r
 option, existing files are read in and new ray evaluations are added
@@ -150,6 +166,12 @@ If the number of bins is known in advance, it should b
 .I \-bn
 option, and this is critical for output files containing multiple values
 per record.
+A variable or constant name may be given for this parameter if
+it has been defined via a previous
+.I \-f
+or
+.I \-e
+option.
 Since bin numbers start from 0, the bin count is always equal to
 the last bin plus 1.
 Set the this value to 0 if the bin count is unknown (the default).
@@ -160,14 +182,14 @@ and
 .I \-o
 options to the left of each
 .I \-m
-setting affect only that modifier.
+setting are the ones used for that modifier.
 The ordering of other options is unimportant, except for
 .I \-x
 and
 .I \-y
 if the
 .I \-c
-is present, when they control the resolution string
+is 0, when they control the resolution string
 produced in the corresponding output.
 .PP
 If a
@@ -243,17 +265,6 @@ suitable for manipulation with
 .I pcomb(1)
 and related tools.
 .PP
-If the
-.I \-n
-option is specified with a value greater than 1, multiple
-.I rtrace
-processes will be used to accelerate computation on a shared
-memory machine.
-Note that there is no benefit to using more processes
-than there are local CPUs available to do the work, and the
-.I rtcontrib
-process itself may use a considerable amount of CPU time.
-.PP
 Options may be given on the command line and/or read from the
 environment and/or read from a file.
 A command argument beginning with a dollar sign ('$') is immediately
@@ -271,12 +282,12 @@ 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
+@render.opt \-o c_%s.hdr \-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.hdr \-c 50 55 57 c_light2.hdr > combined.hdr
 .PP
 To compute an array of illuminance contributions according to a Tregenza sky:
 .IP "" .2i
@@ -287,5 +298,5 @@ RAYPATH		path to search for \-f and \-M files
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-cnt(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
+cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
 rcalc(1), rpict(1), rtrace(1), total(1), vwrays(1), ximage(1)