--- ray/doc/man/man1/mkillum.1	2004/09/17 21:43:49	1.4
+++ ray/doc/man/man1/mkillum.1	2010/09/03 23:53:49	1.10
@@ -1,4 +1,4 @@
-.\" RCSid "$Id: mkillum.1,v 1.4 2004/09/17 21:43:49 greg Exp $"
+.\" RCSid "$Id: mkillum.1,v 1.10 2010/09/03 23:53:49 greg Exp $"
 .TH MKILLUM 1 10/6/95 RADIANCE
 .SH NAME
 mkillum - compute illum sources for a RADIANCE scene
@@ -32,17 +32,16 @@ and the secondary source types in RADIANCE.
 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
+ray tracing 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
+are interpreted as rendering options for
 .I rtrace(1),
-which is used to compute the light distributions for the input surfaces.
+to compute the light distributions for the input surfaces.
 These surfaces can be any combination of polygons, spheres and rings.
 Other surfaces may be included, but
 .I mkillum
@@ -57,8 +56,7 @@ the file names.
 (Note that this character must be escaped from most shells.)
 This is necessary so
 .I mkillum
-can tell where the arguments to
-.I rtrace(1)
+can tell where the rendering arguments
 end and its own input files begin.
 .SH VARIABLES
 .I Mkillum
@@ -139,7 +137,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
@@ -173,6 +172,24 @@ 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, which may be produced by the Radiance
+.I genBSDF(1)
+program.
+The orientation of the BSDF may be controlled with the
+.I u
+setting, described below.
+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.
@@ -193,10 +210,44 @@ 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, corresponding to an azimuth of 90 degrees.
+The default up vector 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 a fenestration system, specifically
+to compute the incoming distribution for a BSDF computation.
+If the thickness is set to 0 and a BSDF contains detailed geometry,
+it will be translated and output as part of the new description, provided the
+.I l-
+option is also in effect.
+(This currently works only for rectangular polygons.)\0
+The default thickness 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), rvu(1)
+genBSDF(1), oconv(1), rad(1), rpict(1), rtrace(1), rvu(1)