Haute résolution

Les écrans à haute résolution (DPI), également appelés écrans rétina, sont des écrans à haute résolution (pixels) par rapport à leur taille physique (mm), ce qui se traduit par une densité de pixels élevée, ou un nombre élevé de points par pouce (DPI). L'augmentation de la résolution est utilisée pour fournir un contenu plus détaillé à l'écran (texte plus lisse, icônes plus détaillées), plutôt que plus de contenu (plus de fenêtres, tailles de fenêtres plus grandes).

Qt prend en charge les écrans à haute résolution sur toutes les plateformes et fournit une API unifiée qui fait abstraction des différences entre les plateformes. Qt tiendra automatiquement compte de la résolution de l'écran lors de l'utilisation d'API de plus haut niveau telles que Qt Widgets et Qt Quicket les applications n'ont plus qu'à fournir des ressources haute résolution, telles que des images et des icônes. Les changements dans les préférences des utilisateurs de la plate-forme sont automatiquement pris en compte.

Le dessin graphique de niveau inférieur (tel que le code OpenGL) doit tenir compte de la résolution DPI élevée, mais peut utiliser les API Qt multiplateformes pour connaître les résolutions d'affichage de la plateforme.

Modèle conceptuel

Qt utilise un modèle dans lequel le système de coordonnées de l'application est indépendant de la résolution du périphérique d'affichage. L'application fonctionne avec des pixels indépendants du périphérique, qui sont ensuite mappés sur les pixels physiques de l'écran par le biais d'un facteur d'échelle, connu sous le nom de rapport de pixels du périphérique. Le facteur d'échelle est exprimé sous la forme d'un nombre à virgule flottante, par exemple 1.0 ou 2.0, ou de manière informelle 1x et 2x.

Par exemple, la création d'une page QWindow ou QWidget, et la définition de sa taille à 200x200 couvrira 200x200 pixels d'affichage sur un écran de densité standard (avec un rapport de pixels de 1,0), mais couvrira 400x400 pixels sur un écran de haute densité (avec un rapport de pixels de 2,0).

Ce modèle s'applique à la plupart des unités des API de niveau supérieur Qt GUI, Widgets et Quick, y compris la géométrie des widgets et des éléments, la géométrie des événements, la géométrie du bureau, de la fenêtre et de l'écran, ainsi que les vitesses d'animation.

Dessin

Qt XML profitera automatiquement de la densité accrue d'un écran à haut DPI lors de l'utilisation d'API de dessin telles que QPainter, ou lors du rendu de primitives graphiques ou de texte dans Qt Quick.

Par conséquent, l'application peut fonctionner dans un seul système de coordonnées unifié, sans avoir à tenir compte des densités d'affichage possibles sur lesquelles l'application s'exécute.

