feat(display): size virtual displays from the client's image area

The stream protocol carries pixels, never physical dimensions, so the host
cannot tell a 2504-pixel-wide phone panel from a 2504-pixel-wide monitor.
effective_virtual_display_scale_percent() therefore guessed a Windows scale
from the short edge alone, and buttons, text, and the cursor landed at a
different physical size on the client than they have on the host's monitor.

Add dd_virtual_display_image_width_mm: the measured width, in millimetres, of
the image area the client actually displays. When set, the virtual display
advertises that size through its synthetic EDID and Windows derives DPI from it
the same way it does for a real monitor. The Windows scale becomes a value
derived from the measurement rather than the primary input, which is both more
precise than a picked percentage and closer to how Windows expects to be told
about a display.

The width describes the image area, not the device. A letterboxed stream is
smaller than the panel carrying it, so the height is derived from the width and
the requested mode's pixel aspect instead of from the panel's shape.

Both halves stay pure functions of the configuration. Reconnecting re-runs them
against a display that already carries the previous answer, so neither may read
back what it wrote last time; a covering test pins that down. An explicit
dd_virtual_display_scale still wins, and 0 still leaves the Windows DPI setting
untouched.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: lbonafe-codezi

docs/configuration.md

@@ -4229,6 +4229,33 @@ Controls AMD's high-motion quality boost. Use `auto` to leave the driver default
 
 Sets how long a paused virtual display may remain ready before the display helper releases it. Set `0` to disable the timeout.
 
+### dd_virtual_display_image_width_mm
+
+Sets the width, in millimetres, of the image area the client actually displays. Set `0` to disable.
+
+The stream protocol carries pixels, not physical dimensions, so the host cannot tell a 2504-pixel-wide
+phone panel from a 2504-pixel-wide desktop monitor. Left to itself it guesses a scale from the
+resolution, and buttons, text, and the cursor end up a different physical size on the client than they
+are on the host's own monitor. Measuring the image area once removes the guess: the virtual display
+advertises those dimensions in its EDID, Windows derives DPI from them the same way it does for a real
+monitor, and interface elements come out at their true physical size.
+
+Measure the **image area**, not the device. On a letterboxed panel the two differ: a 16:10 stream on the
+8.0-inch inner panel of a Galaxy Z Fold8 Ultra occupies only about 7.01 inches of it. The height is
+derived from the width and the requested mode, so only the width is configured.
+
+Known-good widths, as a starting point — this is an ordinary list, so add your own device by measuring
+its image area:
+
+| Client | Mode | Image area (mm) | Width to configure | Density |
+| --- | --- | --- | --- | --- |
+| Alienware m16 R2 | 2560x1600 | 344.68 x 215.42 | `345` | 188.65 PPI |
+| Galaxy Z Fold8 Ultra (inner panel, landscape) | 2504x2256 | 150.97 x 136.01 | `151` | 421.3 PPI |
+
+`dd_virtual_display_scale` still wins when set to an explicit percentage, and `0` (preserve Windows'
+choice) still leaves the Windows DPI setting alone. The measured width only replaces the automatic
+recommendation.
+
 ### dd_virtual_display_scale
 
 Sets the virtual-display scale override. Leave it unset or at the automatic setting to use the recommended scale for the requested display mode.

src/config.cpp

@@ -939,6 +939,7 @@ namespace config {
       true,  // use_sunshine_virtual_display_driver
       false,  // activate_virtual_display
       -1,  // virtual_display_scale_percent
+      0,  // virtual_display_image_width_mm
       0,  // virtual_display_permanent_count
       false,  // virtual_display_permanent_count_configured
       {},  // snapshot_exclude_devices
@@ -1901,6 +1902,18 @@ namespace config {
                            << "%; use -1 (recommended), 0, 100, 125, 150, 175, 200, 225, 250, 300, 350, 400, 450, or 500.";
       }
     }
