Hoher DPI

High-DPI-Displays - auch Retina-Displays genannt - sind Displays mit hoher Auflösung (Pixel) im Verhältnis zu ihrer physischen Größe (mm), was zu einer hohen Pixeldichte oder einer hohen Anzahl von Punkten pro Zoll (DPI) führt. Die höhere Auflösung wird verwendet, um detailliertere Inhalte auf dem Bildschirm darzustellen (glatterer Text, detailliertere Symbole), anstatt mehr Inhalt (mehr Fenster, größere Fenstergrößen).

Qt unterstützt hohe DPI-Displays auf allen Plattformen und bietet eine einheitliche API, die alle Plattformunterschiede überdeckt. Qt berücksichtigt die Bildschirmauflösung automatisch, wenn APIs auf höherer Ebene wie Qt Widgets und Qt Quick verwendet werden, und Anwendungen müssen nur hochauflösende Assets wie Bilder und Icons bereitstellen. Änderungen in den Benutzereinstellungen der Plattform werden automatisch übernommen.

Grafikzeichnungen auf niedrigerer Ebene (wie z. B. OpenGL-Code) müssen sich der hohen DPI-Auflösung bewusst sein, können aber plattformübergreifende Qt-APIs verwenden, um sich über die Bildschirmauflösungen der Plattform zu informieren.

Konzeptuelles Modell

Qt verwendet ein Modell, bei dem das Koordinatensystem der Anwendung unabhängig von der Auflösung des Anzeigegeräts ist. Die Anwendung arbeitet in geräteunabhängigen Pixeln, die dann über einen Skalierungsfaktor, dem sogenannten Gerätepixelverhältnis, auf die physischen Pixel des Displays abgebildet werden. Der Skalierungsfaktor wird als Gleitkommazahl ausgedrückt, z. B. 1.0 oder 2.0, oder informell als 1x und 2x.

Wenn Sie z. B. ein QWindow oder QWidget erstellen und seine Größe auf 200x200 einstellen, deckt es 200x200 Anzeigepixel auf einem Display mit normaler Dichte (mit einem Gerätepixelverhältnis von 1,0) ab, aber 400x400 Pixel auf einem Display mit hoher Dichte (mit einem Gerätepixelverhältnis von 2,0).

Dieses Modell gilt für die meisten Einheiten in höheren Ebenen Qt GUI, Widgets und Quick APIs, einschließlich Widget- und Elementgeometrie, Ereignisgeometrie, Desktop-, Fenster- und Bildschirmgeometrie sowie Animationsgeschwindigkeiten.

Zeichnen

Qt nutzt automatisch die erhöhte Dichte eines High-DPI-Displays, wenn Zeichen-APIs wie QPainter verwendet werden, oder wenn grafische Primitive oder Text in Qt Quick gerendert werden.

Als Ergebnis kann die Anwendung in einem einzigen, einheitlichen Koordinatensystem arbeiten, ohne dass die möglichen Anzeigedichten berücksichtigt werden müssen, auf denen die Anwendung läuft.

Bei der Verwendung von Zeichen-APIs auf niedrigerer Ebene, z. B. OpenGL, muss die Anwendung jedoch das Pixelverhältnis des Bildschirms berücksichtigen. Dies ist sowohl pro Fenster als QWindow::devicePixelRatio() (Verfolgung des Gerätepixelverhältnisses des Fensters beim Verschieben zwischen Anzeigen) als auch pro Anzeige als QScreen::devicePixelRatio() möglich.

Bildpuffer wie QImage und QPixmap stellen die rohen Pixel dar und arbeiten daher nicht mit dem oben beschriebenen geräteunabhängigen Koordinatensystem. Ein QImage der Größe 400x400 mit einem Gerätepixelverhältnis von 2,0 passt auf einem Display mit hoher Dichte (2x) auf ein 200x200 QWindow oder wird während des Zeichnens automatisch auf 200x200 verkleinert, wenn ein Display mit normaler Dichte (1x) verwendet wird. Siehe Drawing High Resolution Versions of Pixmaps and Images für weitere Details.

Bild-Assets

