--- ray/doc/man/man1/rpict.1	2003/12/09 15:59:07	1.2
+++ ray/doc/man/man1/rpict.1	2007/09/04 17:36:41	1.11
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rpict.1,v 1.2 2003/12/09 15:59:07 greg Exp $"
+.\" RCSid "$Id: rpict.1,v 1.11 2007/09/04 17:36:41 greg Exp $"
 .TH RPICT 1 2/26/99 RADIANCE
 .SH NAME
 rpict - generate a RADIANCE picture
@@ -89,6 +89,9 @@ center of a parallel projection.
 .BI -vd " xd yd zd"
 Set the view direction vector to
 .I "xd yd zd".
+The length of this vector indicates the focal distance as needed by the
+.I \-pd
+option, described below.
 .TP
 .BI -vu " xd yd zd"
 Set the view up vector (vertical direction) to
@@ -149,7 +152,7 @@ This is option is useful for generating skewed perspec
 rendering an image a piece at a time.
 A value of 1 means that the rendered image starts just to the right of
 the normal view.
-A value of -1 would be to the left.
+A value of \-1 would be to the left.
 Larger or fractional values are permitted as well.
 .TP
 .BI -vl \ val
@@ -163,7 +166,7 @@ option.
 .BI -vf \ file
 Get view parameters from
 .I file,
-which may be a picture or a file created by rview (with the "view" command).
+which may be a picture or a file created by rvu (with the "view" command).
 .TP
 .BI -x \ res
 Set the maximum x resolution to
@@ -226,6 +229,23 @@ to use a very small fraction with the
 .I \-pm
 option, to avoid the ghosting effect of too few time samples.
 .TP
+.BI -pd \ dia
+Set the pixel depth-of-field aperture to a diameter of
+.I dia
+(in world coordinates).
+This will be used in conjunction with the view focal distance, indicated
+by the length of the view direction vector given in the
+.I \-vd
+option.
+It is not advisable to use this option in combination with the
+.I pdfblur(1)
+program, since one takes the place of the other.
+However, it may improve results with
+.I pdfblur
+to use a very small fraction with the
+.I \-pd
+option, to avoid the ghosting effect of too few samples.
+.TP
 .BI -dj \ frac
 Set the direct jittering to
 .I frac.
@@ -243,7 +263,7 @@ A warning about aiming failure will issued if
 .I frac
 is too large.
 It is usually wise to turn off image sampling when using
-direct jitter by setting -ps to 1.
+direct jitter by setting \-ps to 1.
 .TP
 .BI -ds \ frac
 Set the direct sampling ratio to
@@ -452,23 +472,23 @@ header of the ambient file.
 .I Getinfo(1)
 may be used to print out this information.
 .TP
-.BI -ae \ mat
+.BI -ae \ mod
 Append
-.I mat
+.I mod
 to the ambient exclude list,
 so that it will not be considered during the indirect calculation.
 This is a hack for speeding the indirect computation by
 ignoring certain objects.
 Any object having
-.I mat
+.I mod
 as its modifier will get the default ambient
 level rather than a calculated value.
-Any number of excluded materials may be given, but each
+Any number of excluded modifiers may be given, but each
 must appear in a separate option.
 .TP
-.BI -ai \ mat
+.BI -ai \ mod
 Add
-.I mat
+.I mod
 to the ambient include list,
 so that it will be considered during the indirect calculation.
 The program can use either an include list or an exclude
@@ -477,16 +497,16 @@ list, but not both.
 .BI -aE \ file
 Same as
 .I \-ae,
-except read materials to be excluded from
+except read modifiers to be excluded from
 .I file.
 The RAYPATH environment variable determines which directories are
 searched for this file.
-The material names are separated by white space in the file.
+The modifier names are separated by white space in the file.
 .TP
 .BI -aI \ file
 Same as
 .I \-ai,
-except read materials to be included from
+except read modifiers to be included from
 .I file.
 .TP
 .BI -me " rext gext bext"
@@ -535,16 +555,38 @@ though the
 .I \-dv
 option (above) may be used to override this.
 .TP
+.BR \-u
+Boolean switch to control uncorrelated random sampling.
+When "off", a low-discrepancy sequence is used, which reduces
+variance but can result in a brushed appearance in specular highlights.
+When "on", pure Monte Carlo sampling is used in all calculations.
+.TP
 .BI -lr \ N
 Limit reflections to a maximum of
 .I N.
+If
+.I N
+is zero, then Russian roulette is used for ray
+termination, and the
+.I -lw
+setting (below) must be positive.
+If N is a negative integer, then this sets the upper limit
+of reflections past which Russian roulette will not be used.
+In scenes with dielectrics and total internal reflection,
+a setting of 0 (no limit) may cause a stack overflow.
 .TP
 .BI -lw \ frac
 Limit the weight of each ray to a minimum of
 .I frac.
-During ray-tracing, a record is kept of the final contribution
-a ray would have to the image.
-If it is less then the specified minimum, the ray is not traced.
+During ray-tracing, a record is kept of the estimated contribution
+(weight) a ray would have in the image.
+If this weight is less than the specified minimum and the
+.I -lr
+setting (above) is positive, the ray is not traced.
+Otherwise, Russian roulette is used to
+continue rays with a probability equal to the ray weight
+divided by the given
+.I frac.
 .TP
 .BI -S \ seqstart
 Instead of generating a single picture based only on the view
@@ -732,7 +774,7 @@ Set the time between progress reports to
 A progress report writes the number of rays traced, the percentage
 completed, and the CPU usage to the standard error.
 Reports are given either automatically after the specified interval,
-or when the process receives a continue (-CONT) signal (see
+or when the process receives a continue (\-CONT) signal (see
 .I kill(1)).
 A value of zero turns automatic reporting off.
 .TP
@@ -746,13 +788,13 @@ Boolean switch for warning messages.
 The default is to print warnings, so the first appearance of
 this option turns them off.
 .SH EXAMPLE
-rpict -vp 10 5 3 -vd 1 -.5 0 scene.oct > scene.pic
+rpict \-vp 10 5 3 \-vd 1 \-.5 0 scene.oct > scene.pic
 .PP
-rpict -S 1 -o frame%02d.pic scene.oct < keyframes.vf
+rpict \-S 1 \-o frame%02d.pic scene.oct < keyframes.vf
 .SH ENVIRONMENT
 RAYPATH		the directories to check for auxiliary files.
 .SH FILES
-/usr/tmp/rtXXXXXX		common header information for picture sequence
+/tmp/rtXXXXXX		common header information for picture sequence
 .br
 rfXXXXXX		temporary name for recover file
 .SH DIAGNOSTICS
@@ -768,5 +810,5 @@ option.
 .SH AUTHOR
 Greg Ward
 .SH "SEE ALSO"
-getinfo(1), lookamb(1), oconv(1), pfilt(1), pinterp(1), pmblur(1),
-printf(3), ra_rgbe(1), rad(1), rtrace(1), rview(1)
+getinfo(1), lookamb(1), oconv(1), pdfblur(1), pfilt(1), pinterp(1), pmblur(1),
+printf(3), ra_rgbe(1), rad(1), rtrace(1), rvu(1)