1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
|
/****************************************************************************
**
** Copyright (C) 2016 The Qt Company Ltd.
** Contact: https://www.qt.io/licensing/
**
** This file is part of the documentation of the Qt Toolkit.
**
** $QT_BEGIN_LICENSE:FDL$
** Commercial License Usage
** Licensees holding valid commercial Qt licenses may use this file in
** accordance with the commercial license agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and The Qt Company. For licensing terms
** and conditions see https://www.qt.io/terms-conditions. For further
** information use the contact form at https://www.qt.io/contact-us.
**
** GNU Free Documentation License Usage
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of
** this file. Please review the following information to ensure
** the GNU Free Documentation License version 1.3 requirements
** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
** $QT_END_LICENSE$
**
****************************************************************************/
/*!
\page highdpi.html
\title High DPI Displays
\brief Concepts of High DPI Displays
\section1 High DPI Displays
High DPI Displays are displays with increased pixel density compared to standard
DPI displays.
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.
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.
\section2 Issues with High DPI
High DPI Displays cause a number of issues for existing applications:
\list
\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 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.
\endlist
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.
\section2 Qt High DPI Support Overview
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.
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.
Applications mostly work with device independent pixels. Notable exceptions are
OpenGL and code that works with raster graphics.
\section2 Operating System Support
The operating systems supported by Qt offer the following support for high DPI displays:
\section3 \macos and iOS
The Apple platforms implement scaling and coordinate system virtualization in the
in the operating system. Normally, no special configuration is required.
\note On \macos, high-DPI support is enabled by settings in the Info.plist file.
Make sure they are present.
\code
<key>NSPrincipalClass</key>
<string>NSApplication</string>
<key>NSHighResolutionCapable</key>
<string>True</string>
\endcode
Never versions of qmake will generate Info.plist's with the NSPrincipalClass key,
which is sufficient since NSHighResolutionCapable is true by default.
\note \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.
\section3 Microsoft Windows
\section4 Scaling
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.
\section4 DPI Awareness
An application on Windows can assume one of the following levels of "DPI Awareness":
\table
\header
\li DPI Awareness Level
\li Meaning
\row
\li DPI Unaware
\li 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.
\row
\li System-DPI Aware
\li This level has been introduced in Windows-Vista. It differs from
\e{Per-Monitor DPI Aware} only when multiple monitors are connected.
Windows will calculate a scaling suitable for all connected monitors.
\row
\li Per-Monitor DPI Aware
\li This level has been introduced in Windows 8.1. Windows does not perform
any scaling at all.
\endtable
Qt applications by default are \e{Per-Monitor DPI Aware} on Windows 8.1 or \e{System-DPI Aware}
on older versions of Windows. As of Qt 5.4, the level can be specified by passing a parameter
to the platform plugin (see \l{Using qt.conf}):
\code
<application> -platform windows:dpiawareness=0,1,2
\endcode
\section2 High DPI Support in Qt
\list
\li Ability to provide pixmaps or artwork for high resolution:
see \l{Drawing High Resolution Versions of Pixmaps and Images}.
\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:
\list
\li \c QT_AUTO_SCREEN_SCALE_FACTOR [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 \c QT_SCALE_FACTOR [numeric] defines a global scale
factor for the whole application, including point sized fonts.
\li \c QT_SCREEN_SCALE_FACTORS [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
\l {https://en.wikipedia.org/wiki/Extended_Display_Identification_Data}
{EDID information}(Extended Display Identification Data).
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 \c name=value pairs, where \c
name is the same as QScreen::name().
\endlist
It is recommended to use the \c Fusion style.
\note Non-integer scale factors may cause significant
scaling/painting artifacts.
\li The application attribute \c Qt::AA_EnableHighDpiScaling, introduced in Qt 5.6,
enables automatic scaling based on the pixel density of the monitor.
\li The application attribute \c Qt::AA_DisableHighDpiScaling, 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 An experimental implementation of high-DPI scaling was introduced in Qt 5.4.
It was enabled by the environment variable \c QT_DEVICE_PIXEL_RATIO, which
could be set to a numerical scale factor or \c "auto". This variable is
deprecated in Qt 5.6.
\endlist
\section2 Migration of Existing Applications
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 \e{DPI Unaware} on Windows or set the environment
variable \c QT_AUTO_SCREEN_SCALE_FACTOR to \c "1". These options may incur
some scaling or painting artifacts, though.
In the longer term, the application should be adapted to run unmodified:
\list
\li Always use the qreal versions of the QPainter drawing API.
\li Size windows and dialogs in relation to the screen size.
\li Replace hard-coded sizes in layouts and drawing code
by values calculated from font metrics or screen size.
\endlist
\section2 Glossary Of High DPI Terms
\table
\header
\li Term
\li Definition
\row
\li Device Independent Pixels
\li Pixels used by application (user space), subject to scaling by the operating
system or Qt.
\row
\li Device Pixels
\li Pixels of the display device.
\row
\li Device Pixel Ratio
\li Scale factor applied by the operating system or Qt.
\row
\li Logical DPI
\li Resolution used for converting font sizes defined in points to font sizes in pixels.
Typically one of the standard values 96, 128, .. 192.
\row
\li Physical DPI
\li Physical resolution obtained by dividing the size of the monitor by
the number of pixels.
\row
\li Retina Display
\li See \l{http://en.wikipedia.org/wiki/Retina_Display}{Wikipedia on Retina Displays}
\row
\li User Space
\li The coordinate space the application uses (Device Independent Pixels).
\endtable
*/
|