Um die Vorteile der höheren Pixeldichte von Bildschirmen mit hoher DPI-Dichte zu nutzen, sollte die Anwendung auch High-DPI-Versionen von statischen Bild-Assets enthalten. Dies wird erreicht, indem man eine spezielle Namenskonvention für die High-Density-Assets verwendet, z. B. logo@2x.png, und sowohl das Bild mit normaler Dichte als auch das Bild mit hoher Dichte in eine QIcon lädt. Qt wählt zur Laufzeit automatisch die beste Darstellung für das Zieldisplay. Siehe High DPI Icons für weitere Details.

Geräteunabhängige Bildschirmgeometrie

Qt-Anwendungen arbeiten im Allgemeinen in geräteunabhängigen Pixeln. Dies schließt Fenster- und Bildschirmgeometrien ein, die der Anwendung gemeldet werden.

Das bedeutet, dass QScreen::geometry() möglicherweise nicht die physische Pixelanzahl des Bildschirms oder die vom Betriebssystem gemeldete Pixelgröße zurückgibt. Dies hat Auswirkungen auf die Geometrie des virtuellen Desktops:

Moderne Desktop-Betriebssysteme erstellen in der Regel ein gemeinsames Koordinatensystem für alle angeschlossenen Bildschirme und ermöglichen es dem Benutzer, die Bildschirme so zu positionieren, dass sie mit der physischen Bildschirmkonfiguration übereinstimmen, normalerweise über einen Konfigurationsdialog. Wenn diese Positionierung in einem Koordinatensystem erfolgt, das den geräteunabhängigen Pixeln von Qt entspricht (wie unter macOS), dann entspricht die Geometrie von QScreen dem nativen Bildschirmlayout. Wenn die Positionierung in physischen Pixeln des Bildschirms erfolgt (wie unter Windows), dann kann die Behandlung der Bildschirmgeometrie durch Qt zu "Lücken" in der Geometrie des virtuellen Desktops führen, die von keinem Bildschirm genutzt werden.

Genauer gesagt skaliert Qt die Bildschirmgröße (was bei positiven Skalierungsfaktoren zu einem "kleineren" Bildschirm führt), ändert aber nicht die Position des Bildschirms. Dies führt zu einer virtuellen Desktop-Geometrie vom Typ "Inseln von Bildschirmen".

Der Anwendungscode sollte nicht davon ausgehen, dass Positionen, die unmittelbar an einen Bildschirm angrenzen und sich außerhalb eines Bildschirms befinden, eine gültige Position auf dem benachbarten Bildschirm darstellen. Holen Sie sich stattdessen die Bildschirmliste mit QGuiApplication::screens() und verwenden Sie diese Liste, um auf die verfügbare Bildschirmgeometrie zu schließen.

Konfigurieren von

Als Endbenutzer möchten Sie vielleicht die DPI- oder Skalierungseinstellungen an die Bildschirmhardware anpassen oder den Betrachtungsabstand und persönliche Vorlieben berücksichtigen. Diese Anpassungen sollten mit den nativen Anzeigeeinstellungen der Plattform vorgenommen werden, so dass alle Anwendungen die gleichen DPI- oder Skalierungswerte verwenden. Qt bietet dem Endbenutzer keine Möglichkeit, das Verhalten der Qt-High-DPI-Unterstützung zu konfigurieren.

Das Betriebssystem kann den Skalierungsfaktor entweder als Faktor (1.5), als Prozentsatz (150%) oder als Punkte pro Zoll (144 DPI) darstellen. Qt übersetzt diese Werte in das Pixelverhältnis des Geräts, das von der Anwendung gesehen wird. Im letzteren Fall geht Qt von einem "Basis"-DPI aus - z.B. 96 auf X11 - und berechnet das resultierende Gerätepixelverhältnis entsprechend.

Ganzzahlige Skalierungsfaktoren (z.B. 1.0 oder 2.0) werden für beste Ergebnisse bevorzugt. Das "Runden" des Skalierungsfaktors auf 25%-Schritte kann ebenfalls zu guten Ergebnissen führen. Die Einstellung des Skalierungsfaktors oder des DPI-Wertes auf den exakten physischen DPI-Wert des Bildschirms führt aufgrund der damit verbundenen Bruchteilsskalierung möglicherweise nicht zu guten visuellen Ergebnissen. Wenn die Anwendung in diesem Szenario unter visuellen Artefakten leidet, kann sie QGuiApplication::setHighDpiScaleFactorRoundingPolicy() verwenden, um die sichtbaren Skalierungsfaktoren zu begrenzen.

