[screen-orientation] Review comments for ScreenOrientation API

Hi,

During DAS meeting I’ve got an action point [1] to review ScreenOrientation
API [2].
No scope of the review was specified, so I went through concepts and
definitions
provided by the spec. If some of my comments are invalid, please disregard
them.

Short summary:

- Screen interface [3] defines physical properties of the output device,
yet,
  Screen.orientation provides document orientation / changes / locking.
- ScreenOrientation.angle provides rotation angle of the document, rather
  than the screen. Specification of the angle property as well as its
  implementation prone to fragmentation and could be improved.
- ScreenOrientation.lock locks document orientation, not the screen
orientation.
  Screen orientation changes are not emitted when document orientation is
locked.
- Might be nice to have event for default orientation changes (2-in-1
devices)
- Would be good to have information about how orientation type is obtained
  (e.g., EDID + OS display info + optional sensors).
- Would be nice to have an API for getting default (natural) orientation.
- Sync definition of orientation (e.g., device’s coordinate system) with
other
  specs (WebVR, DeviceMotion & Orientation, Sensors).


Detailed information:

Screen interface in CSSOM view spec describes properties of the output
device as well as rendering surface properties. I think specification can be
more explicit in defining what ScreenOrientation means in relation to
physical
orientation of output device’s screen. At the moment, it looks like:
ScreenOrientation == DocumentOrientation.

Based on assumption that ScreenOrientation should provide physical
orientation
of the output device’s screen, here are my review comments.


1. ScreenOrientation.angle

As a developer, I think that the angle should represent physical screen
rotation
from device’s default orientation, taking into account device’s local
coordinate
system, for example, around Z axis that is pointing from device’s screen.
Therefore, positive angle value would denote counterclockwise rotation from
default orientation.

It was confusing to find out that ScreenOrientation.angle is not an angle
between
default orientation and current screen orientation. It’s the angle between
document orientation and default orientation of the device’s screen.

Also, I think, specification is not taking into account use-cases when
device
could change its default orientation at runtime. For example, 2-in-1 might
have
‘landscape == default’ when keyboard attached and ‘portrait == default’ when
keyboard is detached.

Maybe it is better to deprecate (rethink) ScreenOrientation.angle property?
Even the spec states that angle and orientation enum can be out-of-sync,
and has
to be synced by web developers at runtime. For convertibles, developers
would
need to re-sync when default orientation changes. Wouldn’t it be better to
keep
enums and add informative notes for possible relations between rotation
angles
and orientation?

I also did some quick testing of the API on different platforms, results are
in [Test results] section. Results show that angle property in the current
form
is not that useful and introduces fragmentation between platforms.


2. ScreenOrientation.type

Mapping of primary / secondary values to physical orientation should be done
by the UA based on specifics of the hardware. Same should be done for
landscape
and portrait definitions. In my opinion spec should not explicitly specify
that
the the orientation is calculated only from the screen properties. What if
the
device have square screen? The device can use its sensors to determine
default
orientation.


3. ScreenOrientation.lock

The orientation lock has side-effects in my opinion. Web developers can lock
document orientation, device’s physical screen orientation lock cannot be
done
programmatically. I think, it would be better to separate these two
concepts.
For example, developers should be able to get default and current screen
orientation, as well as locked document orientation, so that web page can
adapt
and re-lock document orientation if needed.


4. Screen rotation when device is parallel to the ground

I’ve tested latest chromium canary and when the device is parallel to the
ground and rotated (around Z axis), screen orientation is not affected at
all.
Should it?


5. Test results (Chromium browser)

## macOS (laptop, default orientation)

 - ScreenOrientation.type: landscape-primary
 - ScreenOrientation.angle:  0 deg.

Output to external display rotated 90 degrees in settings,  monitor rotated
90
degrees CW, rendering surface rotated 90 degrees CCW from default
orientation.

 - ScreenOrientation.type: portrait-primary
 - ScreenOrientation.angle: 90 deg.


## Windows 8.1 (laptop, default orientation)

 - ScreenOrientation.type: landscape-primary
 - ScreenOrientation.angle: 0 deg.

Output to external display rotated 90 degrees in settings, monitor rotated
90
degrees CW, rendering surface rotated 90 degrees CCW from default
orientation.

 - ScreenOrientation.type: portrait-primary
 - ScreenOrientation.angle: 270 deg.


## Linux (desktop)

Physical screen orientation does not matter, orientation is calculated from
viewport size, thus, changing browser’s window size affects orientation.

## Android (PixelXL, default orientation)

 - ScreenOrientation.type: portrait-primary
 - ScreenOrientation.angle: 0 deg.

Device rotated 90 degrees CCW, content rotated 90 CW.

 - ScreenOrientation.type: landscape-primary
 - ScreenOrientation.angle: 90 deg.

When auto-rotate is disabled in settings, no notifications are delivered
through
the API, yet, physical orientation of the screen is changing.

[1] - https://www.w3.org/2017/03/23-dap-minutes.html#action01
[2] - https://w3c.github.io/screen-orientation/
[3] - https://www.w3.org/TR/cssom-view-1/#the-screen-interface

Best regards,
Alexander