Hohe DPI

High-DPI-Displays - auch Retina-Displays genannt - sind Displays mit einer hohen 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 ausblendet. Qt berücksichtigt automatisch die Bildschirmauflösung bei der Verwendung von APIs auf höherer Ebene, wie z.B. Qt Widgets und Qt Quickund Anwendungen müssen nur hochauflösende Assets wie Bilder und Icons bereitstellen. Änderungen in den Benutzereinstellungen der Plattform werden automatisch übernommen.

Die Grafikdarstellung auf niedrigerer Ebene (z. B. OpenGL-Code) muss sich der hohen DPI-Auflösung bewusst sein, kann aber plattformübergreifende Qt-APIs verwenden, um die Bildschirmauflösungen der Plattform zu erkennen.

Konzeptionelles 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 Standarddichte (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 übergeordneten Qt GUI, Widgets und Quick APIs, einschließlich Widget- und Elementgeometrie, Ereignisgeometrie, Desktop-, Fenster- und Bildschirmgeometrie sowie Animationsgeschwindigkeiten.

Zeichnen

Qt nutzt automatisch die höhere Dichte eines Displays mit hohem DPI-Wert, wenn Zeichen-APIs wie QPainter verwendet werden oder wenn grafische Primitive oder Text in Qt Quick gerendert werden.

Infolgedessen kann die Anwendung in einem einzigen, einheitlichen Koordinatensystem arbeiten, ohne dass die möglichen Anzeigedichten berücksichtigt werden müssen, auf denen die Anwendung ausgeführt wird.

Bei der Verwendung von Zeichnungs-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, wenn es zwischen Anzeigen verschoben wird), als auch pro Anzeige, als QScreen::devicePixelRatio(), möglich.

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

Bild-Assets

Um die Vorteile der höheren Pixeldichte von Displays mit hoher DPI-Dichte zu nutzen, sollte die Anwendung auch High-DPI-Versionen von statischen Bildelementen 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 wird die Geometrie von QScreen dem nativen Bildschirmlayout entsprechen. 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 eine Position unmittelbar neben und außerhalb eines Bildschirms eine gültige Position auf dem benachbarten Bildschirm ist. 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 Anzeigehardware 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 dieselben DPI- oder Skalierungsfaktorwerte 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 - zum Beispiel 96 bei 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 der Anzeige 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 entspricht nicht genau dem, was Qt benötigt, was die DPI-Konfiguration unter X11 komplizierter machen kann als auf anderen Plattformen.

Desktop-Umgebungen wie Ubuntu und Kubuntu 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, dann beschreibt dieser Abschnitt, welche X11-Einstellungen Qt liest.

Einige X11-Konfigurationsabläufe beinhalten das Überschreiben der gemeldeten physischen Größe des Bildschirms, damit die DPI-Berechnungen einen bestimmten DPI-Wert ergeben. Qt unterstützt diese Arbeitsabläufe, 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 den physikalischen DPI-Wert 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 mehrere DPI-Bewusstseinsstufen, die Anwendungen einstellen können, um hohe DPI-Funktionen zu nutzen. Qt 6 ist standardmäßig Per-Monitor DPI Aware V2. Wenn Sie Code einbinden, der von einem einzigen globalen DPI-Wert ausgeht, sollten Sie einen anderen 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 festzulegen.

QT_SCALE_FACTOR=2 ./myapp

Dies skaliert die gesamte Anwendungsgeometrie (einschließlich des Gerätepixelverhältnisses) um den 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 rounding policy nicht beeinflusst.

Das effektive Gerätepixelverhältnis, wie es von QWindow::devicePixelRatio() zurückgegeben wird, ist ein Produkt aus dem eingestellten Skalierungsfaktor und dem nativen Gerätepixelverhältnis. 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 Fenster befindet, wie von QPlatformScreen::logicalDpi() und QPlatformScreen::devicePixelRatio() gemeldet.

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, die Sie unter qtbase/tests/manual/highdpi/dprgadget finden können.

Referenz der Umgebungsvariablen

Dieser Abschnitt listet Umgebungsvariablen auf, die von Qt erkannt werden und sich auf hohe DPI-Werte beziehen. 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 es wird nicht empfohlen, 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 sind alle in geräteunabhängigen Pixeln. 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.