Plattform-Details

In der folgenden Tabelle wird beschrieben, wie High-DPI auf verschiedenen Plattformen konfiguriert werden kann.

X11 konfigurieren

Die erforderliche Konfigurationseingabe für Qt ist die logische DPI pro Bildschirm. Derzeit bietet X11 entweder globale logische DPI oder physische DPI pro Bildschirm. Beides ist nicht genau das, was Qt braucht, was die DPI-Konfiguration unter X11 komplizierter machen kann als auf anderen Plattformen.

Desktop-Umgebungen wie Ubuntu und Kubntu implementieren Workarounds für das Fehlen der logischen DPI und bieten leicht konfigurierbare High-DPI-Unterstützung. Wenn Sie stattdessen die X11-DPI-Einstellungen manuell konfigurieren möchten, beschreibt dieser Abschnitt, welche X11-Einstellungen Qt liest.

Einige X11-Konfigurationsabläufe beinhalten das Überschreiben der gemeldeten physikalischen Größe des Bildschirms, damit die DPI-Berechnung einen bestimmten DPI-Wert ergibt. Qt unterstützt diesen Arbeitsablauf, aber dies erfordert ein Opt-in, wie unten beschrieben.

Die genaue Konfigurationspriorität ist wie folgt, wobei Qt die erste verfügbare Option verwendet. Beachten Sie, dass das Verhalten von der verwendeten Qt-Version abhängt. Das Verhalten von Qt 5 setzt voraus, dass AA_EnableHighDpiScaling gesetzt wurde (dieses Flag wird bei Qt 6 nicht benötigt).

Die Überschreibung QT_USE_PHYSICAL_DPI

Setzen Sie QT_USE_PHYSICAL_DPI=1, damit Qt bedingungslos die physikalischen DPI-Werte von RandR verwendet; insbesondere werden die Felder mwidth und mheight der Struktur xcb_randr_screen_change_notify_event_t verwendet. Der DPI-Wert wird auf eine ganze Zahl gerundet.

Windows konfigurieren

Qt verwendet die Windows-Anzeigeskalierungseinstellungen automatisch; es sind keine spezifischen Einstellungen erforderlich. Wenn zum Beispiel ein Bildschirm für eine Skalierung von 175% konfiguriert ist, dann sehen Qt-Anwendungen auf diesem Bildschirm ein Pixelverhältnis von 1,75.

Windows definiert mehrereDPI-Wahrnehmungsstufen, die Anwendungen einstellen, um hohe DPI-Funktionen nutzen zu können. Qt 6 ist standardmäßig Per-Monitor DPI Aware V2. Wenn Sie Code einbinden, der von einem einzigen globalen DPI ausgeht, möchten Sie vielleicht ein anderes Awareness-Level einstellen. Dies kann durch Hinzufügen eines Eintrags in der qt.conf geschehen:

[Platforms]
WindowsArguments = dpiawareness=0,1,2

Testen

QT_SCALE_FACTOR

Setzen Sie die Umgebungsvariable QT_SCALE_FACTOR, um einen globalen Skalierungsfaktor für die Anwendung bereitzustellen.

QT_SCALE_FACTOR=2 ./myapp

Dies skaliert die gesamte Anwendungsgeometrie (einschließlich des Gerätepixelverhältnisses) mit dem angegebenen Faktor, was das Testen von High-DPI-Unterstützung unabhängig von der verfügbaren Hardware ermöglicht. Der eingestellte Skalierungsfaktor wird von Qt so verwendet, wie er ist, und wird von der rounding policy nicht beeinflusst.

Das effektive Pixelverhältnis des Geräts, wie es von QWindow::devicePixelRatio() zurückgegeben wird, ist ein Produkt aus dem eingestellten Skalierungsfaktor und dem nativen Pixelverhältnis des Geräts. Zum Beispiel führt das Setzen von QT_SCALE_FACTOR=2 auf einem 2x Wayland Display dazu, dass die Anwendung ein Gerätepixelverhältnis von 4 sieht.

DprGadget

Die Testanwendung DprGadget kann verwendet werden, um die native Konfiguration und die Reaktion von Qt darauf zu überprüfen:

