Jump to content

Creating gmobile cutout files

From postmarketOS Wiki

gmobile display-panel files describe device-specific screen geometry, such as rounded corners, notches and punch-hole camera cutouts. Phosh uses this information to keep shell UI elements like the top bar, clock and status icons away from unusable parts of the display. When this data is missing, Phosh may draw content underneath a camera hole or too close to rounded corners. This page explains how to create candidate gmobile cutout files from Android/LineageOS device overlay data, test them on postmarketOS, and prepare them for upstream submission.

Note The files generated by these tools are candidates. Always validate the result on the target device, for example with Phosh/Phoc cutout debugging, before upstreaming it to gmobile or relying on it in a device port.

lineage_cutout_to_gmobile is a helper script for generating gmobile display-panel JSON files from LineageOS Android device overlay repositories.

It is useful when Phosh does not correctly avoid a notch, punch-hole camera cutout or rounded screen corners. Many Android/LineageOS device trees already contain display cutout and rounded-corner information in framework overlay resources, while gmobile only contains display-panel data for some devices.

The related autogenerated_gmobile_files repository contains generated JSON candidates, currently focused on Xiaomi devices.

Repositories

What the generator extracts

The generator clones a LineageOS device repository named like:

android_device_<oem>_<codename>

It then scans the repository, and optionally related repositories, for display information such as:

  • display resolution
  • rounded corner radius values
  • Android display cutout paths
  • Android display cutout rectangular approximations
  • display density, when needed for converting dp/dip values to pixels

The Android cutout path is converted to the coordinate system expected by gmobile. Android's default cutout path origin is the top center of the display, while gmobile display-panel JSON paths use normal display coordinates.

Requirements

  • Python 3.9 or newer
  • git
  • optional: json-glib-validate, for validating the generated JSON

No third-party Python packages are required.

Basic usage

Clone the generator:

$ git clone https://github.com/PiotrZPL/lineage_cutout_to_gmobile.git
$ cd lineage_cutout_to_gmobile

Generate a display-panel JSON file:

$ python3 main.py <oem> <codename> --output-dir ./display-panels

For example, for the Xiaomi Redmi Note 10 Pro/Pro Max (xiaomi-sweet):

$ python3 main.py xiaomi sweet \
    --branch lineage-23.2 \
    --workdir ./lineage-device-work \
    --output-dir ./display-panels \
    --force \
    --print-notes

This writes:

display-panels/xiaomi,sweet.json

If --branch is omitted, the script tries to use the newest available lineage-* branch.

Common options

Option Description
--branch BRANCH Use a specific LineageOS branch, for example lineage-23.2. If omitted, the newest available lineage-* branch is selected automatically.
--workdir DIR Directory where LineageOS repositories are cloned.
--output-dir DIR Directory where the generated JSON file is written.
--output-file PATH Write the generated JSON to an exact path instead of using --output-dir.
--repo-url URL Use a specific device repository instead of the default https://github.com/LineageOS/android_device_<oem>_<codename>.git.
--clone-dependencies Also clone repositories listed in lineage.dependencies. This is useful when display overlays are inherited from a common device tree.
--use-wiki Use LineageOS wiki device YAML metadata as a fallback for display resolution.
--compatible STEM Choose the output filename stem, for example xiaomi,sweet. This is useful when the Linux device-tree compatible differs from the LineageOS repo name.
--x-res PX Override the detected horizontal resolution.
--y-res PX Override the detected vertical resolution.
--density DPI Override the detected Android screen density. This is needed when the Android overlay uses dp or dip values and density was not detected automatically.
--corner-format auto Automatically choose how rounded corners are emitted.
--corner-format border-radius Emit a single border-radius value.
--corner-format corner-radii Emit explicit per-corner values.
--use-rect-approx Use Android's rectangular cutout approximation instead of the exact cutout path.
--include-physical-size Estimate physical display width and height from the display diagonal, if available.
--update Update an existing checkout instead of reusing it as-is.
--depth N Set the Git clone depth. Use --depth 0 for a full clone.
--force Overwrite an existing output JSON file.
--no-validate Skip json-glib-validate.
--print-notes Print detection notes, including where values were found.

