Lightning correction

Author: eehakkin

index.html

@@ -418,5 +418,116 @@ <h2>Transferable MediaStreamTrack</h2>
       In a sense, between these steps, the data holder is attached to the underlying source as if it was a track.</p>
     </div>
   </section>
+  <section>
+    <h2>Lightning correction</h2>
+    <section>
+      <h3>{{MediaTrackSupportedConstraints}}</h3>
+      <pre class="idl"
+>partial dictionary MediaTrackSupportedConstraints {
+  boolean lightningCorrection = true;
+};</pre>
+      <section class="notoc">
+        <h4>Dictionary {{MediaTrackSupportedConstraints}} Members</h4>
+        <dl class="dictionary-members" data-dfn-for="MediaTrackSupportedConstraints" data-link-for="MediaTrackSupportedConstraints">
+          <dt><dfn><code>lightningCorrection</code></dfn> of type <span class="idlMemberType">{{boolean}}</span>, defaulting to <code>true</code></dt>
+          <dd>
+            <p>Whether <a>Lightning correction</a> constraining is
+            recognized.</p>
+          </dd>
+        </dl>
+      </section>
+    </section>
+    <section>
+      <h3>{{MediaTrackCapabilities}}</h3>
+      <pre class="idl"
+>partial dictionary MediaTrackCapabilities {
+  sequence&lt;boolean&gt; lightningCorrection;
+};</pre>
+      <section class="notoc">
+        <h4>Dictionary {{MediaTrackCapabilities}} Members</h4>
+        <dl class="dictionary-members" data-dfn-for="MediaTrackCapabilities" data-link-for="MediaTrackCapabilities">
+          <dt><dfn><code>lightningCorrection</code></dfn> of type <span class="idlMemberType">sequence&lt;{{boolean}}&gt;</span></dt>
+          <dd>
+            <p>A sequence of supported <a>lightning correction</a> modes.
+            If the source cannot do lightning correction,
+            a single <code>false</code> is reported.
+            If the lightning correction cannot be turned off,
+            a single <code>true</code> is reported.
+            If the script can control the lightning correction,
+            both <code>false</code> and <code>true</code> are reported as
+            possible values.</p>
+          </dd>
+        </dl>
+      </section>
+    </section>
+    <section>
+      <h3>{{MediaTrackConstraintSet}}</h3>
+      <pre class="idl"
+>partial dictionary MediaTrackConstraintSet {
+  ConstrainBoolean lightningCorrection;
+};</pre>
+      <section class="notoc">
+        <h4>Dictionary {{MediaTrackConstraintSet}} Members</h4>
+        <dl class="dictionary-members" data-dfn-for="MediaTrackConstraintSet" data-link-for="MediaTrackConstraintSet">
+          <dt><dfn><code>lightningCorrection</code></dfn> of type <span class="idlMemberType">{{ConstrainBoolean}}</span></dt>
+          <dd>
+            <p>See <a>lightning correction</a> constrainable property.</p>
+          </dd>
+        </dl>
+      </section>
+    </section>
+    <section>
+      <h3>{{MediaTrackSettings}}</h3>
+      <pre class="idl"
+>partial dictionary MediaTrackSettings {
+  boolean lightningCorrection;
+};</pre>
+      <section class="notoc">
+        <h4>Dictionary {{MediaTrackSettings}} Members</h4>
+        <dl class="dictionary-members" data-dfn-for="MediaTrackSettings" data-link-for="MediaTrackSettings">
+          <dt><dfn><code>lightningCorrection</code></dfn> of type <span class="idlMemberType">{{boolean}}</span></dt>
+          <dd>
+            <p>Current <a>lightning correction</a> setting.</p>
+          </dd>
+        </dl>
+      </section>
+    </section>
+    <section>
+      <h3>Constrainable Properties</h3>
+      <ol>
+        <li>
+          <p><dfn>Lightning correction</dfn> is a boolean setting
+          controlling whether face and background lightning balance is
+          to be corrected.</p>
+        </li>
+      </ol>
+    </section>
+    <section>
+      <h3>Examples</h3>
+      <pre class="example">
+&lt;video&gt;&lt;/video&gt;
+&lt;script&gt;
+// Open camera.
+const stream = await navigator.mediaDevices.getUserMedia({video: true});
+const [videoTrack] = stream.getVideoTracks();
+
+// Try to correct lightning.
+const videoCapabilities = videoTrack.getCapabilities();
+if ((videoCapabilities.lightningCorrection || []).includes(true)) {
+  await videoTrack.applyConstraints({
+    advanced: [{lightningCorrection: true}]
+  });
+} else {
+  // Lightning correction is not supported by the platform or by the camera.
+  // Consider falling back to some other method.
+}
+
+// Show to user.
+const videoElement = document.querySelector("video");
+videoElement.srcObject = stream;
+&lt;/script&gt;
+      </pre>
+    </section>
+  </section>
 </body>
 </html>