--- ray/doc/man/man1/rcontrib.1	2014/07/11 01:52:38	1.8
+++ ray/doc/man/man1/rcontrib.1	2024/10/23 23:51:20	1.24
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rcontrib.1,v 1.8 2014/07/11 01:52:38 greg Exp $"
+.\" RCSid "$Id: rcontrib.1,v 1.24 2024/10/23 23:51:20 greg Exp $"
 .TH RCONTRIB 1 5/25/05 RADIANCE
 .SH NAME
 rcontrib - compute contribution coefficients in a RADIANCE scene
@@ -9,6 +9,8 @@ rcontrib - compute contribution coefficients in a RADI
 ][
 .B \-V
 ][
+.B "\-t secs"
+][
 .B "\-c count"
 ][
 .B \-fo
@@ -21,6 +23,8 @@ rcontrib - compute contribution coefficients in a RADI
 ][
 .B "\-o ospec"
 ][
+.B "\-p p1=V1,p2=V2"
+][
 .B "\-b binv"
 ][
 .B "\-bn nbins"
@@ -41,6 +45,8 @@ rtrace options
 .B octree
 .br
 .B "rcontrib [ options ] \-defaults"
+.br
+.B "rcontrib \-features [feat1 ..]"
 .SH DESCRIPTION
 .I Rcontrib
 computes ray coefficients
@@ -117,6 +123,26 @@ Note that output flushing via zero-direction rays is d
 .I \-c
 set to zero.
 .PP
+Output flushing at fixed intervals may be enabled with the
+.I \-x
+option, which specifies the number of records
+(-c accumulations) before each flush.
+If the
+.I \-y
+option is also set, then periodic flushing is disabled and the
+output size for an RGB image is the taken from the x and y dimensions.
+In lieu of periodic flushing, a flush may be forced as mentioned above
+by sending a sample with a zero direction vector, although you
+must still send a full record of rays before output occurs.
+.PP
+If progress reports are desired, the
+.I \-t
+option specifies a time interval in seconds for reports sent to
+standard error.
+This requires that the number of input samples is known, meaning a
+.I \-y
+parameter has been specified.
+.PP
 The output of
 .I rcontrib
 has many potential uses.
@@ -156,7 +182,10 @@ The
 option may be used to further define
 a "bin number" within each object if finer resolution is needed, and
 this will be applied to a "%d" format in the output file
-specification if present.
+specification if present. 
+(The final integer will be offset incrementally
+if the output is a RADIANCE picture and more than one modifier has
+the same format specification.)\0
 The actual bin number is computed at run time based on ray direction
 and surface intersection, as described below.
 The number of bins must be specified in advance with the
@@ -172,13 +201,18 @@ option.
 Since bin numbers start from zero, the bin count is always equal to
 the last bin plus one.
 The most recent
+.I \-p,
 .I \-b,
 .I \-bn
 and
 .I \-o
 options to the left of each
 .I \-m
-setting are the ones used for that modifier.
+name are the ones used for that modifier.
+Any
+.I \-cs
+option changing the number of spectral color
+samples must appear before the first modifier.
 The ordering of other options is unimportant, except for
 .I \-x
 and
@@ -201,8 +235,14 @@ These parameters may be combined with definitions give
 arguments and files read using the
 .I \-f
 option.
+Additional parameter values that apply only to this modifier may be specified
+with a
+.I \-p
+option, which contains a list of variable names and assigned values, separated
+by commas, colons, or semicolons.
 The computed bin value will be
 rounded to the nearest whole number.
+(Negative bin values will be silently ignored.)\0
 For a single bin, you may specify
 .I "\-b 0",
 which is the default.
@@ -269,9 +309,28 @@ A command argument beginning with a dollar sign ('$') 
 replaced by the contents of the given environment variable.
 A command argument beginning with an at sign ('@') is immediately
 replaced by the contents of the given file.
+.PP
+.I Rcontrib
+supports light source contributions from photon maps generated by
+.I mkpmap(1)
+with its
+.I -apC
+option. Enabling photon mapping is described in the
+.I rtrace 
+man page along with its relevant settings. In photon mapping mode,
+.I rcontrib
+only supports contributions from light sources, not arbitrary modifiers.
+The
+.I -b
+option is supported along with its associated ray variables, as
+discussed above. Ray coefficients are also supported via the
+.I \-V-
+option. Using fewer photons than there are light sources for the photon
+density estimates results in omitted contributions, thus the bandwidth
+is clamped accordingly and a warning is issued. 
 .SH EXAMPLES
 To compute the proportional contributions from sources modified
-by "light1" vs. "light2" on a set of illuminance values:
+by "light1" vs. "light2" on a set of irradiance values:
 .IP "" .2i
 rcontrib \-I+ @render.opt \-o c_%s.dat \-m light1 \-m light2 scene.oct < test.dat
 .PP
@@ -287,14 +346,27 @@ of light1 and light2:
 .IP "" .2i
 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:
+To compute an array of irradiance contributions according to a Tregenza sky:
 .IP "" .2i
 rcontrib \-I+ \-f tregenza.cal \-b tbin \-bn Ntbins \-o sky.dat \-m skyglow
 \-b 0 \-o ground.dat \-m groundglow @render.opt scene.oct < test.dat
+.PP
+To perform an annual simulation of 365 daily sun positions in photon mapping
+mode:
+.IP "" .2i
+rcontrib \-I+ \-h \-V \-fo \-o c_%s.dat \-M lights \-ap contrib.pm 365
+scene.oct < test.dat,
 .SH ENVIRONMENT
 RAYPATH		path to search for \-f and \-M files
+.SH BUGS
+We do not currently compute contributions or coefficients properly
+in scenes with participating media.
+A single warning will be issued if a scattering or absorbing medium
+is detected.
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-cnt(1), genklemsamp(1), getinfo(1), pcomb(1), pfilt(1), ra_rgbe(1),
-rcalc(1), rpict(1), rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1)
+cnt(1), genklemsamp(1), getinfo(1), mkpmap(1), pcomb(1), pfilt(1), 
+ra_rgbe(1), rcalc(1), rcomb(1), rfluxmtx(1), rmtxop(1), rpict(1),
+rsensor(1), rtrace(1), total(1), vwrays(1), ximage(1)
+