Run the script with --help for the full CLI reference:

$ python3 main.py --help

Examples

Generate a file for a normal LineageOS device tree

$ python3 main.py xiaomi sweet \
    --output-dir ./display-panels \
    --force \
    --print-notes

Use a specific branch

$ python3 main.py xiaomi sweet \
    --branch lineage-23.2 \
    --output-dir ./display-panels

Clone dependency repositories too

Some devices inherit overlays from a common tree. In that case, use:

$ python3 main.py xiaomi sweet \
    --clone-dependencies \
    --output-dir ./display-panels \
    --print-notes

Use LineageOS wiki metadata as fallback

Some LineageOS device trees do not contain the panel resolution directly in their README or makefiles. The generator can use LineageOS wiki metadata as a fallback:

$ python3 main.py xiaomi sweet \
    --use-wiki \
    --output-dir ./display-panels \
    --print-notes

Override missing values manually

If the display resolution or density is not detected correctly:

$ python3 main.py xiaomi sweet \
    --x-res 1080 \
    --y-res 2400 \
    --density 440 \
    --output-dir ./display-panels \
    --force

Use a custom repository URL

$ python3 main.py xiaomi sweet \
    --repo-url https://github.com/LineageOS/android_device_xiaomi_sweet.git \
    --output-dir ./display-panels

Generate a file with a custom compatible filename

gmobile filenames should match a Linux device-tree compatible string. If the LineageOS codename does not match the compatible string, use --compatible:

$ python3 main.py xiaomi sweet \
    --compatible xiaomi,sweet \
    --output-dir ./display-panels

This writes:

display-panels/xiaomi,sweet.json

Autogenerated candidate files

The autogenerated_gmobile_files repository contains JSON files generated with the helper script.

The files are named like:

<vendor>,<codename>.json

Examples:

xiaomi,peridot.json
xiaomi,sweet.json
xiaomi,venus.json

These files are useful as starting points, but should not be considered guaranteed-correct device data. Before using one:

  1. Check that the filename matches the Linux device-tree compatible string.
  2. Validate the JSON.
  3. Test the cutout and rounded corners on the device.
  4. If the result is correct, consider submitting it upstream to gmobile.

Testing with Phosh/Phoc

Copy the generated file to a local gmobile overlay directory, for example:

$ mkdir -p ~/.local/share/gmobile/display-panels
$ cp display-panels/xiaomi,sweet.json ~/.local/share/gmobile/display-panels/

Then create or edit ~/.phoshdebug:

G_RESOURCE_OVERLAYS=/mobi/phosh/gmobile/devices/display-panels=$HOME/.local/share/gmobile/display-panels
export G_RESOURCE_OVERLAYS

PHOC_DEBUG=cutouts
export PHOC_DEBUG

Restart Phosh, log out and back in, or reboot. If the debug overlay matches the physical notch or punch-hole, the JSON is likely suitable for further testing and upstreaming.

To disable the debug drawing but keep the local gmobile override, remove only the PHOC_DEBUG=cutouts line.

Upstreaming to gmobile

Once tested, submit the JSON file to gmobile:

data/devices/display-panels/<vendor>,<codename>.json

Also add the file to:

data/gmobile.gresources.xml

The merge request should mention:

  • the device model and codename
  • the Linux device-tree compatible string
  • where the values came from, for example LineageOS overlay resources
  • how the result was tested on the device

Limitations

The generated files should be reviewed manually. Possible problems include:

  • LineageOS repositories may omit display cutout information.
  • Some devices inherit overlay values from common repositories.
  • Android overlays may describe multiple regional variants.
  • Display resolution may need to be taken from LineageOS wiki metadata or provided manually.
  • Some generated files may describe the approximate Android cutout rectangle instead of the exact visual shape, depending on the options used.
  • A generated file may be syntactically valid but still visually wrong on real hardware.

See also