simplify surface models

remove the ``SURFACE_SPECULAR`` and ``SURFACE_DIFFUSE`` models, since their functionality is available using the more-general ``SURFACE_DEFAULT``. also allow the user to specify the reflection type (specular/diffuse) for the complex and wls models. change wls so the normalization of properties is more consistent with the default.

1 files changed, 7 insertions, 16 deletions

diff --git a/doc/source/surface.rst b/doc/source/surface.rst
index a9b61d1..0ed142b 100644
--- a/doc/source/surface.rst
+++ b/doc/source/surface.rst
@@ -3,7 +3,7 @@ Surface Models
 
 Chroma includes a variety of surface models, which control the interaction of photons with objects. The ``Surface`` class contains many (typically wavelength-dependent) surface parameters, some of which apply to each surface model.
 
-To select a particular model for a surface, set ``surface.model = MODEL`` where ``MODEL`` is one of ``{ SURFACE_DEFAULT, SURFACE_SPECULAR, SURFACE_DIFFUSE, SURFACE_COMPLEX, SURFACE_WLS }``.
+To select a particular model for a surface, set ``surface.model = MODEL`` where ``MODEL`` is one of ``{ SURFACE_DEFAULT, SURFACE_COMPLEX, SURFACE_WLS }``.
 
 ``SURFACE_DEFAULT``
 -------------------
@@ -19,27 +19,17 @@ Parameters::
     unsigned int n
     float step
     float wavelength0
-    
-``SURFACE_SPECULAR``
---------------------
-
-A perfect specular reflector. Behavior is identical to ``SURFACE_DEFAULT`` with 100% specular reflection at all wavelengths, but is marginally faster. This model has no parameters.
-
-``SURFACE_DIFFUSE``
--------------------
-
-A perfect diffuse reflector. Behavior is identical to ``SURFACE_DEFAULT`` with 100% diffuse reflection at all wavelengths, but is marginally faster. This model has no parameters.
 
 ``SURFACE_COMPLEX``
 -------------------
 
-This surface model uses a complex index of refraction (``eta``, ``k``) to compute transmission, (specular) reflection, and absorption probabilities. Surfaces may also be photon detectors, but the detection probability is conditional on detection (``detect`` should be normalized to 1). If a surface is not transmissive (``bool transmissive``), transmitted photons are absorbed.
-
-This model accounts for incoming photon polarization in its calculations.
+This surface model uses a complex index of refraction (``eta``, ``k``) to compute transmission, (specular) reflection, and absorption probabilities, taking into account the incoming photon polarization and surface thickness (``thickness``). Surfaces may also be photon detectors, but detection is conditional on absorption so ``detect`` should be normalized independently. Reflection may be either specular or diffuse, with probabilities given in ``reflect_specular`` and ``reflect_diffuse``; these should sum to 1 at each wavelength. By default surfaces are not transmissive (use ``bool transmissive`` to set), and transmitted photons are absorbed.
 
 Parameters::
 
     float *detect
+    float *reflect_specular
+    float *reflect_diffuse
     float *eta
     float *k
     unsigned int n
@@ -51,12 +41,13 @@ Parameters::
 ``SURFACE_WLS``
 ---------------
 
-A model of wavelength-shifting surfaces. Surfaces may absorb and reflect (these probabilities should sum to 1). Reflection is diffuse. If a photon is absorbed, it may be reemitted with a probability given in ``float *reemit`` (normalized to 1). The reemission spectrum CDF is defined in ``float* reemission_cdf``. The CDF must start at 0 and end at 1. This model does not enforce conservation of energy, and cannot reemit multiple photons!
+This surface model is used for wavelength-shifting surfaces. Surfaces may absorb, specularly reflect, diffusely reflect, or transmit photons; ``1 - absorb - reflect_diffuse - reflect_specular`` gives the transmission probability. If a photon is absorbed, it may be reemitted with a probability given in ``float *reemit``. The reemission spectrum CDF is defined in ``float* reemission_cdf``. The CDF must start at 0 and end at 1. This model does not enforce conservation of energy, and cannot reemit multiple photons!
 
 Parameters::
 
     float *absorb
-    float *reflect
+    float *reflect_specular
+    float *reflect_diffuse
     float *reemit
     float *reemission_cdf
     unsigned int n