Virtual displays

A virtual display exists in the macOS display hierarchy with nothing on the other end of it. macOS composites into it, applications lay out for it, and a screen sharing client streams from it. The only thing missing is the panel.

Pixel size and HiDPI

The Pixel Size field is the native framebuffer, in pixels. The HiDPI toggle decides whether the display also advertises the 2x modes derived from it.

The mistake to avoid is thinking in the numbers System Settings shows. macOS presents a Retina display as “looks like 2560 x 1440” while the panel is 5120 x 2880. MoreDisplays asks for the panel, and HiDPI is what produces the “looks like” modes on top of it.

Picking numbers for a client

Start from the client’s own panel. The catalogue does this for you: pick the iPad or the MacBook from the template picker and the numbers arrive correct.

When you are typing them yourself, these are reasonable starting points.

Set one, connect, look at it, adjust. There is no substitute for looking.

Rotation

A display can be rotated by 90, 180 or 270 degrees, and the rotation is part of the spec rather than something applied afterwards. A portrait panel is a landscape panel with a rotation, not a display with its width and height swapped, and macOS reports the two differently to applications.

Rotation is captured with the rest of the group, so a portrait side panel comes back portrait.

The physical size it reports, and why it is a lie

Every display tells macOS how large it physically is, and macOS divides pixels by millimetres to get a density. A virtual display has no physical size, so the app derives one.

It cannot simply use the real panel’s millimetres. The private interface refuses a descriptor whose pixel density is too high for the declared size, so the millimetres are computed from a target density rather than taken from the catalogue. The default target is 150 PPI, which sits comfortably inside what the interface accepts.

There is an override on the spec for the cases where a client renders at an obviously wrong scale and the density is the reason. Reach for it last, after checking the pixel size and the HiDPI toggle, because those explain the problem far more often.

Two behaviours to know about

Displays vanish when the app quits or crashes. They belong to the app, and it releases them when it stops. That is deliberate: a display no running process owns cannot be reconfigured or removed until the next reboot, which is worse than not having it. Orphans from a crash are detected at the next launch through the vendor identifier stamped on everything the app creates, and cleaned up.

There is a kill switch. Turning off Allow virtual displays in Settings stops the app creating any and releases those that exist. It is the first thing to check when nothing appears and no error is shown.

What is available on which macOS

Creating a display uses an interface that is not public API.

Next

• Templates and the catalogue so you do not have to type any of this.
• Refresh rates for high refresh and the exact NTSC-derived rates.