Display cutouts

Overview of all display cutout keys:

<devicename>:
  CollapsedPanelHeight: <height>
  DisplayCutoutsCollapsed:
    - <x> <y> <width> <height>
    - ...
  DisplayCutoutsCollapsedLight:
    - <x> <y> <width> <height>
    - ...
  DisplayCutoutsExpanded:
    - <x> <y> <width> <height>
    - ...

About device cutouts

Lomiri supports marking some screen areas as display “cutouts” - this means any areas of the screen that can’t display anything. This includes notches, punchholes, islands and rounded display corners as those have to be avoided by the indicators.

Available keys

Key

Description

Value(s)

CollapsedPanelHeight

Height of the indicator/menu panel when collapsed

Height

DisplayCutoutsCollapsed

List of cutout avoidance areas when the panel is collapsed

List of rectangles

DisplayCutoutsCollapsedLight

List of cutout avoidance areas when the panel is collapsed and in light mode

List of rectangles

DisplayCutoutsExpanded

List of cutout avoidance areas when the panel is expanded

List of rectangles

All of the values are in physical pixels.

The process requires some tinkering - some indicators change size (battery can have percentage shown, clock can show an upcoming event icon, the network indicator can be rather large with multiple SIMs, WiFi cards etc). Try to find the set of areas that looks good on all the common combinations.

The defined avoidance areas don’t have to exactly match the physical dimensions of the cutouts.

For example, on a device with a punchhole near the left side of the screen it might make sense to mark everything from the hole to the screen edge to avoid having a single smaller indicator separated from the rest.

The rightmost indicator is always the clock (when collapsed) - depending on the corner radius it can look good if the indicator slightly overlaps the corner.

If you know the pixel values for the corner radius (\(r\)) and the central cutout height (\(h\)) you can calculate an approximate corner avoidance area width (\(w\)) with the following equation:

\[w \approx r - \sqrt{r^2 - (r - \frac{1}{4}h)^2}\]

Helper app

There is a helper app intended to make the process of setting up the basic cutouts configuration easier: tool-notch-helper.

It lets you visually position and size the cutouts, compare various indicator sizes and see how they interact with the cutouts when collapsed or expanded. It can also write out and apply the config you create for faster iteration.

In case your device is supported by gmobile it will also suggest starting values based on the display shape defined there.

Examples

Device sample having the following display shape:

../../../_images/cutouts-sample.svg

The chosen avoidance areas. When collapsed, the notch cutout was offset to the left to fit one more indicator on the right side (this works because the indicators have padding around them so nothing gets actually obstructed by the notch).

For light mode the expanded cutout size was used to give the icons more space so they look more centered with the white background.

corner avoidancex: 0, width: 40 corner avoidancex: 1040, width: 40 notch (when panels collapsed) x: 468, width: 115, height: 81 notch (when panels expanded) x: 460, width: 160, height: 147

Config file:

$ cat /etc/deviceinfo/devices/sample.yaml
sample:
  CollapsedPanelHeight: 81
  DisplayCutoutsCollapsed:
    - 0 0 40 81
    - 468 0 115 81
    - 1040 0 40 81
  DisplayCutoutsCollapsedLight:
    - 0 0 40 81
    - 460 0 160 81
    - 1040 0 40 81
  DisplayCutoutsExpanded:
    - 0 0 40 147
    - 460 0 160 147
    - 1040 0 40 147