--- ray/doc/ray.1	2018/06/25 20:49:10	1.34
+++ ray/doc/ray.1	2023/11/15 18:28:09	1.41
@@ -1,8 +1,8 @@
-.\" RCSid "$Id: ray.1,v 1.34 2018/06/25 20:49:10 greg Exp $"
+.\" RCSid "$Id: ray.1,v 1.41 2023/11/15 18:28:09 greg Exp $"
 .\" Print using the -ms macro package
-.DA 07/10/2016
+.DA 11/13/2023
 .LP
-.tl """Copyright \(co 2017 Regents, University of California
+.tl """Copyright \(co 2023 Regents, University of California
 .sp 2
 .TL
 The
@@ -630,6 +630,8 @@ arguments have additional flexibility to specify the s
 Also, rather than roughness, specular power is used, which has no
 physical meaning other than larger numbers are equivalent to a smoother
 surface.
+Unlike other material types, total reflectance is the sum of
+diffuse and specular colors, and should be adjusted accordingly.
 .DS
 mod ashik2 id
 4+ ux uy uz funcfile transform
@@ -947,18 +949,19 @@ 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 sBSDF
+.UL aBSDF
 .PP
-The sBSDF material is identical to the BSDF type with two important
+The aBSDF material is identical to the BSDF type with two important
 differences.
 First, proxy geometry is not supported, so there is no thickness parameter.
-Second, an sBSDF is assumed to have some specular through component, which
+Second, an aBSDF is assumed to have some specular through component
+(the 'a' stands for "aperture"), which
 is treated specially during the direct calculation and when viewing the
 material.
 Based on the BSDF data, the coefficient of specular transmission is
 determined and used for modifying unscattered shadow and view rays.
 .DS
-mod sBSDF id
+mod aBSDF id
 5+ BSDFfile ux uy uz funcfile transform
 0
 0|3|6|9
@@ -968,7 +971,7 @@ mod sBSDF id
 .DE
 .LP
 If a material has no specular transmitted component, it is much better
-to use the BSDF type with a zero thickness than to use sBSDF.
+to use the BSDF type with a zero thickness than to use aBSDF.
 .LP
 .UL Antimatter
 .PP
@@ -1191,6 +1194,73 @@ A section of text meant to depict a picture, perhaps u
 font such as hexbit4x1.fnt, calls for uniform spacing.
 Reasonable magnitudes for proportional spacing are
 between 0.1 (for tightly spaced characters) and 0.3 (for wide spacing).
+.LP
+.UL Spectrum
+.PP
+The spectrum primitive is the most basic type for introducing spectral
+color to a material.
+Since materials only provide RGB parameters, spectral patterns
+are the only way to superimpose wavelength-dependent behavior.
+.DS
+mod spectrum id
+0
+0
+5+ nmA nmB s1 s2 .. sN
+.DE
+The first two real arguments indicate the limits of the covered
+spectral range in nanometers.
+Subsequent real values correspond to multipliers in each wavelength band,
+where the first band goes from nmA to nmA+(nmB-nmA)/N, and N is the
+number of bands (i.e., the number of real arguments minus 2).
+The nmA wavelength may be greater or less than the nmB wavelength,
+but they may not be equal, and their ordering must correspond to
+the ordering of the spectral values.
+A minimum of 3 values must be given, which would act
+more or less the same as a constant RGB multiplier.
+As with RGB values, spectral quantities normally range between 0
+and 1 at each wavelength, or average to 1.0 against a standard
+sensitivity functions such as V(lambda).
+The best results obtain when the spectral range and number
+of samples match rendering options, though resampling will handle
+any differences, zero-filling wavelenths outside the nmA to nmB
+range.
+A warning will be issued if the given wavelength range does not
+adequately cover the visible spectrum.
+.LP
+.UL Specfile
+.PP
+The specfile primitive is equivalent to the spectrum type, but
+the wavelength range and values are contained in a 1-dimensional
+data file.
+This may be a more convenient way to specify a spectral color,
+especially one corresponding to a standard illuminant such as D65
+or a library of measured spectra.
+.DS
+mod specfile id
+1 datafile
+0
+0
+.DE
+As with the spectrum type, rendering wavelengths outside the defined
+range will be zero-filled.
+Unlike the spectrum type, the file may contain non-uniform samples.
+.LP
+.UL Specfunc
+.PP
+The specfunc primitive offers dynamic control over a spectral
+pattern, similar to the colorfunc type.
+.DS
+mod specfunc id
+2+ sval funcfile transform
+0
+2+ nmA nmB A3 ..
+.DE
+Like the spectrum primitive, the wavelength range is specified
+in the first two real arguments, and additional real values are
+accessible to the sval function.
+This function is fed a wavelenth sample
+between nmA and nmB as its only argument,
+and it returns the corresponding spectral intensity.
 .NH 3
 Mixtures
 .PP
@@ -1592,6 +1662,20 @@ the Ecole Polytechnique Federale de Lausanne (EPFL Uni
 in Lausanne, Switzerland.
 .NH 1
 References
+.LP
+Ward, Gregory J., Bruno Bueno, David Geisler-Moroder, 
+Lars O. Grobe, Jacob C. Jonsson, Eleanor
+S. Lee, Taoning Wang, Helen Rose Wilson,
+``Daylight Simulation Workflows Incorporating
+Measured Bidirectional Scattering Distribution Functions,''
+.I "Energy & Buildings",
+Vol. 259, No. 111890, 2022.
+.LP
+Wang, Taoning, Gregory Ward, Eleanor Lee,
+``Efficient modeling of optically-complex, non-coplanar
+exterior shading: Validation of matrix algebraic methods,''
+.I "Energy & Buildings",
+vol. 174, pp. 464-83, Sept. 2018.
 .LP
 Lee, Eleanor S., David Geisler-Moroder, Gregory Ward,
 ``Modeling the direct sun component in buildings using matrix