Merge pull request #59 from henbos/220330_efficientPixelFormat

Add powerEfficientPixelFormat

index.html

@@ -50,8 +50,10 @@ <h2>Introduction</h2>
     <h2>Terminology</h2>
     <p>
       This document uses the definitions {{MediaDevices}}, {{MediaStreamTrack}},
-      {{MediaStreamConstraints}} and {{ConstrainablePattern}}
-      from [[!mediacapture-streams]].
+      {{MediaStreamConstraints}}, {{ConstrainablePattern}},
+      {{MediaTrackSupportedConstraints}}, {{MediaTrackCapabilities}},
+      {{MediaTrackConstraintSet}}, {{MediaTrackSettings}} and
+      {{ConstrainBoolean}} from [[!mediacapture-streams]].
       <p>The terms [=permission state=], [=request permission to use=], and
       <a data-cite="permissions">prompt the user to choose</a> are defined in
       [[!permissions]].</p>    </p>
@@ -208,6 +210,110 @@ <h3>GetUserMediaSemantics enum</h3>
         </table>
       </div>
     </section>
+  </section>
+  <section id="the powerEfficientPixelFormat constraint">
+    <h2>The powerEfficientPixelFormat constraint</h2>
+    <section id="mediatracksupportedconstraints-dictionary-extensions">
+      <h3>MediaTrackSupportedConstraints dictionary extensions</h3>
+      <div>
+        <pre class="idl"
+>partial dictionary MediaTrackSupportedConstraints {
+  boolean powerEfficientPixelFormat = true;
+};</pre>
+        <section>
+          <h2>Dictionary {{MediaTrackSupportedConstraints}} Members</h2>
+          <dl data-link-for="MediaTrackSupportedConstraints" data-dfn-for=
+          "MediaTrackSupportedConstraints" class="dictionary-members">
+            <dt><dfn>powerEfficientPixelFormat</dfn> of type
+            {{boolean}}, defaulting to <code>true</code></dt>
+            <dd>See <a href=
+            "#def-constraint-powerEfficientPixelFormat">
+            powerEfficientPixelFormat</a> for details.</dd>
+          </dl>
+        </section>
+      </div>
+    </section>
+    <section id="mediatrackcapabilities-dictionary-extensions">
+      <h3>MediaTrackCapabilities dictionary extensions</h3>
+      <div>
+        <pre class="idl"
+>partial dictionary MediaTrackCapabilities {
+  sequence&lt;boolean&gt; powerEfficientPixelFormat;
+};</pre>
+        <section>
+          <h2>Dictionary {{MediaTrackCapabilities}} Members</h2>
+          <dl data-link-for="MediaTrackCapabilities" data-dfn-for=
+          "MediaTrackCapabilities" class="dictionary-members">
+            <dt><dfn>powerEfficientPixelFormat</dfn> of type
+            <code>sequence&lt;{{boolean}}&gt;</code></dt>
+            <dd>
+              <p>If the source only has power efficient pixel formats, a single
+              <code>true</code> is reported. If the source only has power
+              inefficient pixel formats, a single <code>false</code> is
+              reported. If the script can control the feature, the source
+              reports a list with both <code>true</code> and <code>false</code>
+              as possible values. See <a href=
+              "#def-constraint-powerEfficientPixelFormat">
+              powerEfficientPixelFormat</a> for additional
+              details.</p>
+            </dd>
+          </dl>
+        </section>
+      </div>
+    </section>
+    <section id="mediatracksettings-dictionary-extensions">
+      <h3>MediaTrackSettings dictionary extensions</h3>
+      <div>
+        <pre class="idl"
+>partial dictionary MediaTrackSettings {
+  boolean powerEfficientPixelFormat;
+};</pre>
+        <section>
+          <h2>Dictionary {{MediaTrackSettings}} Members</h2>
+          <dl data-link-for="MediaTrackSettings" data-dfn-for=
+          "MediaTrackSettings" class="dictionary-members">
+            <dt><dfn>powerEfficientPixelFormat</dfn> of type
+            {{boolean}}</dt>
+            <dd>See <a href=
+            "#def-constraint-powerEfficientPixelFormat">
+            powerEfficientPixelFormat</a> for details.</dd>
+      </section>
+      </div>
+    </section>
+      <h2>Constrainable Properties</h2>
+      <p>The constrainable properties in this document are defined below.</p>
+      <table class="simple">
+        <thead>
+          <tr>
+            <th>Property Name</th>
+            <th>Values</th>
+            <th>Notes</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><dfn id="def-constraint-powerEfficientPixelFormat">
+              powerEfficientPixelFormat</dfn></td>
+            <td>{{ConstrainBoolean}}</td>
+            <td>
+              <p>Compressed pixel formats often need to be decoded, for instance
+              for display purposes or when being encoded during a video call.
+              The user agent SHOULD label compressed pixel formats that incur
+              significant power penalty when decoded as power inefficient. The
+              labeling is up to the user agent, but decoding MJPEG in software
+              is an example of an expensive mode. Pixel formats that have not
+              been labeled power inefficient by the user agent are for the
+              purpose of this API considered power efficient.</p>
+              <p>As a constraint, setting it to true allows filtering out
+              inefficient pixel formats and setting it to false allows filtering
+              out efficient pixel formats.</p>
+              <p>As a setting, this reflects whether or not the current pixel
+              format is considered power efficient by the user agent.</p>
+            </td>
+          </tr>
+        </tbody>
+      </table>
+    </section>
     <section>
       <h2>Algorithms</h2>
       <p>When the {{MediaDevices/getUserMedia()}} method is invoked, run the