.. _DeviceInfo_DisplayCutouts: Display cutouts =============== Overview of all display cutout keys:: : CollapsedPanelHeight: DisplayCutoutsCollapsed: - - ... DisplayCutoutsCollapsedLight: - - ... DisplayCutoutsExpanded: - - ... 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 (:math:`r`) and the central cutout height (:math:`h`) you can calculate an approximate corner avoidance area width (:math:`w`) with the following equation: .. math:: 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: .. figure:: /_static/images/porting/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. .. raw:: html :file: ../../../_static/images/porting/cutouts-sample-overlaid.svg 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 .. _tool-notch-helper: https://gitlab.com/ubports/porting/tools/tool-notch-helper .. _gmobile: https://gitlab.gnome.org/World/Phosh/gmobile/-/tree/main/data/devices/display-panels