--- ray/doc/man/man1/rad.1	2004/01/01 19:31:45	1.4
+++ ray/doc/man/man1/rad.1	2015/05/26 10:00:46	1.11
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: rad.1,v 1.4 2004/01/01 19:31:45 greg Exp $"
+.\" RCSid "$Id: rad.1,v 1.11 2015/05/26 10:00:46 greg Exp $"
 .TH RAD 1 2/1/99 RADIANCE
 .SH NAME
 rad - render a RADIANCE scene
@@ -7,7 +7,7 @@ rad - render a RADIANCE scene
 [
 .B \-s
 ][
-.B "-n|-N npr"
+.B "-n | -N npr"
 ][
 .B \-t
 ][
@@ -207,7 +207,7 @@ As in
 and
 .I pfilt,
 the exposure setting may be given either as a multiplier or as a
-number of f-stop adjustments (eg. +2 or -1.5).
+number of f\-stop adjustments (eg. +2 or \-1.5).
 There is no default value for this variable.
 If it is not given, an average level will be computed by
 .I pfilt
@@ -295,7 +295,7 @@ command line option.
 Also, there are several standard view identifiers defined by
 .I rad.
 These standard views are specified by strings of the form
-"[Xx]?[Yy]?[Zz]?[vlcah]?".
+"[Xx]?[Yy]?[Zz]?[vlcahs]?".
 (That is, an optional upper or lower case X followed by an optional
 upper or lower case Y followed by an optional upper or lower case Z
 followed by an optional lower case V, L, C, A or H.)\0
@@ -303,7 +303,8 @@ The letters indicate the desired view position, where 
 means maximum X, lower case means minimum and so on.
 The final letter is the view type, where 'v' is perspective (the
 default), 'l' is parallel, 'c' is a cylindrical panorama,
-'a' is angular fisheye, and 'h' is hemispherical fisheye.
+'a' is angular fisheye, 'h' is hemispherical fisheye, and 's'
+is a planisphere (stereographic) fisheye.
 A perspective view from maximum X, minimum Y would be "Xy" or "Xyv".
 A parallel view from maximum Z would be "Zl".
 If "ZONE" is an interior zone, the standard views will
@@ -318,7 +319,7 @@ generated.
 .TP
 .BR UP
 The vertical axis for this scene.
-A negative axis may be specified with a minus sign (eg. "-Y").
+A negative axis may be specified with a minus sign (eg. "\-Y").
 There is no default value for this variable, although the standard
 views assume Z is up if no other axis is specified.
 .TP
@@ -370,7 +371,7 @@ The default value is 0.
 .BR PICTURE
 This is the root name of the output picture file(s).
 This name will have appended the view identifier (or a number if no
-id was used) and a ".pic" suffix.
+id was used) and a ".hdr" suffix.
 If a picture corresponding to a specific view exists and is not out
 of date with respect to the given octree, it will not be
 re-rendered.
@@ -438,6 +439,25 @@ For a space with penetrating sunlight casting bright p
 few places, it should be set to HIGH.
 The default value is "L".
 .TP
+.BR PGMAP
+This variable designates a global photon map to be generated by
+.I mkpmap(1)
+and used to accelerate rendering.
+The file name must be followed by the number of photons to be stored
+in the map, and this number may be followed by a bandwidth for rendering.
+There is no default value, meaning that a global photon map will not
+normally be created.
+.TP
+.BR PCMAP
+This variable designates a caustic photon map to be generated by
+.I mkpmap(1)
+and used during renderings to model light transmission by reflecting
+and refracting surfaces.
+The file name must be followed by the number of photons to be stored
+in the map, and this number may be followed by a bandwidth for rendering.
+There is no default value, meaning that a caustic photon map will not
+normally be created.
+.TP
 .BR OPTFILE
 This is the name of a file in which
 .I rad
@@ -471,6 +491,8 @@ There is no default value for this variable.
 .BR oconv
 This variable may be used to specify special options to
 .I oconv.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "oconv".
 See the
 .I oconv(1)
 manual page for a list of valid options.
@@ -478,10 +500,21 @@ manual page for a list of valid options.
 .BR mkillum
 This variable may be used to specify additional options to
 .I mkillum.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "mkillum".
 See the
 .I rtrace(1)
 manual page for a list of valid options.
 .TP
+.BR mkpmap
+This variable may be used to specify additional options to
+.I mkpmap.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "mkpmap".
+See the
+.I mkpmap(1)
+manual page for a list of valid options.
+.TP
 .BR render
 This variable may be used to specify additional options to
 .I rpict
@@ -491,9 +524,29 @@ These options will appear after the options set automa
 .I rad,
 and thus will override the default values.
 .TP
