--- ray/doc/man/man1/mkillum.1	2003/12/09 15:59:06	1.2
+++ ray/doc/man/man1/mkillum.1	2007/12/13 07:03:36	1.7
@@ -1,10 +1,12 @@
-.\" RCSid "$Id: mkillum.1,v 1.2 2003/12/09 15:59:06 greg Exp $"
+.\" RCSid "$Id: mkillum.1,v 1.7 2007/12/13 07:03:36 greg Exp $"
 .TH MKILLUM 1 10/6/95 RADIANCE
 .SH NAME
 mkillum - compute illum sources for a RADIANCE scene
 .SH SYNOPSIS
 .B mkillum
 [
+.B "\-n nprocs"
+][
 .B "rtrace options"
 ]
 .B octree
@@ -18,7 +20,7 @@ light source distributions for each surface, replacing
 secondary sources whose contributions can be computed more efficiently by
 .I rpict(1)
 and
-.I rview(1).
+.I rvu(1).
 This type of optimization is most useful for windows and skylights which
 represent concentrated sources of indirect illumination.
 .I Mkillum
@@ -27,7 +29,16 @@ directional distributions.
 These are best handled respectively by the ambient calculation
 and the secondary source types in RADIANCE.
 .PP
-The arguments to
+If the
+.I \-n
+option is specified with a value greater than 1, multiple
+.I rtrace(1)
+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.
+.PP
+Remaining arguments to
 .I mkillum
 are passed directly to
 .I rtrace(1),
@@ -128,7 +139,8 @@ Only produce secondary sources for surfaces modified b
 .TP
 .BR n
 Do not produce any secondary sources.
-All input will be passed to the output unaffected.
+All input will be passed to the output unaffected, except any
+void surfaces will be removed.
 .TP
 .BI b =real
 Do not produce a secondary source for a surface if its average
@@ -162,6 +174,25 @@ If
 is zero, then a diffuse source is assumed and no distribution is
 created.
 .TP
+.BI d =string
+Set the surface Bidirectional Scattering Distribution Function (BSDF)
+to the given file.
+The RADIANCE library path will be searched if the file does not begin
+with a '.' or '~' character.
+This file must contain an LBNL Window 6 XML specification of a valid
+BSDF for the given surface, and all rays will be interpreted through
+this function.
+The orientation of the BSDF may be controlled with the
+.I u
+setting, described below.
+The thickness of the surface may be controlled with the
+.I t
+setting.
+If this variable has no setting or an integer is specified,
+.I mkillum
+returns to the default behavior of computing the output distribution
+directly.
+.TP
 .BI s =integer
 Set the number of ray samples per direction to
 .I integer.
@@ -182,10 +213,39 @@ will use the material type "illum" with the input surf
 as its alternate material.
 The default is
 .I l-.
+.TP
+.BI u =[+|-]{X|Y|Z}
+The given axis will be considered "up" for the purposes of interpreting
+BSDF data specified with the
+.I d
+variable.
+The BSDF will be reoriented relative to the surface as necessary to keep
+the up vector in the vertical plane that contains this axis and the
+surface normal.
+The default value is +Z.
+.TP
+.BI t =real
+Set the surface thickness to
+.I real
+in world coordinates.
+This value is used for determining where to start rays that need to begin
+on the opposite side of the surface, specifically to compute the incoming
+distribution for a BSDF computation.
+The default value is 0.
+.SH EXAMPLES
+The following command generates illum's corresponding to geometry
+in the files "it1.rad" and "it2.rad":
+.IP "" .3i
+mkillum \-ab 2 \-ad 1024 \-av .1 .1 .1 basic.oct "<" it1.rad it2.rad > illums.rad
+.PP
+The output file "illums.rad" would then be combined with the original
+scene geometry to create a more easily rendered composite.
+.SH ENVIRONMENT
+RAYPATH		the directories to check for auxiliary files.
 .SH AUTHOR
 Greg Ward
 .SH ACKNOWLEDGEMENT
 Work on this program was initiated and sponsored by the LESO
 group at EPFL in Switzerland.
 .SH "SEE ALSO"
-oconv(1), rad(1), rpict(1), rtrace(1), rview(1)
+oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)