Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Revise hardwareAcceleration based on consensus decision. #313

Merged
merged 11 commits into from
Aug 16, 2021
Merged

Revise hardwareAcceleration based on consensus decision. #313

Changes from 2 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
c985f35
Revise hardwareAcceleration based on consensus decision.
dalecurtis Jul 28, 2021
6aaa9da
Switch to lower case plus dashes for consistency.
dalecurtis Jul 28, 2021
230aa31
Add rejection step to config validation.
dalecurtis Jul 29, 2021
71cf279
Add normative text on fingerprinting for hardwareAcceleration.
dalecurtis Aug 3, 2021
9faa5da
Tweak wording.
dalecurtis Aug 9, 2021
d1e17dc
Reword to be more precise.
dalecurtis Aug 10, 2021
b4ba67e
Merge branch 'main' of https://github.com/w3c/webcodecs into hwaccel
chcunningham Aug 16, 2021
cb0ad15
Fix typo
chcunningham Aug 16, 2021
c75d1be
--amend
chcunningham Aug 16, 2021
72ce759
Remove WEBCODECS_IGNORE_WARNINGS=1
chcunningham Aug 16, 2021
4ea4dc6
Revert "Add rejection step to config validation."
chcunningham Aug 16, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 42 additions & 28 deletions index.src.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1630,7 +1630,7 @@
[EnforceRange] unsigned long codedHeight;
[EnforceRange] unsigned long displayAspectWidth;
[EnforceRange] unsigned long displayAspectHeight;
HardwareAcceleration hardwareAcceleration = "allow";
HardwareAcceleration hardwareAcceleration = "no-preference";
boolean optimizeForLatency;
};
</xmp>
Expand Down Expand Up @@ -1697,7 +1697,7 @@

<dt><dfn dict-member for=VideoDecoderConfig>hardwareAcceleration</dfn></dt>
<dd>
Configures hardware acceleration for this codec. See
Hint that configures hardware acceleration for this codec. See
{{HardwareAcceleration}}.
</dd>

Expand Down Expand Up @@ -1762,7 +1762,7 @@
[EnforceRange] unsigned long displayHeight;
[EnforceRange] unsigned long long bitrate;
[EnforceRange] double framerate;
HardwareAcceleration hardwareAcceleration = "allow";
HardwareAcceleration hardwareAcceleration = "no-preference";
AlphaOption alpha = "discard";
DOMString scalabilityMode;
BitrateMode bitrateMode = "variable";
Expand Down Expand Up @@ -1849,7 +1849,7 @@

<dt><dfn dict-member for=VideoEncoderConfig>hardwareAcceleration</dfn></dt>
<dd>
Configures hardware acceleration for this codec. See
Hint that configures hardware acceleration for this codec. See
{{HardwareAcceleration}}.
</dd>

Expand Down Expand Up @@ -1885,30 +1885,41 @@
---------------------------------------------
<xmp class='idl'>
enum HardwareAcceleration {
dalecurtis marked this conversation as resolved.
Show resolved Hide resolved
"allow",
"deny",
"require",
"no-preference",
Copy link
Contributor

@youennf youennf Jul 30, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed in #239, I tend to prefer a more descriptive default value.
@dalecurtis mentionned renaming no-preference to prefer-efficiency if we can all agree on this default behavior.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I defer final decision to @aboba @padenot, I prefer no-preference.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

no-preference is fine. I've also seen "balanced" used.

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find this rather descriptive. In passing this value, the author explicitly signals that they don't have any particular preference, and defers to the UA to make the decision on what decoder to use, based on the scenario characteristics (on battery power, video resolution, etc.).

"prefer-hardware",
"prefer-software",
};
</xmp>

When supported, hardware acceleration offloads encoding or decoding to
specialized hardware.
specialized hardware. {{HardwareAcceleration/prefer-hardware}} and
{{HardwareAcceleration/prefer-software}} are hints. While User Agents SHOULD
respect these values when possible, User Agents may ignore these values in some
or all circumstances for any reason.

