From 44a4285026a1863e74702c16197bab0a060cf633 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Fri, 17 Dec 2021 12:19:55 +0100 Subject: [PATCH 01/25] Add brightness-mode-explainer.md. Related to #129 and w3c/devicesensors-wg#51 for more context. The contents come from https://docs.google.com/document/d/1skbEBafMjKnYVC7UoJfRgnnhAkp-jx0k_Z4j6eZeOwc/edit?usp=sharing which was used while hashing out the basics and the structure. Now that the contents have matured a bit, it is time to move this to an explainer and continue iterating here. --- brightness-mode-explainer.md | 129 +++++++++++++++++++++++++++++++++++ 1 file changed, 129 insertions(+) create mode 100644 brightness-mode-explainer.md diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md new file mode 100644 index 0000000..fdfd518 --- /dev/null +++ b/brightness-mode-explainer.md @@ -0,0 +1,129 @@ +# Design Document: the need to control screen brightness + +_As discussed in the [DAS WG 2021-11-17](https://www.w3.org/2021/11/17-dap-minutes.html) meeting about Screen Brightness and the Screen Wake Lock API, the idea of this document is to make it easier for the meeting attendees to work on an explainer than if this had been committed to GitHub directly. Once this is done the goal is to move the contents to a proper explainer on GitHub._ + +Previously: +- https://github.com/WICG/proposals/issues/17 +- https://github.com/w3c/screen-wake-lock/issues/129 +- https://github.com/w3c/devicesensors-wg/issues/51 +- https://www.w3.org/2021/11/17-dap-minutes.html + +## Introduction + +There is currently a need for web applications to increase the brightness of a device's screen. + +This would help address the following use cases: +- a user scans QR/barcode under various lighting conditions. +- remote medical, where increasing the screen brightness could assist in remote examination +- biometric security apps, where increasing the screen brightness can help illuminate features to get better imagery from the front facing camera +- increasing contrast for readability for the visually impaired +- [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps + +[Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) was filed back in 2018, and since then there has been feedback from developers working on multiple areas about the usefulness of an API that addresses this use case. + +## Open design issues + +- Things to consider in the spec proposal + - UAs should be free to limit maximum brightness level and/or do other things like increase contrast. + - Idea is to focus on mobile first (i.e. not worry about external displays). How to indicate that in the spec? Does it *need* to be indicated in the spec? + - Should this trigger "`prefers-contrast: more`" in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? +- From [https://github.com/w3c/devicesensors-wg/issues/51](https://github.com/w3c/devicesensors-wg/issues/51) + - Brightness levels + - How bright is too bright? Consider 100% brightness with HDR displays, for example. + - Take a granular value or an enum? + - Related to whether script should be allowed to reduce brightness. + - Permission model + - Probably require user gesture (request but not consume it). + - How to deal with multiple or external displays + - While brightness changes + - What if users change the brightness level while the lock is held? + - When dropping screen brightness request + - Does the UA have to restore the previous brightness level? + - What about external displays? Do UAs need to keep track of levels for each display? + - Should script be allowed to "hold the lock" indefinitely? + +## Goals + +- Provide the ability to request an increase to the display's brightness. This could be a UA-controlled maximum (which *could* be the maximum display brightness), either indefinitely or for a period of time. +- Provide the ability to release the request so that the device's brightness returns to its pre-request value (i.e. hand back control to OS). +- Handle error cases, where such requests are denied or not possible. + +## Non-goals + +- Reading screen brightness level. +- Adjusting display brightness level to arbitrary values (absolute or relative). + - [\ integration to allow e.g. granular brightness control](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-926603108) is an instance of the above. This is most likely better handled elsewhere and should probably be a UA-specific control. + +## API +### Web IDL + +Extend the [Screen interface](https://drafts.csswg.org/cssom-view/#the-screen-interface) with a new operation, inspired by the [Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel). Something like: + +```webidl +[SecureContext] +partial interface Screen { + Promise requestBrightnessIncrease(); +}; + +interface ScreenBrightnessSentinel { + Promise release(); +}; +``` + +### Usage + +```javascript +myButton.addEventListener("click", async () => { + try { + const sentinel = await screen.requestBrightnessIncrease(); + console.log("The display's brightness level has increased"); + await sentinel.release(); + } catch (e) { + console.error(e); + } +}); +``` + +## Proposed Solutions + +This was initially discussed in [Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) back in 2018 and also proposed as a [separate API in WICG](https://github.com/WICG/proposals/issues/17). This topic was also discussed at multiple TPACs under the Devices and Sensors WG. As such, several different API shapes have been considered over the years. + +At this point, none have been fully discarded, and we are open to feedback about adopting some of the ideas described here. + +### Screen Wake Lock integration + +This was considered for a long time until the [2021-11-17 DAS WG meeting to discuss the topic](https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180). The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a WakeLockSentinel. Something like: + +``` javascript +const lock = await navigator.wakeLock.request({ increaseBrightness: true }); +``` + +### navigator.screenBrightness + +Originally proposed in [WICG issue 17](https://github.com/WICG/proposals/issues/17). The API proposed there had a larger surface that allowed reading the brightness value (leading to potential fingerprinting issues). + +### requestFullscreen() integration + +A mixture of [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https://github.com/whatwg/fullscreen/issues/185) and [198](https://github.com/whatwg/fullscreen/issues/198). The idea would be to do something like + +``` javascript +body.requestFullscreen({ increaseBrightness: true }); +``` + +To take advantage of existing UA privacy mitigations and UX indications that would show to the user that a web application is increasing the brightness, and leaving full screen mode would make it clear that the UA should stop increasing the device's screen's brightness level. + +### getUserMedia() integration + +Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. + +The idea was dropped because this feature is not doing media capture and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). + +### CSS property + +Some form of "scannable element" property. When an element with said property is visible, the UA would take care of increasing the brightness level. + +*Note: this is the least hashed out proposal at this point. It is unclear how this would work with zoom, permissions, low-battery mode, what happens when an element scrolls in/out of view, or even how to mitigate something like* + +``` html +* +``` From 746a70be180cc1973e91600ee75d78ebcbb371cc Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 21 Dec 2021 11:38:30 +0100 Subject: [PATCH 02/25] Make the Screen-based idea a proposed solution as well. --- brightness-mode-explainer.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index fdfd518..0e8f64b 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -54,8 +54,13 @@ This would help address the following use cases: - Adjusting display brightness level to arbitrary values (absolute or relative). - [\ integration to allow e.g. granular brightness control](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-926603108) is an instance of the above. This is most likely better handled elsewhere and should probably be a UA-specific control. -## API -### Web IDL +## Proposed Solutions + +This was initially discussed in [Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) back in 2018 and also proposed as a [separate API in WICG](https://github.com/WICG/proposals/issues/17). This topic was also discussed at multiple TPACs under the Devices and Sensors WG. As such, several different API shapes have been considered over the years. + +At this point, none have been fully discarded, and we are open to feedback about adopting some of the ideas described here. + +### Screen IDL interface extension Extend the [Screen interface](https://drafts.csswg.org/cssom-view/#the-screen-interface) with a new operation, inspired by the [Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel). Something like: @@ -70,7 +75,7 @@ interface ScreenBrightnessSentinel { }; ``` -### Usage +Proposed usage: ```javascript myButton.addEventListener("click", async () => { @@ -84,12 +89,6 @@ myButton.addEventListener("click", async () => { }); ``` -## Proposed Solutions - -This was initially discussed in [Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) back in 2018 and also proposed as a [separate API in WICG](https://github.com/WICG/proposals/issues/17). This topic was also discussed at multiple TPACs under the Devices and Sensors WG. As such, several different API shapes have been considered over the years. - -At this point, none have been fully discarded, and we are open to feedback about adopting some of the ideas described here. - ### Screen Wake Lock integration This was considered for a long time until the [2021-11-17 DAS WG meeting to discuss the topic](https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180). The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a WakeLockSentinel. Something like: From 6b44cac57ef9e3d05ad1b69a1bdee1aa13a639d9 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jan 2022 16:17:50 +0100 Subject: [PATCH 03/25] Add timeout to the code example MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: François Beaufort --- brightness-mode-explainer.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 0e8f64b..892b2b3 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -82,7 +82,10 @@ myButton.addEventListener("click", async () => { try { const sentinel = await screen.requestBrightnessIncrease(); console.log("The display's brightness level has increased"); - await sentinel.release(); + // …and release it after 5s. + window.setTimeout(() => { + await sentinel.release(); + }, 5000); } catch (e) { console.error(e); } From 67e38989c359bfc57d5ff440eab116fc0f9831d0 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Thu, 13 Jan 2022 17:57:36 +0100 Subject: [PATCH 04/25] Mention low battery in the Goals section. --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 892b2b3..68cbbf5 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -46,7 +46,7 @@ This would help address the following use cases: - Provide the ability to request an increase to the display's brightness. This could be a UA-controlled maximum (which *could* be the maximum display brightness), either indefinitely or for a period of time. - Provide the ability to release the request so that the device's brightness returns to its pre-request value (i.e. hand back control to OS). -- Handle error cases, where such requests are denied or not possible. +- Handle error or low battery cases, where such requests are denied or not possible. The API must not make it possible to determine whether a request failed due to low battery to avoid fingerprinting. ## Non-goals From 76dce08c6445e70ac03aaac1794db837c3e08259 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 11:45:59 +0100 Subject: [PATCH 05/25] Incorporate review suggestion MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Expand bullet point scanning and increased contrast. Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 68cbbf5..79edb34 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -13,7 +13,7 @@ Previously: There is currently a need for web applications to increase the brightness of a device's screen. This would help address the following use cases: -- a user scans QR/barcode under various lighting conditions. +- a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. - remote medical, where increasing the screen brightness could assist in remote examination - biometric security apps, where increasing the screen brightness can help illuminate features to get better imagery from the front facing camera - increasing contrast for readability for the visually impaired From 413a60386a7296032bc67a9128c8bbf2cd734dfa Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:01:20 +0100 Subject: [PATCH 06/25] Incorporate review suggestions. Merge make-up mirror use case with biometrical one and reword the whole item. --- brightness-mode-explainer.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 79edb34..1168855 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -15,9 +15,8 @@ There is currently a need for web applications to increase the brightness of a d This would help address the following use cases: - a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. - remote medical, where increasing the screen brightness could assist in remote examination -- biometric security apps, where increasing the screen brightness can help illuminate features to get better imagery from the front facing camera +- increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) - increasing contrast for readability for the visually impaired -- [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps [Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) was filed back in 2018, and since then there has been feedback from developers working on multiple areas about the usefulness of an API that addresses this use case. From 8bd1bdcbe4abb71b5103606f0f701644b794fe1a Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:03:11 +0100 Subject: [PATCH 07/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 1168855..ef93203 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -12,7 +12,8 @@ Previously: There is currently a need for web applications to increase the brightness of a device's screen. -This would help address the following use cases: +For developers, it would help address the following use cases: + - a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. - remote medical, where increasing the screen brightness could assist in remote examination - increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) From 95a2a04efdef6af7b691813680943eb16932eede Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:03:29 +0100 Subject: [PATCH 08/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index ef93203..7e80818 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -23,7 +23,7 @@ For developers, it would help address the following use cases: ## Open design issues -- Things to consider in the spec proposal +The following issues remain open for discussion: - UAs should be free to limit maximum brightness level and/or do other things like increase contrast. - Idea is to focus on mobile first (i.e. not worry about external displays). How to indicate that in the spec? Does it *need* to be indicated in the spec? - Should this trigger "`prefers-contrast: more`" in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? From 6db1026c983eff08202dfd13c19d464704043c8d Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:03:51 +0100 Subject: [PATCH 09/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 7e80818..ea9eca1 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -24,7 +24,7 @@ For developers, it would help address the following use cases: ## Open design issues The following issues remain open for discussion: - - UAs should be free to limit maximum brightness level and/or do other things like increase contrast. + - should UAs be free to limit maximum brightness level and/or do other things like increase contrast? - Idea is to focus on mobile first (i.e. not worry about external displays). How to indicate that in the spec? Does it *need* to be indicated in the spec? - Should this trigger "`prefers-contrast: more`" in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? - From [https://github.com/w3c/devicesensors-wg/issues/51](https://github.com/w3c/devicesensors-wg/issues/51) From fc98916f97f88fb08bf5dee01c13de0f7b56b3b8 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:04:13 +0100 Subject: [PATCH 10/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index ea9eca1..fa1fb62 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -30,7 +30,7 @@ The following issues remain open for discussion: - From [https://github.com/w3c/devicesensors-wg/issues/51](https://github.com/w3c/devicesensors-wg/issues/51) - Brightness levels - How bright is too bright? Consider 100% brightness with HDR displays, for example. - - Take a granular value or an enum? + - Take a discrete or continuous value? - Related to whether script should be allowed to reduce brightness. - Permission model - Probably require user gesture (request but not consume it). From 2cb91a8e77598ecd531091323c6fd5eddb5062e7 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:04:28 +0100 Subject: [PATCH 11/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index fa1fb62..4d921de 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -33,7 +33,7 @@ The following issues remain open for discussion: - Take a discrete or continuous value? - Related to whether script should be allowed to reduce brightness. - Permission model - - Probably require user gesture (request but not consume it). + - Would it require user gesture (request but not consume it)? - How to deal with multiple or external displays - While brightness changes - What if users change the brightness level while the lock is held? From ca0eab54c7178f2f32f60bb12f76a51f46064d22 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 12:04:51 +0100 Subject: [PATCH 12/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 4d921de..2283c77 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -46,7 +46,7 @@ The following issues remain open for discussion: - Provide the ability to request an increase to the display's brightness. This could be a UA-controlled maximum (which *could* be the maximum display brightness), either indefinitely or for a period of time. - Provide the ability to release the request so that the device's brightness returns to its pre-request value (i.e. hand back control to OS). -- Handle error or low battery cases, where such requests are denied or not possible. The API must not make it possible to determine whether a request failed due to low battery to avoid fingerprinting. +- Handle error or low battery cases, where such requests are denied or not possible. For privacy, the API must not make it possible to determine whether a request failed due to low battery. ## Non-goals From fd2a152b5c6ce53f20af38c9efc772fec5a2ac9f Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:33:19 +0100 Subject: [PATCH 13/25] Incorporate review suggestion. Reword the getUserMedia() paragraph following Marcos' suggestion. --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 2283c77..2a64c3f 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -118,7 +118,7 @@ To take advantage of existing UA privacy mitigations and UX indications that wou Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. -The idea was dropped because this feature is not doing media capture and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). +This is complicated because this feature is not doing media capture, and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). ### CSS property From ab5d893ffcc5c1934c0f342c711b842fe4a89615 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:36:57 +0100 Subject: [PATCH 14/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move whatwg/fullscreen links to the end of the section. Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 2a64c3f..0e42e89 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -106,14 +106,14 @@ Originally proposed in [WICG issue 17](https://github.com/WICG/proposals/issues/ ### requestFullscreen() integration -A mixture of [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https://github.com/whatwg/fullscreen/issues/185) and [198](https://github.com/whatwg/fullscreen/issues/198). The idea would be to do something like +The idea to integrate with `.requestFullscreen()`, to do something like: ``` javascript body.requestFullscreen({ increaseBrightness: true }); ``` To take advantage of existing UA privacy mitigations and UX indications that would show to the user that a web application is increasing the brightness, and leaving full screen mode would make it clear that the UA should stop increasing the device's screen's brightness level. - +See [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https://github.com/whatwg/fullscreen/issues/185) and [198](https://github.com/whatwg/fullscreen/issues/198). ### getUserMedia() integration Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. From 6f1577a8bf51e187bd264e53d018abcdde07415a Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:39:07 +0100 Subject: [PATCH 15/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 0e42e89..f0a85d7 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -102,7 +102,7 @@ const lock = await navigator.wakeLock.request({ increaseBrightness: true }); ### navigator.screenBrightness -Originally proposed in [WICG issue 17](https://github.com/WICG/proposals/issues/17). The API proposed there had a larger surface that allowed reading the brightness value (leading to potential fingerprinting issues). +The API proposed there had a larger surface that allowed reading the brightness value (leading to potential fingerprinting issues). Originally proposed in [WICG issue 17](https://github.com/WICG/proposals/issues/17). ### requestFullscreen() integration From 7aad21762a3288102f36d08a028721eca441ddf4 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:40:34 +0100 Subject: [PATCH 16/25] Update brightness-mode-explainer.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index f0a85d7..d23e2dd 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -94,11 +94,10 @@ myButton.addEventListener("click", async () => { ### Screen Wake Lock integration -This was considered for a long time until the [2021-11-17 DAS WG meeting to discuss the topic](https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180). The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a WakeLockSentinel. Something like: +The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a WakeLockSentinel. Something like: ``` javascript const lock = await navigator.wakeLock.request({ increaseBrightness: true }); -``` ### navigator.screenBrightness From fb253034717975cbe7ed98b50267ece9d8afaed3 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:41:42 +0100 Subject: [PATCH 17/25] Adjust previous commit. GitHub's UI botched the suggestion and erased a paragraph that should not have been removed. --- brightness-mode-explainer.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index d23e2dd..8d1bbc4 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -98,6 +98,9 @@ The idea was to extend the existing Screen Wake Lock API and tie the change in b ``` javascript const lock = await navigator.wakeLock.request({ increaseBrightness: true }); +``` + +This was considered for a long time until the [2021-11-17 DAS WG meeting to discuss the topic](https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180). ### navigator.screenBrightness From b85c6f5190abc809b20953cea7106eff2ea9f932 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:44:55 +0100 Subject: [PATCH 18/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move link to Screen Wake Lock API issue 129 to the introduction. Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 8d1bbc4..2f87a6b 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -10,7 +10,7 @@ Previously: ## Introduction -There is currently a need for web applications to increase the brightness of a device's screen. +Since 2018, the working group has received [significant requests](https://github.com/w3c/screen-wake-lock/issues/129) from web developers surrounding the need to increase the brightness of a device's screen. For developers, it would help address the following use cases: @@ -19,7 +19,6 @@ For developers, it would help address the following use cases: - increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) - increasing contrast for readability for the visually impaired -[Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) was filed back in 2018, and since then there has been feedback from developers working on multiple areas about the usefulness of an API that addresses this use case. ## Open design issues @@ -56,9 +55,9 @@ The following issues remain open for discussion: ## Proposed Solutions -This was initially discussed in [Screen Wake Lock API issue 129](https://github.com/w3c/screen-wake-lock/issues/129) back in 2018 and also proposed as a [separate API in WICG](https://github.com/WICG/proposals/issues/17). This topic was also discussed at multiple TPACs under the Devices and Sensors WG. As such, several different API shapes have been considered over the years. +The following represent some rough proposals that could address the use cases using various web technologies. -At this point, none have been fully discarded, and we are open to feedback about adopting some of the ideas described here. +We present them here only to foster discussion, and the working group has not settled on any particular one. We are open to feedback to pursuing any of the proposals below. Or, if there is a better alternative solution we have not considered, we would be open to hearing it! ### Screen IDL interface extension From 5be36bbfdd35e603f3163f51ea04bc63d1599c9d Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:46:08 +0100 Subject: [PATCH 19/25] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Marcos Cáceres --- brightness-mode-explainer.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 2f87a6b..fcaef55 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -24,7 +24,7 @@ For developers, it would help address the following use cases: The following issues remain open for discussion: - should UAs be free to limit maximum brightness level and/or do other things like increase contrast? - - Idea is to focus on mobile first (i.e. not worry about external displays). How to indicate that in the spec? Does it *need* to be indicated in the spec? + - Should this be mobile first/only? (i.e. not worry about external displays). - Should this trigger "`prefers-contrast: more`" in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? - From [https://github.com/w3c/devicesensors-wg/issues/51](https://github.com/w3c/devicesensors-wg/issues/51) - Brightness levels @@ -33,7 +33,6 @@ The following issues remain open for discussion: - Related to whether script should be allowed to reduce brightness. - Permission model - Would it require user gesture (request but not consume it)? - - How to deal with multiple or external displays - While brightness changes - What if users change the brightness level while the lock is held? - When dropping screen brightness request From 350571306df4c5e8678595f015c477dd61becf07 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:46:43 +0100 Subject: [PATCH 20/25] Add a missing empty line between headers. --- brightness-mode-explainer.md | 1 + 1 file changed, 1 insertion(+) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index fcaef55..542323a 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -114,6 +114,7 @@ body.requestFullscreen({ increaseBrightness: true }); To take advantage of existing UA privacy mitigations and UX indications that would show to the user that a web application is increasing the brightness, and leaving full screen mode would make it clear that the UA should stop increasing the device's screen's brightness level. See [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https://github.com/whatwg/fullscreen/issues/185) and [198](https://github.com/whatwg/fullscreen/issues/198). + ### getUserMedia() integration Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. From b271b84592e3a2fd78c3aef98c38720a718ca02f Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 18 Jan 2022 14:50:53 +0100 Subject: [PATCH 21/25] Move links from the beginning to the end of the text. Drop paragraph explaining what the document is about; we have already moved to GitHub. --- brightness-mode-explainer.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 542323a..dc0d8e0 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -1,13 +1,5 @@ # Design Document: the need to control screen brightness -_As discussed in the [DAS WG 2021-11-17](https://www.w3.org/2021/11/17-dap-minutes.html) meeting about Screen Brightness and the Screen Wake Lock API, the idea of this document is to make it easier for the meeting attendees to work on an explainer than if this had been committed to GitHub directly. Once this is done the goal is to move the contents to a proper explainer on GitHub._ - -Previously: -- https://github.com/WICG/proposals/issues/17 -- https://github.com/w3c/screen-wake-lock/issues/129 -- https://github.com/w3c/devicesensors-wg/issues/51 -- https://www.w3.org/2021/11/17-dap-minutes.html - ## Introduction Since 2018, the working group has received [significant requests](https://github.com/w3c/screen-wake-lock/issues/129) from web developers surrounding the need to increase the brightness of a device's screen. @@ -19,7 +11,6 @@ For developers, it would help address the following use cases: - increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) - increasing contrast for readability for the visually impaired - ## Open design issues The following issues remain open for discussion: @@ -130,3 +121,9 @@ Some form of "scannable element" property. When an element with said property is ``` html * ``` + +## Past discussions +- https://github.com/WICG/proposals/issues/17 +- https://github.com/w3c/screen-wake-lock/issues/129 +- https://github.com/w3c/devicesensors-wg/issues/51 +- https://www.w3.org/2021/11/17-dap-minutes.html From b5e2603f0f60e16dc3d7e96ae9c0e9c435eb3e65 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 25 Jan 2022 16:32:29 +0100 Subject: [PATCH 22/25] Remove a few use cases from the least. There was some agreement that these are not very good ones. --- brightness-mode-explainer.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index dc0d8e0..17b07da 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -7,9 +7,7 @@ Since 2018, the working group has received [significant requests](https://github For developers, it would help address the following use cases: - a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. -- remote medical, where increasing the screen brightness could assist in remote examination - increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) -- increasing contrast for readability for the visually impaired ## Open design issues From 5d7eafa908eaa833e88274487bb7ef8df7a46da2 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 25 Jan 2022 16:45:42 +0100 Subject: [PATCH 23/25] Add examples of mobile apps that change the screen's brightness level. --- brightness-mode-explainer.md | 1 + 1 file changed, 1 insertion(+) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 17b07da..8921e8b 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -7,6 +7,7 @@ Since 2018, the working group has received [significant requests](https://github For developers, it would help address the following use cases: - a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. + - this is already possible on native mobile apps such as [Starbucks'](https://play.google.com/store/apps/details?id=com.starbucks.mobilecard), [the UK Home Office's Document Check app](https://play.google.com/store/apps/details?id=uk.gov.HomeOffice.ho1) and the [Dutch government's CoronaCheck app](https://play.google.com/store/apps/details?id=nl.rijksoverheid.ctr.holder). - increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) ## Open design issues From 87c16ad1bd23361ae020c98ddd8991d36c2044f1 Mon Sep 17 00:00:00 2001 From: Raphael Kubo da Costa Date: Tue, 25 Jan 2022 16:46:30 +0100 Subject: [PATCH 24/25] Elaborate a bit more on why getUserMedia() is not a good option. --- brightness-mode-explainer.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index 8921e8b..ecc36f7 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -109,7 +109,7 @@ See [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https: Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. -This is complicated because this feature is not doing media capture, and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). +This is complicated because this feature is not doing media capture (and there is no MediaStream to get out of screen brightness), and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). ### CSS property From ef91054c4e5e4b832ee90b0d7998918c26b81399 Mon Sep 17 00:00:00 2001 From: Thomas Steiner Date: Wed, 26 Jan 2022 14:13:52 +0100 Subject: [PATCH 25/25] Apply suggestions from code review --- brightness-mode-explainer.md | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/brightness-mode-explainer.md b/brightness-mode-explainer.md index ecc36f7..181f049 100644 --- a/brightness-mode-explainer.md +++ b/brightness-mode-explainer.md @@ -6,26 +6,26 @@ Since 2018, the working group has received [significant requests](https://github For developers, it would help address the following use cases: -- a user scans QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. +- a user scans a QR/barcode under various lighting conditions, in which case boosting the screen brightness creates more contrast. - this is already possible on native mobile apps such as [Starbucks'](https://play.google.com/store/apps/details?id=com.starbucks.mobilecard), [the UK Home Office's Document Check app](https://play.google.com/store/apps/details?id=uk.gov.HomeOffice.ho1) and the [Dutch government's CoronaCheck app](https://play.google.com/store/apps/details?id=nl.rijksoverheid.ctr.holder). -- increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action) +- increasing the screen brightness can help illuminate a user's facial features, improving the viability of certain application that rely on the front facing camera (e.g., [make up mirror](https://play.google.com/store/apps/details?id=mmapps.mirror.pro&hl=en&gl=US) style apps, and applications that can scan people's facial features to perform some particular action). ## Open design issues The following issues remain open for discussion: - - should UAs be free to limit maximum brightness level and/or do other things like increase contrast? - - Should this be mobile first/only? (i.e. not worry about external displays). - - Should this trigger "`prefers-contrast: more`" in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? + - should UAs be free to limit the maximum brightness level and/or do other things like increase the contrast? + - Should this be mobile first/only? (i.e., not worry about external displays)? + - Should this trigger `prefers-contrast: more` in [CSS Media Queries](https://drafts.csswg.org/mediaqueries-5/#prefers-contrast)? - From [https://github.com/w3c/devicesensors-wg/issues/51](https://github.com/w3c/devicesensors-wg/issues/51) - Brightness levels - How bright is too bright? Consider 100% brightness with HDR displays, for example. - Take a discrete or continuous value? - Related to whether script should be allowed to reduce brightness. - Permission model - - Would it require user gesture (request but not consume it)? + - Would it require a user gesture (request but not consume it)? - While brightness changes - What if users change the brightness level while the lock is held? - - When dropping screen brightness request + - When dropping a screen brightness request - Does the UA have to restore the previous brightness level? - What about external displays? Do UAs need to keep track of levels for each display? - Should script be allowed to "hold the lock" indefinitely? @@ -33,24 +33,24 @@ The following issues remain open for discussion: ## Goals - Provide the ability to request an increase to the display's brightness. This could be a UA-controlled maximum (which *could* be the maximum display brightness), either indefinitely or for a period of time. -- Provide the ability to release the request so that the device's brightness returns to its pre-request value (i.e. hand back control to OS). +- Provide the ability to release the request so that the device's brightness returns to its pre-request value (i.e., hand back control to OS). - Handle error or low battery cases, where such requests are denied or not possible. For privacy, the API must not make it possible to determine whether a request failed due to low battery. ## Non-goals -- Reading screen brightness level. -- Adjusting display brightness level to arbitrary values (absolute or relative). - - [\ integration to allow e.g. granular brightness control](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-926603108) is an instance of the above. This is most likely better handled elsewhere and should probably be a UA-specific control. +- Reading the current screen brightness level. +- Adjusting the display brightness level to arbitrary values (absolute or relative). + - [\ integration to allow, e.g., granular brightness control](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-926603108) is an instance of the above. This is most likely better handled elsewhere and should probably be a UA-specific control. ## Proposed Solutions -The following represent some rough proposals that could address the use cases using various web technologies. +The following represents some rough proposals that could address the use cases using various web technologies. -We present them here only to foster discussion, and the working group has not settled on any particular one. We are open to feedback to pursuing any of the proposals below. Or, if there is a better alternative solution we have not considered, we would be open to hearing it! +We present them here only to foster discussion, and the working group has not settled on any particular one. We are open to feedback to pursue any of the proposals below. Or, if there is a better alternative solution we have not considered, we would be open to hearing it! ### Screen IDL interface extension -Extend the [Screen interface](https://drafts.csswg.org/cssom-view/#the-screen-interface) with a new operation, inspired by the [Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel). Something like: +Extend the [`Screen` interface](https://drafts.csswg.org/cssom-view/#the-screen-interface) with a new operation, inspired by the [Wake Lock API](https://developer.mozilla.org/en-US/docs/Web/API/WakeLockSentinel). Something like: ```webidl [SecureContext] @@ -82,7 +82,7 @@ myButton.addEventListener("click", async () => { ### Screen Wake Lock integration -The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a WakeLockSentinel. Something like: +The idea was to extend the existing Screen Wake Lock API and tie the change in brightness to a `WakeLockSentinel`. Something like: ``` javascript const lock = await navigator.wakeLock.request({ increaseBrightness: true }); @@ -90,13 +90,13 @@ const lock = await navigator.wakeLock.request({ increaseBrightness: true }); This was considered for a long time until the [2021-11-17 DAS WG meeting to discuss the topic](https://www.w3.org/events/meetings/0f623aa1-2026-4366-846b-c2faedda4180). -### navigator.screenBrightness +### `navigator.screenBrightness` The API proposed there had a larger surface that allowed reading the brightness value (leading to potential fingerprinting issues). Originally proposed in [WICG issue 17](https://github.com/WICG/proposals/issues/17). -### requestFullscreen() integration +### `requestFullscreen()` integration -The idea to integrate with `.requestFullscreen()`, to do something like: +The idea to integrate with `Element.requestFullscreen()`, to do something like: ``` javascript body.requestFullscreen({ increaseBrightness: true }); @@ -107,9 +107,9 @@ See [whatwg/fullscreen](https://fullscreen.spec.whatwg.org/) issues [185](https: ### getUserMedia() integration -Add something to getUserMedia() to bundle the request for brightness into the media capture request itself. +Add something to `getUserMedia()` to bundle the request for brightness into the media capture request itself. -This is complicated because this feature is not doing media capture (and there is no MediaStream to get out of screen brightness), and the need to ask for camera permission before e.g. entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). +This is complicated because this feature is not doing media capture (and there is no `MediaStream` to get out of screen brightness), and the need to ask for camera permission before, e.g., entering full screen mode [complicates some use cases](https://github.com/w3c/screen-wake-lock/issues/129#issuecomment-858790397). ### CSS property