On this page

Pixels and high DPI

The engine lays out in logical units and draws in physical pixels. One scale joins them, on every platform, so text and edges stay sharp on a dense display and a layout keeps its size when a window moves between screens.

Two kinds of pixel

SpaceWho uses it
PhysicalThe window extent, the swapchain or drawable, the raw pointer position from the system, and the native pass at level two.
LogicalLayout, styles, ui::input, isolen_frame::width and height, the draw list and the app descriptor's window size.

The scale is isolen_frame::scale, physical pixels per logical unit. It is the display density times the ui scale:

  • Density. On mac it is the screen's backing scale, 2 on a Retina display. On Windows it is the monitor DPI over 96, so 144 DPI is 1.5.
  • ui scale. A zoom on top, 1 by default and clamped to 0.5 to 3. Ctrl with plus, minus and 0 step it by 1.1 or reset it, and on Windows Ctrl with the wheel steps it too.

The ui scale lays the tree out again at the new size. The pinch zoom is a different thing: it magnifies the page as drawn and keeps the layout, and it is not part of the scale. Its magnification is isolen_frame::zoom, and input over the page arrives already in page units.

Each frame

  1. The shell takes the physical extent and divides it by the scale. That is the logical size the tree is laid out at.
  2. Input is divided the same way, so mouse_x and mouse_y are logical and match the boxes they hit.
  3. The tree and the frame's list are recorded in logical units.
  4. gfx_frame_draw takes the scale and draws them against the physical extent, so glyphs and edges land on whole device pixels.
  5. Anything handed back to the system, such as the IME caret, is multiplied by the scale on the way out.

The shell logs the density, the scale and the physical and logical sizes whenever the density changes. Code that draws with a device on its own passes its own scale to gfx_frame_draw.

Windows

  • Every exe carries a manifest that makes it per monitor DPI aware, version 2, so Windows never stretches its pixels. It is added to each target through the build.
  • A binary linked without it asks for per monitor v2 at runtime, then v1, then system awareness on old systems. The log says which it got, and warns when the process is not per monitor aware, since text would blur.
  • The window keeps its DPI and scale. When it moves to a screen of another density it takes the size Windows suggests, keeps a full screen or maximised frame covering its monitor, and rescales the size it restores to.
  • The width and height an app asks for are logical, like points on a mac, and are multiplied by the DPI when the window is made. The resize edge and the default restore size scale too.
  • Monitor sizes are reported in logical units, and ISOLEN_MONITOR_SMALLEST compares logical areas, so a dense small panel is judged by its real size.
  • Moving a window to another monitor centres it again after the new density resizes it.

mac

The backing scale comes from the window's screen and is refreshed with the view's size. The drawable is the view bounds times that scale.

At level two the native encoder and target are physical. Size a pass by the drawable, and multiply a logical rect from the tree by scale before using it as a viewport or scissor.

Last updated 23 September 2026