--- ray/doc/ray.1	2010/03/12 19:57:58	1.17
+++ ray/doc/ray.1	2011/02/18 00:40:25	1.18
@@ -1,8 +1,8 @@
 .\" RCSid "$Id"
 .\" Print using the -ms macro package
-.DA 3/12/2010
+.DA 2/17/2011
 .LP
-.tl """Copyright \(co 2010 Regents, University of California
+.tl """Copyright \(co 2011 Regents, University of California
 .sp 2
 .TL
 The
@@ -864,6 +864,74 @@ mod transdata id
 0
 6+ red green blue rspec trans tspec A7 ..
 .DE
+.LP
+.UL BSDF
+.PP
+The BSDF material type loads an XML (eXtensible Markup Language)
+file describing a bidirectional scattering distribution function.
+
+Real arguments to this material may define additional
+diffuse components that augment the BSDF data.
+String arguments are used to define thickness for hidden
+objects and the "up" orientation for the material.
+.DS
+mod BSDF id
+6+ thick BSDFfile ux uy uz funcfile transform
+0
+0|3|6|9
+     rfdif gfdif bfdif
+     rbdif gbdif bbdif
+     rtdif gtdif btdif
+.DE
+The first string argument is a "thickness" parameter that is useful
+for hiding detail geometry for transmitting systems, e.g.,
+complex fenestration.
+If a view or shadow ray hits a BSDF surface with non-zero specular transmission
+and positive thickness, the ray will pass directly through with no
+reflection or transmission due to the BSDF.
+Similar to the illum type, this permits direct viewing and
+shadow testing of complex geometry.
+In contrast, a scattered ray will use the BSDF transmission,
+offsetting transmitted sample rays by the thickness amount
+to avoid any intervening geometry.
+In this manner, BSDF surfaces may act as simplified stand-ins for detailed
+system geometry, which may still be present and visible in the simulation.
+If the BSDF has back-side reflection data, a parallel surface should be
+specified slightly less than the given thickness away from the front surface
+to enclose the system geometry on both sides.
+A zero thickness implies that the BSDF geomtery is all there is, and
+thickness is ignored if there is no transmitted component, or transmission is
+purely diffuse.
+.LP
+The second string argument is the name of the BSDF file, which is
+found in the usual auxiliary locations.
+The following three string parameters name variables for an "up" vector,
+which together with the surface normal, define the
+local coordinate system that orients the BSDF.
+These variables, along with the thickness, are defined in a function
+file given as the next string argument.
+An optional transform is used to scale the thickness and reorient the up vector.
+.LP
+If no real arguments are given, the BSDF is used by itself to determine
+reflection and transmission.
+If there are at least 3 real arguments, the first triplet is an
+additional diffuse reflectance for the front side.
+At least 6 real arguments adds diffuse reflectance to the rear side of the surface.
+If there are 9 real arguments, the final triplet will be taken as an additional
+diffuse transmittance.
+All diffuse components as well as the non-diffuse transmission are
+modified by patterns applied to this material.
+The non-diffuse reflection from either side are unaffected.
+Textures perturb the effective surface normal in the usual way.
+.LP
+The surface normal of this type is not altered to face the incoming ray,
+so the front and back BSDF reflections may differ.
+(Transmission is identical front-to-back by physical law.)\0
+If back visibility is turned off during rendering and there is no
+transmission or back-side reflection, only then the surface will be
+invisible from behind.
+Unlike other data-driven material types, the BSDF type is fully
+supported and all parts of the distribution are properly sampled.
 .LP
 .UL Antimatter
 .PP