<div class='note'>
NOTE: Good examples of when a User Agent may ignore
{{HardwareAcceleration/prefer-hardware}} or
{{HardwareAcceleration/prefer-software}} are for reasons of user privacy or
circumstances where the User Agent determines an alternative setting would
better serve the end user.

NOTE: Most authors will be best served by using the default of
{{HardwareAcceleration/allow}}. This gives the User Agent flexibility to
optimize based on its knowledge of the system and configuration. A common
{{HardwareAcceleration/no-preference}}. This gives the User Agent flexibility
to optimize based on its knowledge of the system and configuration. A common
strategy will be to prioritize hardware acceleration at higher resolutions
with a fallback to software codecs if hardware acceleration fails.

Authors should carefully weigh the tradeoffs when setting a hardware acceleration
preference. The precise tradeoffs will be device-specific, but authors should
generally expect the following:
Authors should carefully weigh the tradeoffs when setting a hardware
acceleration preference. The precise tradeoffs will be device-specific, but
authors should generally expect the following:

* Setting a value of {{HardwareAcceleration/require}} may significantly
restrict what configurations are supported. It may occur that the user's
device does not offer acceleration for any codec, or only for the most
common profiles of older codecs.
* Setting a value of {{HardwareAcceleration/prefer-hardware}} or
{{HardwareAcceleration/prefer-software}} may significantly restrict what
configurations are supported. It may occur that the user's device does not
offer acceleration for any codec, or only for the most common profiles of
older codecs. It may also occur that a given User Agent lacks a software
based codec implementation.
* Hardware acceleration does not simply imply faster encoding / decoding.
Hardware acceleration often has higher startup latency but more consistent
throughput performance. Acceleration will generally reduce CPU load.
Expand All @@ -1920,33 +1931,36 @@
may yield decreased performance and power efficiency compared to purely
software based codecs.

Given these tradeoffs, a good example of using "require" would be if an author
intends to provide their own software based fallback via WebAssembly.
Given these tradeoffs, a good example of using "prefer-hardware" would be if
an author intends to provide their own software based fallback via
WebAssembly.

Alternatively, a good example of using "disallow" would be if an author is
especially sensitive to the higher startup latency or decreased robustness
Alternatively, a good example of using "prefer-software" would be if an author
is especially sensitive to the higher startup latency or decreased robustness
generally associated with hardware acceleration.
</div>

<dl>
<dt><dfn enum-value for=HardwareAcceleration>allow</dfn></dt>
<dt><dfn enum-value for=HardwareAcceleration>no-preference</dfn></dt>
<dd>
Indicates that the User Agent may use hardware acceleration if it is
available and compatible with other aspects of the codec configuration.
</dd>
<dt><dfn enum-value for=HardwareAcceleration>deny</dfn></dt>
<dt><dfn enum-value for=HardwareAcceleration>prefer-software</dfn></dt>
<dd>
Indicates that the User Agent must not use hardware acceleration.
Indicates that the User Agent SHOULD prefer a software codec implementation.
User Agents may ignore this value for any reason.

NOTE: This will cause the configuration to be unsupported on platforms where
NOTE: This may cause the configuration to be unsupported on platforms where
an unaccelerated codec is unavailable or is incompatible with other aspects
of the codec configuration.
</dd>
<dt><dfn enum-value for=HardwareAcceleration>require</dfn></dt>
<dt><dfn enum-value for=HardwareAcceleration>prefer-hardware</dfn></dt>
<dd>
Indicates that the User Agent must use hardware acceleration.
Indicates that the User Agent SHOULD prefer hardware acceleration. User
Agents may ignore this value for any reason.

NOTE: This will cause the configuration to be unsupported on platforms where
NOTE: This may cause the configuration to be unsupported on platforms where
dalecurtis marked this conversation as resolved.
Show resolved Hide resolved
an accelerated codec is unavailable or is incompatible with other aspects of
the codec configuration.
</dd>
Expand Down