<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<!-- highdpi.qdoc -->
<title>High DPI Displays | Qt 5.9</title>
<link rel="stylesheet" type="text/css" href="style/offline-simple.css" />
<script type="text/javascript">
document.getElementsByTagName("link").item(0).setAttribute("href", "style/offline.css");
// loading style sheet breaks anchors that were jumped to before
// so force jumping to anchor again
setTimeout(function() {
var anchor = location.hash;
// need to jump to different anchor first (e.g. none)
location.hash = "#";
setTimeout(function() {
location.hash = anchor;
}, 0);
}, 0);
</script>
</head>
<body>
<div class="header" id="qtdocheader">
<div class="main">
<div class="main-rounded">
<div class="navigationbar">
<table><tr>
<td ><a href="index.html">Qt 5.9</a></td><td >High DPI Displays</td></tr></table><table class="buildversion"><tr>
<td id="buildversion" width="100%" align="right">Qt 5.9.4 Reference Documentation</td>
</tr></table>
</div>
</div>
<div class="content">
<div class="line">
<div class="content mainContent">
<div class="sidebar">
<div class="toc">
<h3><a name="toc">Contents</a></h3>
<ul>
<li class="level1"><a href="#high-dpi-displays">High DPI Displays</a></li>
<li class="level2"><a href="#issues-with-high-dpi">Issues with High DPI</a></li>
<li class="level2"><a href="#qt-high-dpi-support-overview">Qt High DPI Support Overview</a></li>
<li class="level2"><a href="#operating-system-support">Operating System Support</a></li>
<li class="level2"><a href="#high-dpi-support-in-qt">High DPI Support in Qt</a></li>
<li class="level2"><a href="#migration-of-existing-applications">Migration of Existing Applications</a></li>
<li class="level2"><a href="#glossary-of-high-dpi-terms">Glossary Of High DPI Terms</a></li>
</ul>
</div>
<div class="sidebar-content" id="sidebar-content"></div></div>
<h1 class="title">High DPI Displays</h1>
<span class="subtitle"></span>
<!-- $$$highdpi.html-description -->
<div class="descr"> <a name="details"></a>
<a name="high-dpi-displays"></a>
<h2 id="high-dpi-displays">High DPI Displays</h2>
<p>High DPI Displays are displays with increased pixel density compared to standard DPI displays.</p>
<p>This pixel density is measured in Dots per Inch (DPI) or Pixels Per Inch (PPI), and is determined by the number of display pixels and physical size. This means that the number of pixels alone is not enough to determine if a display falls into the high-DPI category.</p>
<p>A 4K monitor has a fixed number of pixels (~8M), however the DPI varies between 185 (23 inch) and 110 (40 inch). The former is around 2x standard 96 DPI desktop resolution, while the latter is barely over it.</p>
<a name="issues-with-high-dpi"></a>
<h3 >Issues with High DPI</h3>
<p>High DPI Displays cause a number of issues for existing applications:</p>
<ul>
<li>Applications using UI designs with fixed coordinates look small. The combination of font size specification in points and other sizes in pixels is particularly problematic since points are independent of the monitor resolution. For example, a frame of 40x20 pixels around the text "hello" using a 12pt font looks correct on low resolution monitors, but the frame will be too small on high DPI monitors, causing the text to be clipped.</li>
<li>Applications must adapt to situations where users have multiple displays with varying resolution. For example, they might use a 4K monitor for the document window of an image editor and a low resolution monitor for the tool box.</li>
</ul>
<p>The traditional approach to supporting high DPI has been one where Qt scaled fonts automatically, and then provided a DPI value that application code could use to scale the rest of the UI.</p>
<a name="qt-high-dpi-support-overview"></a>
<h3 >Qt High DPI Support Overview</h3>
<p>Qt supports a high DPI mode where the main coordinate system is virtualized and made independent of the display pixel density. This mode is implemented by some operating systems (macOS, iOS). In addition, Qt contains an implementation which may be used where operating system support is missing.</p>
<p>Geometry is now specified in device independent pixels. This includes widget and item geometry, event geometry, desktop, window and screen geometry, and animation velocities. Rendered output is in device pixels, which corresponds to the display resolution. The ratio between the device independent and device pixel coordinate systems is the devicePixelRatio.</p>
<p>Applications mostly work with device independent pixels. Notable exceptions are OpenGL and code that works with raster graphics.</p>
<a name="operating-system-support"></a>
<h3 >Operating System Support</h3>
<p>The operating systems supported by Qt offer the following support for high DPI displays:</p>
<a name="macos-and-ios"></a>
<h4 >macOS and iOS</h4>
<p>The Apple platforms implement scaling and coordinate system virtualization in the in the operating system. Normally, no special configuration is required.</p>
<p><b>Note: </b>On macOS, high-DPI support is enabled by settings in the Info.plist file. Make sure they are present.</p><pre class="cpp">
<span class="operator"><</span>key<span class="operator">></span>NSPrincipalClass<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span>NSApplication<span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
<span class="operator"><</span>key<span class="operator">></span>NSHighResolutionCapable<span class="operator"><</span><span class="operator">/</span>key<span class="operator">></span>
<span class="operator"><</span>string<span class="operator">></span>True<span class="operator"><</span><span class="operator">/</span>string<span class="operator">></span>
</pre>
<p>Never versions of qmake will generate Info.plist's with the NSPrincipalClass key, which is sufficient since NSHighResolutionCapable is true by default.</p>
<p><b>Note: </b>macOS and iOS may apply further virtualization such that device pixels do not correspond 1:1 to display pixels. This happens on the iPhone 6+ and on macOS configured with 'display scaling' enabled.</p><a name="microsoft-windows"></a>
<h4 >Microsoft Windows</h4>
<a name="scaling"></a>
<h5 >Scaling</h5>
<p>The user can choose a scaling factor from the control panel or via context menu. This works by making the functions for querying the system metrics return different values for standard font sizes, sizes of window borders, and so on. It does not perform any actual scaling.</p>
<a name="dpi-awareness"></a>
<h5 >DPI Awareness</h5>
<p>An application on Windows can assume one of the following levels of "DPI Awareness":</p>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >DPI Awareness Level</th><th >Meaning</th></tr></thead>
<tr valign="top" class="odd"><td >DPI Unaware</td><td >This level has been introduced in Windows Vista. Windows will pretend to the application that it is running on a standard display of 96 DPI of 1920x1080 and scale the application accordingly. It is intended to accommodate older applications designed for low DPI displays. Some artifacts may result from this type of scaling.</td></tr>
<tr valign="top" class="even"><td >System-DPI Aware</td><td >This level has been introduced in Windows Vista. It differs from <i>Per-Monitor DPI Aware</i> only when multiple monitors are connected. Windows will calculate a scaling suitable for all connected monitors.</td></tr>
<tr valign="top" class="odd"><td >Per-Monitor DPI Aware</td><td >This level has been introduced in Windows 8.1. Windows does not perform any scaling at all.</td></tr>
</table></div>
<p>Qt applications by default are <i>Per-Monitor DPI Aware</i> on Windows 8.1 or <i>System-DPI Aware</i> on older versions of Windows. As of Qt 5.4, the level can be specified by passing a parameter to the platform plugin (see <a href="qt-conf.html">Using qt.conf</a>):</p>
<pre class="cpp">
<span class="operator"><</span>application<span class="operator">></span> <span class="operator">-</span>platform windows:dpiawareness<span class="operator">=</span><span class="number">0</span><span class="operator">,</span><span class="number">1</span><span class="operator">,</span><span class="number">2</span>
</pre>
<a name="high-dpi-support-in-qt"></a>
<h3 >High DPI Support in Qt</h3>
<ul>
<li>Ability to provide pixmaps or artwork for high resolution: see Drawing High Resolution Versions of Pixmaps and Images.</li>
<li>Qt 5.6 supports cross-platform high-DPI scaling for legacy applications, similar to the scaling done natively by macOS. This allows applications written for low-DPI screens to run unchanged on high-DPI devices. This feature is opt-in, and can be enabled by the following environment variables:<ul>
<li><code>QT_AUTO_SCREEN_SCALE_FACTOR</code> [boolean] enables automatic scaling, based on the pixel density of the monitor. This will not change the size of point sized fonts, since point is a physical unit of measure. Multiple screens may get different scale factors.</li>
<li><code>QT_SCALE_FACTOR</code> [numeric] defines a global scale factor for the whole application, including point sized fonts.</li>
<li><code>QT_SCREEN_SCALE_FACTORS</code> [list] specifies scale factors for each screen. This will not change the size of point sized fonts. This environment variable is mainly useful for debugging, or to work around monitors with wrong <a href="https://en.wikipedia.org/wiki/Extended_Display_Identification_Data">EDID information</a>(Extended Display Identification Data).<p>The format can be either a semicolon-separated list of scale factors in the same order as QGuiApplication::screens(), or a semicolon-separated list of <code>name=value</code> pairs, where <code>name</code> is the same as QScreen::name().</p>
</li>
</ul>
<p>While the macOS style fully supports high-DPI, the Windows desktop style currently has some limitations with certain scale factors. In these cases, consider using the Fusion style instead, which aims to support high-DPI in all cases.</p>
<p><b>Note: </b>Non-integer scale factors may cause significant scaling/painting artifacts.</p></li>
<li>The application attribute <code>Qt::AA_EnableHighDpiScaling</code>, introduced in Qt 5.6, enables automatic scaling based on the pixel density of the monitor.</li>
<li>The application attribute <code>Qt::AA_DisableHighDpiScaling</code>, introduced in Qt 5.6, turns off all scaling. This is intended for applications that need to use actual window system coordinates, regardless of environment variables. This attribute takes priority over Qt::AA_EnableHighDpiScaling.</li>
<li>An experimental implementation of high-DPI scaling was introduced in Qt 5.4. It was enabled by the environment variable <code>QT_DEVICE_PIXEL_RATIO</code>, which could be set to a numerical scale factor or <code>"auto"</code>. This variable is deprecated in Qt 5.6.</li>
</ul>
<a name="migration-of-existing-applications"></a>
<h3 >Migration of Existing Applications</h3>
<p>In order to get an application designed for low DPI values running on a high resolution monitors quickly, consider one of the scaling options (let the application run as <i>DPI Unaware</i> on Windows or set the environment variable <code>QT_AUTO_SCREEN_SCALE_FACTOR</code> to <code>"1"</code>. These options may incur some scaling or painting artifacts, though.</p>
<p>In the longer term, the application should be adapted to run unmodified:</p>
<ul>
<li>Always use the qreal versions of the QPainter drawing API.</li>
<li>Size windows and dialogs in relation to the screen size.</li>
<li>Replace hard-coded sizes in layouts and drawing code by values calculated from font metrics or screen size.</li>
</ul>
<a name="glossary-of-high-dpi-terms"></a>
<h3 >Glossary Of High DPI Terms</h3>
<div class="table"><table class="generic">
<thead><tr class="qt-style"><th >Term</th><th >Definition</th></tr></thead>
<tr valign="top" class="odd"><td >Device Independent Pixels</td><td >Pixels used by application (user space), subject to scaling by the operating system or Qt.</td></tr>
<tr valign="top" class="even"><td >Device Pixels</td><td >Pixels of the display device.</td></tr>
<tr valign="top" class="odd"><td >Device Pixel Ratio</td><td >Scale factor applied by the operating system or Qt.</td></tr>
<tr valign="top" class="even"><td >Logical DPI</td><td >Resolution used for converting font sizes defined in points to font sizes in pixels. Typically one of the standard values 96, 128, .. 192.</td></tr>
<tr valign="top" class="odd"><td >Physical DPI</td><td >Physical resolution obtained by dividing the size of the monitor by the number of pixels.</td></tr>
<tr valign="top" class="even"><td >Retina Display</td><td >See <a href="http://en.wikipedia.org/wiki/Retina_Display">Wikipedia on Retina Displays</a></td></tr>
<tr valign="top" class="odd"><td >User Space</td><td >The coordinate space the application uses (Device Independent Pixels).</td></tr>
</table></div>
</div>
<!-- @@@highdpi.html -->
</div>
</div>
</div>
</div>
</div>
<div class="footer">
<p>
<acronym title="Copyright">©</acronym> 2017 The Qt Company Ltd.
Documentation contributions included herein are the copyrights of
their respective owners.<br> The documentation provided herein is licensed under the terms of the <a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License version 1.3</a> as published by the Free Software Foundation.<br> Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property
of their respective owners. </p>
</div>
</body>
</html>
