address Tab's editorial comments re intros, notes <http://lists.w3.org/Archives/Public/public-device-apis/2012Dec/0050.html>
authorAnssi Kostiainen <anssi.kostiainen@nokia.com>
Thu, 10 Jan 2013 14:41:23 +0200
changeset 3291c5fc74bd529
parent 328 51296676e203
child 330 78129450e57a
address Tab's editorial comments re intros, notes <http://lists.w3.org/Archives/Public/public-device-apis/2012Dec/0050.html>
light/Overview.html
     1.1 --- a/light/Overview.html	Thu Jan 10 13:29:01 2013 +0200
     1.2 +++ b/light/Overview.html	Thu Jan 10 14:41:23 2013 +0200
     1.3 @@ -52,31 +52,12 @@
     1.4      <section class="informative">
     1.5        <h2>Introduction</h2>
     1.6        <p>
     1.7 -        The <a>DeviceLightEvent</a> interface provides web developers
     1.8 -        information about the ambient light levels near the
     1.9 -        hosting in terms of lux units.
    1.10 -      </p>
    1.11 -      <p>
    1.12 -        The <a>LightLevelEvent</a> interface provides web
    1.13 -        developers information about the ambient light
    1.14 -        levels near the hosting in terms of general ranges.
    1.15 -      </p>
    1.16 -      <p>
    1.17 -        The values of the <a>LightLevelEvent</a> event may
    1.18 -        be "normal", "dim", or "bright".  "bright" is
    1.19 -        supposed to mean "direct sunlight, or similarly
    1.20 -        bright conditions that make it hard to see things
    1.21 -        that aren't high-contrast".  "dim" is supposed to
    1.22 -        mean "dark enough that the light produced by a white
    1.23 -        background is eye-straining or distracting".  The
    1.24 -        lux values for "dim" typical begin below 50, and the
    1.25 -        values for "bright" begin above 10000.
    1.26 -      </p>
    1.27 -        
    1.28 -
    1.29 -      <p>
    1.30 -        This is achieved by interrogating a photosensors or similar detectors
    1.31 -        of a device.
    1.32 +        This specification defines events that provide information about the
    1.33 +        ambient light level, as measured by a device's light sensor.  A
    1.34 +        <a>LightLevelEvent</a> describes the light level as one of three simple
    1.35 +        categories - "dim", "normal", and "bright" - while a
    1.36 +        <a>DeviceLightEvent</a> provides a more granular answer by describing
    1.37 +        the light level in terms of lux units.
    1.38        </p>
    1.39      </section>
    1.40      
    1.41 @@ -130,6 +111,11 @@
    1.42      <section>
    1.43        <h2>Device Light</h2>
    1.44        <p>
    1.45 +        The <a>DeviceLightEvent</a> interface provides information about the
    1.46 +        ambient light levels, as detected by the device's light detector, in
    1.47 +        terms of lux units.
    1.48 +      </p>
    1.49 +      <p>
    1.50          The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
    1.51          which this specification extends:
    1.52        </p>
    1.53 @@ -166,6 +152,11 @@
    1.54            object is created, this attribute MUST be initialized to positive
    1.55            Infinity. It represents the <a>current light level</a>.
    1.56          </p>
    1.57 +        <div class="note">
    1.58 +          The precise lux value reported by different devices in the same light
    1.59 +          can be different, due to differences in detection method, sensor
    1.60 +          construction etc.
    1.61 +        </div>
    1.62          <p>
    1.63            When a <dfn>user agent</dfn> is required to <dfn>fire a device
    1.64            light event</dfn>, the <dfn>user agent</dfn> MUST run the
    1.65 @@ -226,6 +217,11 @@
    1.66      <section>
    1.67        <h2>Light Level</h2>
    1.68        <p>
    1.69 +        The <a>LightLevelEvent</a> interface provides information about the
    1.70 +        ambient light levels, as detected by the device's light detector, in
    1.71 +        terms of three general range: "dim", "normal", or "bright".
    1.72 +      </p>
    1.73 +      <p>
    1.74          The HTML5 specification [[!HTML5]] defines a <a>Window</a> interface,
    1.75          which this specification extends:
    1.76        </p>
    1.77 @@ -301,8 +297,13 @@
    1.78                    <li><code>bright</code></li>
    1.79                  </ul>
    1.80                  <div class="note">
    1.81 -                  The lux ranges that map to the <a>current light level state</a>s
    1.82 -                  are left to the implementation.
    1.83 +                  The lux ranges that map to the <a>current light level
    1.84 +                  state</a>s are left to the implementation, as devices with
    1.85 +                  different sensitivities could map them slightly differently.
    1.86 +                  However, it is recommended that "dim" correspond to ambient
    1.87 +                  light below 50 lux, "normal" correspond to light between
    1.88 +                  50 lux and 10000 lux, and "bright" correspond to light
    1.89 +                  above 10000 lux.
    1.90                  </div>
    1.91                </li>
    1.92              </ol>