+.BR rpict
+This variable may be used to specify overriding options specific to
+.I rpict.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "rpict".
+See the
+.I rpict(1)
+man page for a list of valid options.
+.TP
+.BR rvu
+This variable may be used to specify overriding options specific to
+.I rvu.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "rvu".
+See the
+.I rvu(1)
+man page for a list of valid options.
+.TP
 .BR pfilt
 This variable may be used to specify additional options to
 .I pfilt.
+If the first word of the first instance of this variable is not an option,
+it will be used in place of the default command path, "pfilt".
 See the
 .I pfilt(1)
 manual page for details.
@@ -526,7 +579,7 @@ If we only want to see what default values
 .I rad
 would use without actually executing anything, we can invoke it thus:
 .IP "" .2i
-rad -n -e sample.rif
+rad \-n \-e sample.rif
 .PP
 This will print the variables we have given as well as default
 values
@@ -543,17 +596,21 @@ result as it is needed to determine some of the opiton
 Different option combinations have specific uses, ie:
 .IP "" .2i
 .br
-rad -v 0 sample.rif OPT=samp.opt	# build octree, put options in "sample.opt"
+rad \-v 0 sample.rif OPT=samp.opt	# build octree, put options in "sample.opt"
 .br
-rad -n -e -s sample.rif > full.rif	# make a complete rad file
+rad \-n \-e \-s sample.rif > full.rif	# make a complete rad file
 .br
-rad -n sample.rif > script.sh	# make a script of commands
+rad \-n sample.rif > script.sh	# make a script of commands
 .br
-rad -V -v Zl -n -s sample.rif > plan.vf	# make a plan view file
+rad \-V \-v Zl \-n \-s sample.rif > plan.vf	# make a plan view file
 .br
-rad -t sample.rif		# update files after minor change to input
+rad \-t sample.rif		# update files after minor change to input
 .br
-rad -s sample.rif &		# execute silently in the background
+rad \-s sample.rif &		# execute silently in the background
+.br
+rad \-N 2 sample.rif	# render views using two parallel rpict calls
+.br
+rad \-N 4 -v 1 sample.rif	# render first view with four rpiece calls
 .PP
 If we decide that the default values
 .I rad
@@ -565,8 +622,8 @@ QUAL= MED		# default was low
 DET= low		# default was medium - our space is almost empty
 PEN= True		# we want to see soft shadows from our window
 VAR= hi		# daylight can result in fairly harsh lighting
-view= XYa -vv 120	# let's try a fisheye view
-PICT= tutor		# our picture name will be "tutor_XYa.pic"
+view= XYa \-vv 120	# let's try a fisheye view
+PICT= tutor		# our picture name will be "tutor_XYa.hdr"
 .fi
 .PP
 Note the use of abbreviations, and the modification of a standard
@@ -576,7 +633,7 @@ Now we can invoke
 to take a look at our scene interactively with
 .I rvu:
 .IP "" .2i
-rad -o x11 sample.rif
+rad \-o x11 sample.rif
 .PP
 .I Rad
 will run
@@ -591,8 +648,8 @@ we wrote out the view files "view1.vp" and "view2.vp".
 We could add these to "sample.rif" like so:
 .IP "" .2i
 .nf
-view= vw1 -vf view1.vp		# Our first view
-view= vw2 -vf view2.vp		# Our second view
+view= vw1 \-vf view1.vp		# Our first view
+view= vw2 \-vf view2.vp		# Our second view
 RESOLUTION= 1024		# Let's go for a higher resolution result
 .fi
 .PP
@@ -600,7 +657,7 @@ To start
 .I rvu
 again using vw2 instead of the default, we use:
 .IP "" .2i
-rad -o x11 -v vw2 sample.rif
+rad \-o x11 \-v vw2 sample.rif
 .PP
 Once we are happy with the variable settings in our file, we can run
 .I rad
@@ -615,6 +672,17 @@ $(PICTURE)_$(view).unf	Unfinished output of
 .SH AUTHOR
 Greg Ward
 .SH BUGS
+You cannot run more than one
+.I rad
+process at a time on the same input file,
+as the second process will attempt to recover the output files
+of the first process, damaging the results.
+The exceptions to this are running interactively via the
+.I \-o
+option, or rendering different views using the
+.I \-v
+option.
+.PP
 Incremental building of octrees is not supported as it would add
 considerable complexity to
 .I rad.
@@ -651,6 +719,7 @@ accurately determine the ambient value for
 The use of upper and lower case naming for the standard views may be
 problematic on systems that don't distinguish case in filenames.
 .SH "SEE ALSO"
-glrad(1), make(1), mkillum(1), objview(1), oconv(1),
+glrad(1), make(1), mkillum(1), mkpmap(1), objview(1), oconv(1),
 pfilt(1), raddepend(1), ranimate(1),
-rholo(1), rpict(1), rtrace(1), rvu(1), touch(1), vgaimage(1), ximage(1)
+rholo(1), rpict(1), rpiece(1), rtrace(1), rvu(1),
+touch(1), vgaimage(1), ximage(1)