Add emission_weight (#231)

Implements the change described in #229.

Author: portsmouth

examples/open_pbr_lightbulb.mtlx

@@ -4,6 +4,7 @@
     <input name="surfaceshader" type="surfaceshader" nodename="open_pbr_surface_surfaceshader" />
   </surfacematerial>
   <open_pbr_surface name="open_pbr_surface_surfaceshader" type="surfaceshader">
+    <input name="emission_weight" type="float" value="1.0" />
     <input name="emission_color" type="color3" value="1.000, 0.415, 0.099" />
     <input name="emission_luminance" type="float" value="10000" />
   </open_pbr_surface>

index.html

@@ -1133,17 +1133,18 @@
 * +-------------------------------------------------+ *
 *******************************************************
 
-The intensity of the EDF is controlled by a luminance and a color multiplier. The **`emission_luminance`** parameter controls the luminance the emissive layer would have when **`emission_color`** is set to (1, 1, 1) and in the absence of coat and fuzz. The **`emission_color`** acts as a multiplier, i.e. the HDR emission in the model color space is defined to have a color given by **`emission_color`** * **`emission_luminance`**, thus the resulting luminance may be less than the input parameter, or even zero if the **`emission_color`** is set to (0, 0, 0).
+The intensity of the EDF is controlled by a luminance value with color and weight multipliers.  The color and weight act as multipliers, i.e. the HDR emission in the model color space is defined to have a color given by **`emission_weight`** * **`emission_color`** * **`emission_luminance`**. The **`emission_luminance`** parameter thus refers to the luminance the emissive layer would have when the color is white and weight is 1, and in the absence of coat and fuzz. Thus the final resulting luminance may be less than the input parameter, or even zero if the color or weight are zeroed.
 
 Moreover, the overall material luminance may be further reduced in the presence of coat or fuzz, as they can absorb light coming from the emissive layer before it exits the surface. The emission from the top surface should in principle gain a directional dependence due to the combined effects of absorption, total internal reflection (TIR) and multiple bounces in the coat layer, and absorption in the fuzz layer. The combined effect should result mostly in darkening and saturation at grazing angles.
 
-Being an intensity, **`emission_luminance`** can be any value greater than or equal to zero. For convenience, we make the soft range $[0, 1000]$, corresponding to the typical range of home appliances.
+Being an intensity, **`emission_luminance`** can be any value greater than or equal to zero. For convenience, we make the soft range $[0, 1000]$, corresponding to the typical range of home appliances. (Note that if the renderer does not deal with photometric units internally, a scale factor may need to be applied to bring the emission into a sensible range).
 
 
 Emission params          | Label     | Type     | Range           | Norm          | Default       | Description
 -------------------------|-----------|----------|:---------------:|:-------------:|:-------------:|----------------------------------------------
-**`emission_luminance`** | Luminance | `float`  | $ [0, \infty) $ | $ [0, 1000] $ | $ 0         $ | Emission luminance, in cd/m^2 (aka. nits)
-**`emission_color`**     | Color     | `color3` | $ [0, 1]^3    $ |               | $ (1, 1, 1) $ | Emission color multiplier
+**`emission_weight`**    | Weight    | `float`  | $ [0, 1]      $ |               | $ 0         $ | Emission weight luminance multiplier
+**`emission_luminance`** | Luminance | `float`  | $ [0, \infty) $ | $ [0, 1000] $ | $ 1000      $ | Emission luminance, in cd/m^2 (aka. nits)
+**`emission_color`**     | Color     | `color3` | $ [0, 1]^3    $ |               | $ (1, 1, 1) $ | Emission color luminance multiplier
 
 ![](images/emitting_lava.png width=90% align=left) ![](images/emission_under_coat.png width=90% align=right)
 <div class="shifted-caption">

parametrization.md.html

@@ -58,7 +58,8 @@
 | `fuzz_color`                          | Color               | `color3`  | $ [0, 1]^3      $ |               | $ (1, 1, 1)        $ |                  |
 | `fuzz_roughness`                      | Roughness           | `float`   | $ [0, 1]        $ |               | $ 0.5              $ |                  |
 | **Emission**                                                                                                                                          |
-| `emission_luminance`                  | Luminance           | `float`   | $ [0, \infty)   $ | $ [0, 1000] $ | $ 0                $ | nits             |
+| `emission_weight`                     | Weight              | `float`   | $ [0, 1]        $ |               | $ 0                $ |                  |
+| `emission_luminance`                  | Luminance           | `float`   | $ [0, \infty)   $ | $ [0, 1000] $ | $ 1000             $ | nits             |
 | `emission_color`                      | Color               | `color3`  | $ [0, 1]^3      $ |               | $ (1, 1, 1)        $ |                  |
 | **Thin-film**                                                                                                                                         |
 | `thin_film_weight`                    | Weight              | `float`   | $ [0, 1]        $ |               | $ 0                $ |                  |

reference/open_pbr_surface.mtlx

@@ -71,6 +71,8 @@
            doc="The thickness of the thin-film layer on the base (in micrometers)." />
     <input name="thin_film_ior" type="float" value="1.4" uimin="0.0" uisoftmin="1.0" uisoftmax="3.0" uiname="Thin Film Index of Refraction" uifolder="Thin Film" uiadvanced="true"
            doc="The index of refraction of the thin-film." />
+    <input name="emission_weight" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Emission Weight" uifolder="Emission"
+           doc="Emission weight luminance multiplier." />
     <input name="emission_luminance" type="float" value="0.0" uimin="0.0" uisoftmax="1000.0" uiname="Emission Luminance" uifolder="Emission"
            doc="The amount of emitted light, as a luminance in nits." />
     <input name="emission_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Emission Color" uifolder="Emission"
@@ -584,12 +586,16 @@
       <input name="in1" type="float" nodename="coat_ior_to_F0_sqrt" />
       <input name="in2" type="float" nodename="coat_ior_to_F0_sqrt" />
     </multiply>
-    <multiply name="emission_weight" type="color3">
-      <input name="in1" type="color3" interfacename="emission_color" />
+    <multiply name="weighted_emission_luminance" type="float">
+      <input name="in1" type="float" interfacename="emission_weight" />
       <input name="in2" type="float" interfacename="emission_luminance" />
     </multiply>
+    <multiply name="emission_color_weight" type="color3">
+      <input name="in1" type="color3" interfacename="emission_color" />
+      <input name="in2" type="float" nodename="weighted_emission_luminance" />
+    </multiply>
     <uniform_edf name="uncoated_emission_edf" type="EDF">
-      <input name="color" type="color3" nodename="emission_weight" />
+      <input name="color" type="color3" nodename="emission_color_weight" />
     </uniform_edf>
     <multiply name="coat_tinted_emission_edf" type="EDF">
       <input name="in1" type="EDF" nodename="uncoated_emission_edf" />