Cependant, lors de l'utilisation d'API de dessin de niveau inférieur, par exemple OpenGL, l'application doit prendre en compte le ratio de pixels de l'écran. Ceci est disponible à la fois par fenêtre, comme QWindow::devicePixelRatio() (qui suit le ratio de pixels de la fenêtre lorsqu'elle est déplacée d'un écran à l'autre), ou par écran, comme QScreen::devicePixelRatio().

Les tampons d'image tels que QImage et QPixmap représentent les pixels bruts et, par conséquent, ne fonctionnent pas dans le système de coordonnées indépendant de l'appareil décrit précédemment. Une image QImage de 400x400, avec un rapport de pixels de 2,0, s'adaptera à une image QWindow de 200x200 sur un écran à haute densité (2x), ou sera automatiquement réduite à 200x200 pendant le dessin si elle est destinée à un écran à densité standard (1x). Voir Drawing High Resolution Versions of Pixmaps and Images pour plus de détails.

Actifs d'image

Pour tirer parti de la densité de pixels accrue des écrans à haute densité de pixels, l'application doit également inclure des versions à haute densité de pixels des images statiques. Pour ce faire, utilisez une convention de dénomination spéciale pour les ressources à haute densité, par exemple logo@2x.png, et chargez à la fois l'image à densité normale et l'image à haute densité dans un fichier QIcon. Qt choisira automatiquement la meilleure représentation pour l'affichage cible au moment de l'exécution. Voir High DPI Icons pour plus de détails.

Géométrie de l'écran indépendante du périphérique

Les applications Qt fonctionnent généralement dans des pixels indépendants du périphérique. Cela inclut les géométries de fenêtre et d'écran communiquées à l'application.

Cela signifie que QScreen::geometry() peut ne pas renvoyer le nombre de pixels physiques de l'écran ou la taille des pixels telle qu'elle est indiquée par le système d'exploitation. Cela a des conséquences sur la géométrie des bureaux virtuels :

Les systèmes d'exploitation modernes créent généralement un système de coordonnées partagé pour tous les écrans connectés et permettent à l'utilisateur de positionner les écrans en fonction de leur configuration physique, généralement par le biais d'une boîte de dialogue de configuration. Si ce positionnement est effectué dans un système de coordonnées équivalent aux pixels indépendants du périphérique de Qt Positioning (comme sur macOS), la géométrie de QScreen correspondra à la disposition native de l'écran. Si le positionnement est effectué dans les pixels physiques de l'écran (comme sous Windows), le traitement de la géométrie de l'écran par Qt peut introduire des "trous" dans la géométrie du bureau virtuel inutilisée par un écran.

Plus précisément, Qt mettra à l'échelle la taille de l'écran (ce qui donnera un écran "plus petit" pour les facteurs d'échelle positifs), mais ne modifiera pas la position de l'écran. Cela produira une géométrie de bureau virtuel de type "îlots d'écrans".

Le code de l'application ne doit pas supposer qu'une position immédiatement adjacente et en dehors d'un écran est une position valide sur l'écran voisin. Il convient plutôt d'obtenir la liste des écrans à l'aide de QGuiApplication::screens() et d'utiliser cette liste pour déterminer la géométrie d'écran disponible.

Configuration

En tant qu'utilisateur final, vous pouvez vouloir ajuster les paramètres DPI ou d'échelle pour correspondre au matériel d'affichage, ou pour tenir compte de la distance de visualisation et des préférences personnelles. Ces ajustements doivent être effectués en utilisant les paramètres d'affichage natifs de la plate-forme, de sorte que toutes les applications s'accordent sur les mêmes valeurs de DPI ou de facteur d'échelle. Qt ne fournit pas d'outils à l'utilisateur final pour configurer le comportement de la prise en charge de Qt pour les hauts DPI.

Le système d'exploitation peut représenter le facteur d'échelle sous la forme d'un facteur (1,5), d'un pourcentage (150%) ou de points par pouce (144 DPI). Qt les traduit en ratio de pixel de l'appareil vu par l'application. Dans ce dernier cas, Qt suppose un DPI "de base" - par exemple, 96 sur X11 - et calcule le rapport de pixels du périphérique en conséquence.

Les facteurs d'échelle entiers (par exemple, 1,0 ou 2,0) sont préférables pour obtenir les meilleurs résultats. "Arrondir le facteur d'échelle par incréments de 25 % peut également donner de bons résultats. Le fait de régler le facteur d'échelle ou le DPI sur le DPI exact de l'affichage physique peut ne pas donner de bons résultats visuels en raison de la mise à l'échelle fractionnaire impliquée. Si l'application souffre d'artefacts visuels dans ce scénario, elle peut utiliser QGuiApplication::setHighDpiScaleFactorRoundingPolicy() pour limiter les facteurs d'échelle qu'elle verra.

Détails de la plate-forme

Le tableau suivant décrit comment configurer le high-DPI sur différentes plateformes.

Configuration de X11

La configuration requise pour Qt est le DPI logique par écran. Actuellement, X11 fournit soit un DPI logique global, soit un DPI physique par écran. Ni l'un ni l'autre ne correspondent exactement aux besoins de Qt, ce qui peut rendre la configuration du DPI sur X11 plus compliquée que sur d'autres plateformes.

Les environnements de bureau tels qu'Ubuntu et Kubuntu mettent en œuvre des solutions de contournement pour l'absence de DPI logique, et fournissent un support DPI élevé facilement configurable. Si vous souhaitez plutôt configurer manuellement les paramètres DPI de X11, cette section décrit les paramètres X11 que Qt lit.

Certains processus de configuration X11 impliquent de remplacer la taille physique de l'écran pour que les calculs DPI donnent une valeur DPI spécifique. Qt prend en charge ce flux de travail, mais cela nécessite une option, comme décrit ci-dessous.

La priorité de configuration exacte est la suivante, Qt utilisant la première option disponible. Notez que le comportement dépend de la version de Qt utilisée. Le comportement de Qt 5 suppose que AA_EnableHighDpiScaling a été défini (ce drapeau n'est pas nécessaire pour Qt 6).

La surcharge QT_USE_PHYSICAL_DPI

Définissez QT_USE_PHYSICAL_DPI=1 pour que Qt utilise inconditionnellement le DPI physique RandR ; en particulier, les champs mwidth et mheight de la structure xcb_randr_screen_change_notify_event_t sont utilisés. La valeur DPI sera arrondie à un entier.

Configuration de Windows

Qt utilise automatiquement les paramètres d'échelle d'affichage de Windows ; aucun paramètre spécifique n'est requis. Par exemple, si un écran est configuré pour une échelle de 175%, les applications Qt verront un ratio de pixels de 1,75 sur cet écran.

Windows définit plusieurs niveaux de sensibilisation au DPI, que les applications paramètrent pour bénéficier des fonctions de DPI élevé. Qt 6 est conscient du DPI par moniteur V2 par défaut. Si vous incorporez du code qui suppose un DPI global unique, vous voudrez peut-être définir un niveau de sensibilisation différent. Cela peut être fait en ajoutant une entrée à qt.conf :

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

Test

QT_SCALE_FACTOR

Définissez la variable d'environnement QT_SCALE_FACTOR pour fournir un facteur d'échelle global pour l'application.

QT_SCALE_FACTOR=2 ./myapp

Cela met à l'échelle toute la géométrie de l'application (y compris le ratio de pixels du périphérique) par le facteur donné, ce qui permet de tester la prise en charge des hauts DPI indépendamment du matériel disponible. Le facteur d'échelle défini sera utilisé tel quel par Qt XML et ne sera pas affecté par la page rounding policy.

Le rapport de pixels effectif, tel que renvoyé par QWindow::devicePixelRatio(), sera le produit du facteur d'échelle défini et du rapport de pixels natif du périphérique. Par exemple, en réglant QT_SCALE_FACTOR=2 sur un écran Wayland 2x, l'application verra un rapport de pixels de 4.

DprGadget

L'application de test DprGadget peut être utilisée pour inspecter la configuration native et la façon dont Qt Test y réagit :

DprGadget affiche le ratio de pixels de la fenêtre, tel qu'il est indiqué par QWindow::devicePixelRatio(). De plus, il affiche le DPI natif et le ratio de pixels du périphérique de l'écran sur lequel se trouve la fenêtre, comme indiqué par QPlatformScreen::logicalDpi() et QPlatformScreen::devicePixelRatio().

Les valeurs affichées doivent être mises à jour automatiquement en cas de changement d'écran et de DPI, et la boîte de dialogue doit conserver la même taille. Si ce n'est pas le cas, il peut s'agir d'un bogue de Qt.

DprGradget fait partie de la suite de tests manuels de Qt Test, et vous pouvez le trouver à l'adresse qtbase/tests/manual/highdpi/dprgadget.

Référence des variables d'environnement

Cette section énumère les variables d'environnement relatives aux DPI élevés reconnues par Qt. Dans l'ordre alphabétique :

• QT_ENABLE_HIGHDPI_SCALING Mettez la valeur 0 pour désactiver la mise à l'échelle en haute résolution, ce qui revient au comportement par défaut de Qt 5. Notez que cela n'a aucun effet sur les plates-formes telles que Wayland ou macOS - cela ne désactive pas le support natif de la haute résolution. Cette variable est destinée à des fins de test uniquement, et il n'est pas recommandé de la définir de manière permanente.
• QT_FONT_DPI Définit un DPI global. Il s'agit d'une ancienne variable d'environnement fournie à des fins de rétrocompatibilité.
• QT_SCALE_FACTOR Définit un facteur d'échelle global. À des fins de débogage et de test.
• QT_SCALE_FACTOR_ROUNDING_POLICY Définit le facteur d'échelle rounding policy, qui est appliqué au facteur d'échelle calculé à partir du DPI de l'écran. Les valeurs prises en charge sont les suivantes
  • Round (valeur par défaut de Qt 5)
  • PassThrough (Qt 6 par défaut)
• QT_SCREEN_SCALE_FACTORS Définit une liste de facteurs d'échelle d'écran. La liste peut se présenter sous l'un des deux formats suivants : soit une liste de facteurs d'échelle d'écran séparés par des points-virgules ("1;1.5;2"), soit une liste d'entrées écran=facteur séparées par des points-virgules ("screenA=1;screenB=1.5;screenC=2"). Il n'est pas recommandé de définir cette variable d'environnement car elle empêche Qt d'utiliser les valeurs DPI du système.
• QT_USE_PHYSICAL_DPI fait en sorte que Qt utilise le DPI physique au lieu du DPI logique. L'utilisation de l'IAP logique est normalement la meilleure option ; cette variable d'environnement peut être définie dans les cas où l'IAP logique n'est pas disponible et où l'IAP physique est connu pour être correct.

Référence aux systèmes de coordonnées

• Pixels indépendants du périphérique Il s'agit du principal système de coordonnées de Qt. Les fenêtres, les widgets, les éléments Quick, les événements et la géométrie de l'écran sont tous des pixels indépendants du périphérique. Typiquement, un pixel indépendant du périphérique a une taille visuelle constante à travers les types de périphériques et les densités d'écran. Bien qu'il s'agisse d'une généralisation, la taille exacte dépend de la configuration de l'appareil.
• Pixels de périphérique Ce système de coordonnées est utilisé pour les tâches de tramage et de graphisme de bas niveau, par exemple lors de l'utilisation de l'API OpenGL. Le système de coordonnées des pixels du périphérique est souvent équivalent au système de coordonnées physiques de l'écran, mais cela n'est pas garanti. Par exemple, macOS et Ubuntu peuvent appliquer une mise à l'échelle supplémentaire, en fonction des paramètres d'affichage.
• Pixels natifs Il s'agit du système de coordonnées utilisé par l'API native, telle que Win32 ou Cocoa (macOS). Selon la plateforme et la configuration de l'écran, les pixels natifs peuvent être équivalents aux pixels indépendants du périphérique ou aux pixels du périphérique.