+    {
+      int value = video.dd.virtual_display_image_width_mm;
+      int_f(vars, "dd_virtual_display_image_width_mm", value);
+      // Mirrors VDISPLAY::kMinImageWidthMillimeters/kMaxImageWidthMillimeters, which live in a
+      // Windows-only header this platform-neutral parser cannot include.
+      if (value == 0 || (value >= 10 && value <= 2000)) {
+        video.dd.virtual_display_image_width_mm = value;
+      } else {
+        BOOST_LOG(warning) << "Ignoring out-of-range virtual display image width " << value
+                           << " mm; use 0 to disable, or 10-2000.";
+      }
+    }
     bool_f(vars, "vulkan_hdr_layer", video.dd.vulkan_hdr_layer);
     {
       auto it = vars.find("dd_virtual_display_permanent_count");
@@ -2583,6 +2596,7 @@ namespace config {
         "dd_use_sunshine_virtual_display_driver",
         "dd_activate_virtual_display",
         "dd_virtual_display_scale",
+        "dd_virtual_display_image_width_mm",
         "dd_virtual_display_permanent_count",
         "dd_mode_remapping",
         "dd_wa_dummy_plug_hdr10",
@@ -3087,6 +3101,7 @@ namespace config {
       const auto prev_dd_use_sunshine_virtual_display_driver = video.dd.use_sunshine_virtual_display_driver;
       const auto prev_dd_activate_virtual_display = video.dd.activate_virtual_display;
       const auto prev_dd_virtual_display_scale_percent = video.dd.virtual_display_scale_percent;
+      const auto prev_dd_virtual_display_image_width_mm = video.dd.virtual_display_image_width_mm;
       const auto prev_dd_virtual_display_permanent_count = video.dd.virtual_display_permanent_count;
       const auto prev_dd_virtual_display_permanent_count_configured = video.dd.virtual_display_permanent_count_configured;
       const auto prev_dd_snapshot_exclude_devices = video.dd.snapshot_exclude_devices;
@@ -3161,6 +3176,7 @@ namespace config {
                                      (prev_dd_use_sunshine_virtual_display_driver != video.dd.use_sunshine_virtual_display_driver) ||
                                      (prev_dd_activate_virtual_display != video.dd.activate_virtual_display) ||
                                      (prev_dd_virtual_display_scale_percent != video.dd.virtual_display_scale_percent) ||
+                                     (prev_dd_virtual_display_image_width_mm != video.dd.virtual_display_image_width_mm) ||
                                      (prev_dd_virtual_display_permanent_count != video.dd.virtual_display_permanent_count) ||
                                      (prev_dd_virtual_display_permanent_count_configured != video.dd.virtual_display_permanent_count_configured) ||
                                      (prev_dd_snapshot_exclude_devices != video.dd.snapshot_exclude_devices) ||

src/config.h

@@ -231,6 +231,7 @@ namespace config {
       bool use_sunshine_virtual_display_driver;  ///< Use the Vibepollo Display Driver instead of rollback drivers such as SudoVDA.
       bool activate_virtual_display;  ///< Auto-activate Sunshine virtual display when selected as the target output.
       int virtual_display_scale_percent;  ///< Windows scale for virtual displays (-1 is resolution-based; 0 preserves Windows' choice).
+      int virtual_display_image_width_mm;  ///< Width of the client's visible image area in millimetres (0 disables). Drives the synthetic EDID so Windows derives DPI from a real physical size.
       int virtual_display_permanent_count;  ///< Number of always-present Sunshine virtual displays to request when explicitly configured.
       bool virtual_display_permanent_count_configured;  ///< False preserves installs that predate this setting.
       std::vector<std::string> snapshot_exclude_devices;  ///< Device IDs to skip when saving display snapshots.

src/platform/windows/virtual_display.h

@@ -68,12 +68,40 @@ namespace VDISPLAY {
     std::uint32_t scale_percent
   );
 
-  // Resolve the configured virtual-display scale. -1 selects a resolution-based
-  // recommendation, 0 preserves Windows' existing choice, and positive values are exact.
+  // Physical size of the image area a virtual display advertises through its synthetic EDID.
+  struct virtual_display_physical_size_t {
+    std::uint32_t width_mm = 0;
+    std::uint32_t height_mm = 0;
+  };
+
+  // Lowest and highest client image widths we accept, in millimetres. The range spans a
+  // phone's inner panel up to a projected image; anything outside it is a typo, not a display.
+  inline constexpr int kMinImageWidthMillimeters = 10;
+  inline constexpr int kMaxImageWidthMillimeters = 2000;
+
+  // The DPI a 100% Windows scale factor is defined against.
+  inline constexpr double kWindowsReferenceDpi = 96.0;
+
+  // Resolve the image area a virtual display should advertise, from the measured width of the
+  // client's visible image and the mode being requested. Returns nullopt when no width is
+  // configured, leaving callers on the scale-derived EDID. Height follows the mode's pixel
+  // aspect: the streamed image fills the client's image area, so its pixels are square even
+  // when the client's panel is not the same shape as the image.
+  std::optional<virtual_display_physical_size_t> virtual_display_physical_size_mm(
+    int configured_image_width_mm,
+    std::uint32_t width,
+    std::uint32_t height
+  );
+
+  // Resolve the configured virtual-display scale. -1 selects a recommendation, 0 preserves
+  // Windows' existing choice, and positive values are exact. A measured client image width
+  // refines the recommendation: it describes the client's pixel density exactly, where the
+  // resolution-only heuristic can only guess at it.
   std::uint32_t effective_virtual_display_scale_percent(
     int configured_scale_percent,
     std::uint32_t width,
-    std::uint32_t height
+    std::uint32_t height,
+    int configured_image_width_mm = 0
   );
 
   // Read the MHC2 peak-luminance value from a Windows HDR calibration profile selection.

src/platform/windows/virtual_display_identity.cpp

@@ -12,6 +12,24 @@ namespace {
     100, 125, 150, 175, 200, 225, 250, 300, 350, 400, 450, 500
   };
 
+  // Windows only exposes the scales in kWindowsScalePercentages, so every derived scale has to
+  // land on one of them.
+  std::uint32_t nearest_windows_scale_percent(const double ideal_scale) {
+    const auto closest = std::ranges::min_element(
+      kWindowsScalePercentages,
+      [ideal_scale](const auto lhs, const auto rhs) {
+        return std::abs(static_cast<double>(lhs) - ideal_scale) <
+               std::abs(static_cast<double>(rhs) - ideal_scale);
+      }
+    );
+    return closest != kWindowsScalePercentages.end() ? *closest : 100u;
+  }
+
+  bool image_width_is_usable(const int image_width_mm) {
+    return image_width_mm >= VDISPLAY::kMinImageWidthMillimeters &&
+           image_width_mm <= VDISPLAY::kMaxImageWidthMillimeters;
+  }
+
   bool equals_ascii_ci(const std::string_view lhs, const std::string_view rhs) {
     return lhs.size() == rhs.size() &&
            std::ranges::equal(lhs, rhs, [](const char left, const char right) {
@@ -108,25 +126,47 @@ namespace VDISPLAY {
            starts_with_wide_ascii_ci(product_code, L"5");
   }
 
+  std::optional<virtual_display_physical_size_t> virtual_display_physical_size_mm(
+    const int configured_image_width_mm,
+    const std::uint32_t width,
+    const std::uint32_t height
+  ) {
+    if (!image_width_is_usable(configured_image_width_mm) || width == 0 || height == 0) {
+      return std::nullopt;
+    }
+
+    virtual_display_physical_size_t size {};
+    size.width_mm = static_cast<std::uint32_t>(configured_image_width_mm);
+    size.height_mm = static_cast<std::uint32_t>((std::max)(
+      1L,
+      std::lround(
+        static_cast<double>(configured_image_width_mm) *
+        static_cast<double>(height) / static_cast<double>(width)
+      )
+    ));
+    return size;
+  }
+
   std::uint32_t effective_virtual_display_scale_percent(
     const int configured_scale_percent,
     const std::uint32_t width,
-    const std::uint32_t height
+    const std::uint32_t height,
+    const int configured_image_width_mm
   ) {
     if (configured_scale_percent >= 0) {
       return static_cast<std::uint32_t>(configured_scale_percent);
     }
 
+    // A measured image width pins the client's real pixel density, so the scale follows from
+    // physics instead of from a guess keyed on resolution alone.
+    if (image_width_is_usable(configured_image_width_mm) && width > 0) {
+      const auto dots_per_inch =
+        static_cast<double>(width) * 25.4 / static_cast<double>(configured_image_width_mm);
+      return nearest_windows_scale_percent(dots_per_inch * 100.0 / VDISPLAY::kWindowsReferenceDpi);
+    }
+
     const auto short_edge = (std::min)(width, height);
-    const auto ideal_scale = static_cast<double>(short_edge) * 100.0 / 864.0;
-    const auto closest = std::ranges::min_element(
-      kWindowsScalePercentages,
-      [ideal_scale](const auto lhs, const auto rhs) {
-        return std::abs(static_cast<double>(lhs) - ideal_scale) <
-               std::abs(static_cast<double>(rhs) - ideal_scale);
-      }
-    );
-    return closest != kWindowsScalePercentages.end() ? *closest : 100u;
+    return nearest_windows_scale_percent(static_cast<double>(short_edge) * 100.0 / 864.0);
   }
 
   std::uint64_t client_uuid_to_virtual_display_id(const GUID &client_guid) {

src/platform/windows/virtual_display_sudovda.cpp

@@ -4441,7 +4441,8 @@ namespace VDISPLAY_SUDOVDA {
         const auto scale_percent = VDISPLAY::effective_virtual_display_scale_percent(
           config::video.dd.virtual_display_scale_percent,
           width,
-          height
+          height,
+          config::video.dd.virtual_display_image_width_mm
         );
         if (scale_percent > 0) {
           const bool has_virtual_target_identity =

src/platform/windows/virtual_display_sunshine.cpp

@@ -6560,9 +6560,16 @@ namespace VDISPLAY_SUNSHINE {
       }
       const auto dpi_settings_prefix = virtual_display_dpi_settings_prefix(display_id);
       const auto configured_scale = config::video.dd.virtual_display_scale_percent;
+      const auto configured_image_width_mm = config::video.dd.virtual_display_image_width_mm;
       const auto effective_scale = VDISPLAY::effective_virtual_display_scale_percent(
         configured_scale,
         width,
+        height,
+        configured_image_width_mm
+      );
+      const auto measured_image_size = VDISPLAY::virtual_display_physical_size_mm(
+        configured_image_width_mm,
+        width,
         height
       );
       const auto dpi_snapshot = configured_scale == 0 ?
@@ -6574,8 +6581,22 @@ namespace VDISPLAY_SUNSHINE {
       create_request.display_id = display_id;
       create_request.width = width;
       create_request.height = height;
-      if (effective_scale > 0) {
-        const auto dpi = 96.0 * static_cast<double>(effective_scale) / 100.0;
+      if (measured_image_size) {
+        // A measured image area is reported verbatim. Windows derives DPI from the EDID, so
+        // handing it the client's real dimensions makes on-screen elements come out at their
+        // true physical size instead of a size implied by a picked scale.
+        create_request.physical_width_mm = std::clamp(
+          measured_image_size->width_mm,
+          sunshine_driver::kMinPhysicalSizeMillimeters,
+          sunshine_driver::kMaxPhysicalSizeMillimeters
+        );
+        create_request.physical_height_mm = std::clamp(
+          measured_image_size->height_mm,
+          sunshine_driver::kMinPhysicalSizeMillimeters,
+          sunshine_driver::kMaxPhysicalSizeMillimeters
+        );
+      } else if (effective_scale > 0) {
+        const auto dpi = VDISPLAY::kWindowsReferenceDpi * static_cast<double>(effective_scale) / 100.0;
         create_request.physical_width_mm = std::clamp(
           static_cast<std::uint32_t>(std::lround(static_cast<double>(width) * 25.4 / dpi)),
           sunshine_driver::kMinPhysicalSizeMillimeters,
@@ -6600,7 +6621,9 @@ namespace VDISPLAY_SUNSHINE {
                        << ", HDR peak=" << create_request.hdr_max_luminance_nits << " nits"
                        << ", scale=" << effective_scale << "%"
                        << ", physical=" << create_request.physical_width_mm << 'x'
-                       << create_request.physical_height_mm << " mm).";
+                       << create_request.physical_height_mm << " mm"
+                       << ", physical source=" << (measured_image_size ? "measured client image" : "scale")
+                       << ").";
       sunshine_driver::ControlResult<sunshine_driver::CreateTemporaryDisplayResult> create_result;
       if (reclaimed_for_reuse) {
         // Ownership is already established in-place. Enter the existing-display
@@ -7215,7 +7238,8 @@ namespace VDISPLAY_SUNSHINE {
         const auto scale_percent = VDISPLAY::effective_virtual_display_scale_percent(
           config::video.dd.virtual_display_scale_percent,
           width,
-          height
+          height,
+          config::video.dd.virtual_display_image_width_mm
         );
         if (scale_percent > 0) {
 

src_assets/common/assets/web/components/settings/SettingsOverrideEditor.vue

@@ -159,6 +159,7 @@ const virtualDisplayOnlyKeys = new Set([
   'virtual_display_mode',
   'virtual_display_layout',
   'dd_virtual_display_scale',
+  'dd_virtual_display_image_width_mm',
   'dd_activate_virtual_display',
   'dd_virtual_display_permanent_count',
   'dd_paused_virtual_display_timeout_secs',

src_assets/common/assets/web/configs/settingsSchema.ts

@@ -87,6 +87,7 @@ export const clientOverrideableKeys = new Set([
   'dd_use_sunshine_virtual_display_driver',
   'dd_activate_virtual_display',
   'dd_virtual_display_scale',
+  'dd_virtual_display_image_width_mm',
   'dd_virtual_display_permanent_count',
   'dd_mode_remapping',
   'dd_wa_dummy_plug_hdr10',
@@ -353,6 +354,14 @@ const virtualDisplayCustomizationFields = (): SettingsField[] => [
     descriptionKey: 'ui.settings.fields.dd_virtual_display_scale.description',
     visibleWhen: { key: 'virtual_display_mode', notEquals: 'disabled' },
   }),
+  number('dd_virtual_display_image_width_mm', {
+    labelKey: 'ui.settings.fields.dd_virtual_display_image_width_mm.label',
+    descriptionKey: 'ui.settings.fields.dd_virtual_display_image_width_mm.description',
+    min: 0,
+    max: 2000,
+    step: 1,
+    visibleWhen: { key: 'virtual_display_mode', notEquals: 'disabled' },
+  }),
 ];
 
 const everydayPacingFields = (): SettingsField[] => [
@@ -796,6 +805,7 @@ export const settingsDefaults: Record<string, unknown> = {
   virtual_display_mode: 'per_client',
   virtual_display_layout: 'exclusive',
   dd_virtual_display_scale: -1,
+  dd_virtual_display_image_width_mm: 0,
   frame_limiter_enable: false,
   frame_limiter_provider: 'auto',
   frame_limiter_fps_limit: 0,

src_assets/common/assets/web/public/assets/locale/ui/en.json

@@ -1362,6 +1362,10 @@
           "description": "Keep up to four virtual monitors outside streams. 0 creates them only when needed.",
           "label": "Always-available virtual displays"
         },
+        "dd_virtual_display_image_width_mm": {
+          "description": "Width of the image area your client actually displays, in millimetres. Windows reads it from the virtual display's EDID and derives DPI from it, so buttons and the cursor match the physical size they have on the host monitor. Measure the image area, not the device: a letterboxed stream is smaller than the panel. 0 disables it. Examples: 345 for an Alienware m16 R2 at 2560x1600, 151 for a Galaxy Z Fold8 Ultra inner panel at 2504x2256.",
+          "label": "Client image width (mm)"
+        },
         "dd_virtual_display_scale": {
           "description": "Adjust interface size without changing the resolution requested by the client.",
           "label": "Windows scaling"