Haute résolution (DPI)

Les écrans à haute résolution (DPI) – également appelés écrans Retina – sont des écrans présentant une résolution élevée (en pixels) par rapport à leur taille physique (en mm), ce qui se traduit par une densité de pixels élevée, ou un nombre élevé de points par pouce (DPI). Cette résolution accrue sert à afficher un contenu plus détaillé à l’écran (texte plus lisse, icônes plus précises), plutôt qu’à afficher davantage de contenu (plus de fenêtres, des 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 tient automatiquement compte de la résolution de l’écran lors de l’utilisation d’API de haut niveau telles que Qt Widgets et Qt Quick, et les applications n’ont qu’à fournir des ressources haute résolution, telles que des images et des icônes. Les modifications apportées aux préférences utilisateur de la plateforme sont automatiquement prises en compte.

Le rendu graphique de bas niveau (tel que le code OpenGL) doit prendre en charge la haute résolution, mais peut utiliser les API Qt multiplateformes pour obtenir des informations sur 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 en pixels indépendants du périphérique, qui sont ensuite mappés aux pixels physiques de l’écran via un facteur d’échelle, appelé « rapport de pixels du périphérique ». Le facteur d’échelle est exprimé sous forme de nombre à virgule flottante, par exemple 1.0 ou 2.0, ou de manière informelle sous la forme 1x et 2x.

Par exemple, la création d’un QWindow ou d’un QWidget, dont la taille est définie sur 200x200, couvre 200x200 pixels d’affichage sur un écran à densité standard (avec un rapport de pixels de l’appareil de 1,0), mais couvre 400x400 pixels sur un écran haute densité (avec un rapport de pixels de l’appareil de 2,0).

Ce modèle s’applique à la plupart des unités des API de haut niveau « 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, des fenêtres et de l’écran, ainsi que les vitesses d’animation.

Tracé

Qt tire automatiquement parti de la densité accrue d’un écran à haute résolution (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`.

De ce fait, l’application peut fonctionner dans un système de coordonnées unique et unifié, sans avoir à tenir compte des différentes densités d’affichage sur lesquelles elle s’exécute.

Cependant, lors de l’utilisation d’API de dessin de plus bas niveau, par exemple OpenGL, l’application doit tenir compte du rapport de pixels de l’écran. Cette information est disponible à la fois par fenêtre, via ` QWindow::devicePixelRatio()` (qui suit le rapport de pixels de la fenêtre lorsqu’elle est déplacée d’un écran à l’autre), et par écran, via ` 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 du périphérique décrit précédemment. Une QImage de taille 400x400, avec un rapport de pixels de périphérique de 2,0, s'adapte à une QWindow de 200x200 sur un écran haute densité (2x), ou est automatiquement redimensionnée à 200x200 lors du dessin si l'affichage ciblé est de densité standard (1x). Voir Drawing High Resolution Versions of Pixmaps and Images pour plus de détails.

Ressources graphiques

Pour tirer parti de la densité de pixels accrue des écrans haute résolution, l’application doit également inclure des versions haute résolution des ressources d’images statiques. Pour ce faire, il convient d’utiliser une convention de nommage spécifique pour les ressources haute densité, par exemple logo@2x.png, et de charger à la fois l’image en densité normale et l’image haute densité dans un QIcon. Qt choisit automatiquement la meilleure représentation pour l’écran cible lors de l’exécution. Voir High DPI Icons pour plus de détails.

Géométrie d’écran indépendante du périphérique

Les applications Qt fonctionnent généralement en 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 la fonction ` QScreen::geometry()` peut ne pas renvoyer le nombre de pixels physiques de l’écran, ni la taille des pixels telle qu’elle est communiquée par le système d’exploitation. Cela a des implications pour la géométrie du bureau virtuel :

Les systèmes d’exploitation de bureau 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 afin qu’ils correspondent à leur configuration physique, généralement via 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 (comme sous macOS), la géométrie de QScreen correspond alors à la disposition native de l’écran. Si le positionnement est effectué en pixels physiques de l’écran (comme sous Windows), le traitement de la géométrie d’écran par Qt peut alors introduire des espaces vides dans la géométrie du bureau virtuel qui ne sont utilisés par aucun écran.

Plus précisément, Qt redimensionne la taille de l’écran (ce qui se traduit par un écran « plus petit » pour des facteurs d’échelle positifs), mais ne modifie pas la position de l’écran. Cela produit 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 à un écran et située en dehors de celui-ci est une position valide sur l’écran voisin. Il convient plutôt de récupérer la liste des écrans à l’aide de la fonction ` QGuiApplication::screens()` et d’utiliser cette liste pour déterminer la géométrie des écrans disponibles.

Configuration

Vous souhaiterez peut-être ajuster les paramètres de DPI ou d’échelle pour les adapter au matériel d’affichage, ou pour tenir compte de la distance de visionnage et de vos préférences personnelles. Ces ajustements doivent être effectués à l’aide des paramètres d’affichage natifs de la plateforme, afin que toutes les applications utilisent les mêmes valeurs de DPI ou de facteur d’échelle. Qt ne fournit pas de fonctionnalités destinées à l’utilisateur final pour configurer le comportement de la prise en charge du DPI élevé de Qt.

Le système d’exploitation peut représenter le facteur d’échelle soit sous forme de facteur (1,5), soit sous forme de pourcentage (150 %), soit en points par pouce (144 DPI). Qt convertit ces valeurs en rapport de pixels de l'appareil tel qu'il est perçu par l'application. Dans ce dernier cas, Qt suppose un DPI « de base » – par exemple, 96 sous X11 – et calcule le rapport de pixels de l'appareil 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. Définir le facteur d’échelle ou le DPI à la valeur exacte du DPI physique de l’écran peut ne pas donner de bons résultats visuels en raison de la mise à l’échelle fractionnaire impliquée. Si l’application présente des artefacts visuels dans ce scénario, elle peut utiliser ` QGuiApplication::setHighDpiScaleFactorRoundingPolicy()` pour limiter les facteurs d’échelle qu’elle perçoit.

Détails sur les plateformes

Le tableau suivant décrit comment configurer la haute résolution (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. Aucune de ces options ne correspond 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 pallier l’absence de DPI logique et offrent une prise en charge des DPI élevés 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 déclarée de l'écran afin que les calculs de DPI aboutissent à une valeur de DPI spécifique. Qt prend en charge ce processus, mais cela nécessite une activation, comme décrit ci-dessous.

L'ordre de priorité exact de la configuration est le suivant : Qt utilise la première option disponible.

Utilisation du DPI physique sous X11

Pour forcer Qt à utiliser sans condition le DPI physique RandR au lieu du DPI logique, définissez ` QT_USE_PHYSICAL_DPI=1`. Qt lit alors les champs ` mwidth ` et ` mheight ` de la structure ` xcb_randr_screen_change_notify_event_t ` et arrondit la valeur de DPI obtenue à un entier.

Cela s’avère utile lorsque le DPI logique n’est pas disponible et que l’on sait que le DPI physique de l’écran est correct. Voir également la référence aux variables d’environnement.

Configuration de Windows

Qt utilise automatiquement les paramètres d’échelle d’affichage de Windows ; aucun réglage spécifique n’est nécessaire. Par exemple, si un écran est configuré avec une échelle de 175 %, les applications Qt voient alors un rapport de pixels de l’appareil (DPI) de 1,75 sur cet écran.

Windows définit plusieurs niveaux de prise en charge du DPI, que les applications peuvent activer pour bénéficier des fonctionnalités haute résolution. Par défaut, Qt 6 utilise le niveau « Per-Monitor DPI Aware V2 ». Si vous intégrez du code qui suppose un DPI global unique, vous pouvez définir un niveau de prise en charge différent. Pour ce faire, ajoutez ce qui suit au fichier ` qt.conf` :

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

Tests

Lors du développement ou du débogage de la prise en charge de la haute résolution, il est souvent peu pratique de s’appuyer sur un matériel spécifique. Qt fournit une variable d’environnement permettant de simuler différents facteurs d’échelle, ainsi qu’une application de test pour vérifier comment Qt interprète la configuration d’affichage actuelle.

QT_SCALE_FACTOR

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

Par exemple :

QT_SCALE_FACTOR=2 ./myapp

Cela permet de mettre à l'échelle toute la géométrie de l'application (y compris le rapport de pixels de l'appareil) selon le facteur donné, ce qui permet de tester la prise en charge des hauteurs de résolution élevées indépendamment du matériel disponible.

Le facteur d'échelle défini est utilisé tel quel par Qt et n'est pas affecté par la variable d'environnement rounding policy.

Le rapport de pixels effectif de l’appareil, tel que renvoyé par ` QWindow::devicePixelRatio()`, est le produit du facteur d’échelle défini et du rapport de pixels natif de l’appareil. Par exemple, définir ` QT_SCALE_FACTOR=2 ` sur un écran Wayland 2x fait que l’application perçoit un rapport de pixels de 4.

Application de test DprGadget

Vous pouvez utiliser l’application de test DprGadget pour inspecter la configuration native et observer comment Qt y réagit :

DprGadget affiche le rapport de pixels natif de la fenêtre, tel que rapporté par ` QWindow::devicePixelRatio()` (). De plus, elle affiche le DPI natif et le rapport de pixels natif de l'écran sur lequel se trouve la fenêtre, tels que rapportés par `QPlatformScreen::logicalDpi()` et `QPlatformScreen::devicePixelRatio()`.

Les valeurs affichées devraient être mises à jour automatiquement en cas de modification de l'écran ou du DPI, et la boîte de dialogue devrait conserver la même taille. Si ce n'est pas le cas, il pourrait s'agir d'un bug de Qt.

DprGadget fait partie de la suite de tests manuels de Qt ; vous pouvez le trouver à l'adresse qtbase/tests/manual/highdpi/dprgadget.

Référence des variables d'environnement

Cette section répertorie les variables d'environnement liées à la haute résolution (high DPI) reconnues par Qt. Par ordre alphabétique :

Référence sur les systèmes de coordonnées

Les systèmes de coordonnées suivants sont utilisés dans l'ensemble des API de Qt. La plupart des codes d'application fonctionnent en pixels indépendants du périphérique ; les autres systèmes concernent principalement les graphismes de bas niveau et l'intégration aux plateformes :