DprGadget zeigt das Gerätepixelverhältnis des Fensters an, wie es von QWindow::devicePixelRatio() gemeldet wird. Zusätzlich zeigt es die native DPI und das Gerätepixelverhältnis des Bildschirms an, auf dem sich das Widow befindet, wie es von QPlatformScreen::logicalDpi() und QPlatformScreen::devicePixelRatio() gemeldet wird.

Die angezeigten Werte sollten bei Bildschirm- und DPI-Änderungen automatisch aktualisiert werden, und der Dialog sollte die gleiche Größe beibehalten. Falls nicht, könnte es ein Qt-Bug sein.

DprGradget ist ein Teil der manuellen Qt-Testsuite und kann unter qtbase/tests/manual/highdpi/dprgadget gefunden werden.

Referenz der Umgebungsvariablen

Dieser Abschnitt listet die von Qt erkannten Umgebungsvariablen für hohe DPI-Werte auf. In alphabetischer Reihenfolge:

• QT_ENABLE_HIGHDPI_SCALING Setzen Sie diese Variable auf 0, um die Skalierung für hohe Bildschirmauflösung zu deaktivieren; damit kehren Sie zum Standardverhalten von Qt 5 zurück. Beachten Sie, dass dies keinen Effekt auf Plattformen wie Wayland oder macOS hat - es deaktiviert keine native High-DPI-Unterstützung. Diese Variable ist nur für Testzwecke gedacht, und wir empfehlen nicht, sie dauerhaft zu setzen.
• QT_FONT_DPI Setzt einen globalen DPI-Wert. Dies ist eine alte Umgebungsvariable, die aus Gründen der Abwärtskompatibilität bereitgestellt wird.
• QT_SCALE_FACTOR Setzt einen globalen Skalierungsfaktor. Für Debugging- und Testzwecke.
• QT_SCALE_FACTOR_ROUNDING_POLICY Legt den Skalierungsfaktor rounding policy fest, der auf den aus dem Bildschirm-DPI berechneten Skalierungsfaktor angewendet wird. Unterstützte Werte sind
  • Round (Qt 5 Voreinstellung)
  • PassThrough (Qt 6 Voreinstellung)
• QT_SCREEN_SCALE_FACTORS Setzt eine Liste von Bildschirm-Skalierungsfaktoren. Die Liste kann in einem von zwei Formaten vorliegen; entweder eine durch Semikolon getrennte Liste von Skalierungsfaktoren ("1;1.5;2"), oder eine durch Semikolon getrennte Liste von screen=factor-Einträgen ("screenA=1;screenB=1.5;screenC=2"). Das Setzen dieser Umgebungsvariable wird nicht empfohlen, da sie Qt daran hindert, die DPI-Werte des Systems zu verwenden.
• QT_USE_PHYSICAL_DPI Bringt Qt dazu, physische DPI anstelle von logischen DPI zu verwenden. Die Verwendung der logischen DPI ist normalerweise die beste Option; diese Umgebungsvariable kann in Fällen gesetzt werden, in denen die logische DPI nicht verfügbar ist und die physikalische DPI als korrekt bekannt ist.

Koordinatensysteme Referenz

• Device Independent Pixels Dies ist das Hauptkoordinatensystem von Qt. Fenster-, Widget-, Quick-Item-, Ereignis- und Bildschirmgeometrie werden alle in geräteunabhängigen Pixeln dargestellt. Typischerweise hat ein geräteunabhängiges Pixel eine konstante visuelle Größe über alle Gerätetypen und Bildschirmdichten hinweg. Auch wenn dies eine Verallgemeinerung ist, hängt die genaue Größe von der Gerätekonfiguration ab.
• Gerätepixel Dieses Koordinatensystem wird für Rasterung und Low-Level-Grafikaufgaben verwendet, z. B. bei Verwendung der OpenGL-API. Das Gerätepixel-Koordinatensystem entspricht oft dem physikalischen Koordinatensystem des Bildschirms, aber das ist nicht garantiert. Zum Beispiel können sowohl macOS als auch Ubuntu je nach Display-Einstellungen eine zusätzliche Skalierung vornehmen.
• Native Pixel Dies ist das Koordinatensystem, das von der nativen API verwendet wird, z. B. Win32 oder Cocoa (macOS). Je nach Plattform und Bildschirmkonfiguration können native Pixel mit geräteunabhängigen oder Gerätepixeln gleichzusetzen sein.