Skip to content

Add HDR headroom to ScreenDetailed #150

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

Open
ccameron-chromium wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add HDR headroom to ScreenDetailed #150

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
93cbb1b
Add HDR headroom to ScreenDetailed
ccameron-chromium Jun 13, 2025
7d339e7
Say greater than zero, not non-zero
ccameron-chromium Jun 13, 2025
839b336
Incorporate review feedback
ccameron-chromium Jun 13, 2025
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
33 changes: 33 additions & 0 deletions index.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,13 @@ Assume Explicit For: yes
</style>

<pre class=anchors>
spec: css-color-hdr; urlPrefix: https://drafts.csswg.org/css-color-hdr/
type: dfn; text: HDR headroom; url: hdr-headroom
type: dfn; text: HDR reference white; url: hdr-reference-white
type: dfn; text: standard dynamic range; url: standard-dynamic-range
type: dfn; text: high dynamic range; url: high-dynamic-range
spec: css-color-4; urlPrefix: https://drafts.csswg.org/css-color-4/
type: dfn; text: white; url: valdef-color-white
spec: css-values-4; urlPrefix: https://drafts.csswg.org/css-values-4/
type: dfn; text: CSS pixel; url: px
spec: fingerprinting-guidance; urlPrefix: https://www.w3.org/TR/fingerprinting-guidance/
Expand Down Expand Up @@ -280,6 +287,10 @@ Note: The [=screen/label=] can be an arbitrary string selected by the user agent

Advisement: While many screen attributes could be used for [=/active fingerprinting=], the strings used as [=screen/labels=] in particular should be considered carefully to minimize the uniqueness. For example, it would be a poor choice to include the serial number of the device.

A [=/screen=] has an <dfn>HDR headroom</dfn>, which is the current [=/HDR headroom=] of the screen.

Note: The [=screen/HDR headroom=], being the base 2 logarithm of the peak luminance of the screen to the [=/HDR reference white=] luminance of the screen (which is the luminance of '[=/white=]') has to be zero for [=/standard dynamic range=] displays. For [=/high dynamic range=] capable displays it can be zero or greater than zero and can vary over time in response to changes in the presence or absence of HDR content on the screen, screen brightness, ambient brightness, power management feature, and other factors.
Copy link

@cnanda-adobe cnanda-adobe Jul 7, 2025

Choose a reason for hiding this comment

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

Sorry, I am missing some details here.
How peak luminance of the screen is specified? Is it read from the OS/display settings?

Copy link
Author

@ccameron-chromium ccameron-chromium Jul 9, 2025

Choose a reason for hiding this comment

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

Some operating systems (Windows) expose the peak luminance, and the headroom is derived from the ratio.

Other operating systems (macOS, iOS, Android) just expose the ratio and abstract away the peak.


Issue: Should [=screen/device pixel ratio=] include the [page-zoom](https://drafts.csswg.org/cssom-view-1/#page-zoom)?

</div>
Expand Down Expand Up @@ -414,6 +425,8 @@ The <dfn for="screen">advanced observable properties</dfn> of a [=/screen=] are:
* The [=/screen=]'s designation as [=/primary=] or [=/secondary=]
* The [=/screen=]'s designation as [=/internal=] or [=/external=]

Note: The [=/screen=]'s [=screen/HDR headroom=] is included in neither the [=screen/basic observable properties=] nor the [=screen/advanced observable properties=] because it changes independently of these properties and at high frequency.

<!-- ====================================================================== -->
# API # {#api}
<!-- ====================================================================== -->
Expand Down Expand Up @@ -662,6 +675,12 @@ A {{ScreenDetailed}} object represents a [=/screen=].
: |screenDetailed| . {{ScreenDetailed/label}}
:: A user-friendly label for the screen, determined by the user agent and OS.

: |screenDetailed| . {{ScreenDetailed/hdrHeadroom}}
:: Returns the [=screen/HDR headroom=] of the screen.

: |screenDetailed| . {{ScreenDetailed/onhdrheadroomchange}}
:: Fired when this screen's [=screen/HDR headroom=] attribute changes.

</div>

<xmp class=idl>
Expand All @@ -675,6 +694,8 @@ interface ScreenDetailed : Screen {
readonly attribute boolean isInternal;
readonly attribute float devicePixelRatio;
readonly attribute DOMString label;
readonly attribute float hdrHeadroom;
attribute EventHandler onhdrheadroomchange;
};
</xmp>

Expand All @@ -694,6 +715,8 @@ The <dfn attribute for=ScreenDetailed>devicePixelRatio</dfn> getter steps are to

The <dfn attribute for=ScreenDetailed>label</dfn> getter steps are to return the [=screen/label=] of [=/this=] [=/screen=].

The <dfn attribute for=ScreenDetailed>hdrHeadroom</dfn> getter steps are to return the [=screen/HDR headroom=] of [=/this=] [=/screen=].

<!-- ====================================================================== -->
### {{ScreenDetailed/onchange}} attribute ### {#api-screendetailed-onchange-attribute}
<!-- ====================================================================== -->
Expand All @@ -702,6 +725,16 @@ The <dfn attribute for=ScreenDetailed>onchange</dfn> attribute is the {{Screen/o

When any [=screen/basic observable property=] or [=screen/advanced observable property=] of a [=/screen=] represented by a {{ScreenDetailed}} object |screenDetailed| changes, [=/queue a global task=] on the [=/relevant global object=] of |screenDetailed| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=ScreenDetailed>`change`</dfn> at |screenDetailed|.

<!-- ====================================================================== -->
### {{ScreenDetailed/onhdrheadroomchange}} attribute ### {#api-screendetailed-onhdrheadroomchange-attribute}
<!-- ====================================================================== -->

The <dfn attribute for=ScreenDetailed>onhdrheadroomchange</dfn> attribute is an [=/event handler IDL attribute=] whose [=/event handler event type=] is {{ScreenDetailed/hdrheadroomchange!!event}}.

When the [=screen/HDR headroom=] of a [=/screen=] represented by a {{ScreenDetailed}} object |screenDetailed| changes, [=/queue a global task=] on the [=/relevant global object=] of |screenDetailed| using the [=/window placement task source=] to [=/fire an event=] named <dfn event for=ScreenDetailed>`hdrheadroomchange`</dfn> at |screenDetailed|.

Note: When the [=screen/HDR headroom=] of a [=/screen=] changes, no event of type {{ScreenDetailed/change!!event}} will be fired. This is because the [=screen/HDR headroom=] of a screen changes independently of the properties that would fire such an event. Additionally, changes in the [=screen/HDR headroom=] often happen at high frequency (e.g, when a [=/screen=] is transitioning into high dynamic range mode, or when a [=/screen=] is adjusting its brightness).

<!-- ====================================================================== -->
## Extensions to {{FullscreenOptions}} ## {#api-extensions-to-fullscreen-options}
<!-- ====================================================================== -->
Expand Down