DPI altos

Las pantallas de alta densidad de píxeles, también conocidas como pantallas retina, son pantallas con una alta resolución (píxeles) en relación con su tamaño físico (mm), lo que se traduce en una alta densidad de píxeles o un elevado número de puntos por pulgada (PPP). El aumento de la resolución se utiliza para proporcionar un contenido más detallado en pantalla (texto más suave, iconos más detallados), en lugar de más contenido (más ventanas, ventanas de mayor tamaño).

Qt es compatible con pantallas de alta DPI en todas las plataformas y proporciona una API unificada que hace abstracción de las diferencias entre plataformas. Qt tendrá en cuenta automáticamente la resolución de la pantalla cuando utilice API de alto nivel como Qt Widgets y Qt Quicky las aplicaciones sólo tienen que proporcionar recursos de alta resolución, como imágenes e iconos. Los cambios en las preferencias de usuario de la plataforma se tienen en cuenta automáticamente.

El dibujo gráfico de bajo nivel (como el código OpenGL) debe tener en cuenta los PPP altos, pero puede utilizar las API Qt multiplataforma para conocer las resoluciones de pantalla de la plataforma.

Modelo conceptual

Qt utiliza un modelo en el que el sistema de coordenadas de la aplicación es independiente de la resolución del dispositivo de visualización. La aplicación opera en píxeles independientes del dispositivo, que luego se asignan a los píxeles físicos de la pantalla a través de un factor de escala, conocido como la relación de píxeles del dispositivo. El factor de escala se expresa como un número de coma flotante, por ejemplo 1.0 o 2.0, o informalmente como 1x y 2x.

Por ejemplo, crear un QWindow o QWidget, y establecer su tamaño en 200x200 cubrirá 200x200 píxeles de pantalla en una pantalla de densidad estándar (con una relación de píxeles del dispositivo de 1,0), pero cubrirá 400x400 píxeles en una pantalla de alta densidad (con una relación de píxeles del dispositivo de 2,0).

Este modelo se aplica a la mayoría de las unidades de las APIs de nivel superior Qt GUI, Widgets y Quick, incluyendo la geometría de widgets y elementos, la geometría de eventos, la geometría de escritorios, ventanas y pantallas, así como las velocidades de animación.

Dibujo

Qt aprovechará automáticamente la mayor densidad de una pantalla de alto PPP cuando utilice APIs de dibujo como QPainter, o cuando renderice primitivas gráficas o texto en Qt Quick.

Como resultado, la aplicación puede operar en un único sistema de coordenadas unificado, sin necesidad de tener en cuenta las posibles densidades de pantalla en las que se ejecutará la aplicación.

Sin embargo, cuando se utilizan API de dibujo de nivel inferior, por ejemplo OpenGL, la aplicación debe tener en cuenta la proporción de píxeles de la pantalla. Esto está disponible tanto por ventana, como QWindow::devicePixelRatio() (siguiendo la relación de píxeles del dispositivo de la ventana cuando se mueve entre pantallas), o por pantalla, como QScreen::devicePixelRatio().

Los búferes de imagen como QImage y QPixmap representan los píxeles sin procesar y, por tanto, no funcionan en el sistema de coordenadas independiente del dispositivo descrito anteriormente. Un QImage de tamaño 400x400, con una relación de píxeles del dispositivo de 2,0, se ajustará a un QWindow de 200x200 en una pantalla de alta densidad (2x), o se reducirá automáticamente a 200x200 durante el dibujo si se utiliza una pantalla de densidad estándar (1x). Para más información, consulte Drawing High Resolution Versions of Pixmaps and Images.

Activos de imagen

Para aprovechar la mayor densidad de píxeles de las pantallas de alta densidad de PPP, la aplicación también debe incluir versiones de alta densidad de PPP de los activos de imagen estáticos. Esto se consigue utilizando una convención de nomenclatura especial para los activos de alta densidad, por ejemplo logo@2x.png, y cargando tanto la imagen de densidad normal como la de alta densidad en QIcon. Qt elegirá automáticamente la mejor representación para la pantalla de destino en tiempo de ejecución. Consulte High DPI Icons para obtener más detalles.

Geometría de pantalla independiente del dispositivo

Las aplicaciones Qt generalmente operan en píxeles independientes del dispositivo. Esto incluye las geometrías de ventana y pantalla reportadas a la aplicación.

Esto significa que QScreen::geometry() puede no devolver el número de píxeles físicos de la pantalla, o el tamaño de píxel tal y como lo informa el sistema operativo. Esto tiene implicaciones para la geometría del escritorio virtual:

Los sistemas operativos de escritorio modernos suelen crear un sistema de coordenadas compartido para todas las pantallas conectadas y permiten al usuario posicionar las pantallas para que coincidan con su configuración de pantalla física, normalmente a través de un diálogo de configuración. Si este posicionamiento se realiza en un sistema de coordenadas equivalente a los píxeles independientes del dispositivo de Qt (como en macOS), entonces la geometría de QScreen coincidirá con la disposición nativa de la pantalla. Si el posicionamiento se realiza en píxeles físicos de la pantalla (como en Windows), entonces el tratamiento de Qt de la geometría de la pantalla puede introducir "huecos" en la geometría del escritorio virtual no utilizados por ninguna pantalla.

Específicamente, Qt escalará el tamaño de la pantalla (resultando en una pantalla "más pequeña" para factores de escala positivos), pero no cambiará la posición de la pantalla. Esto producirá una geometría de escritorio virtual del tipo islas de pantallas.

El código de la aplicación no debe asumir que una posición inmediatamente adyacente y fuera de una pantalla es una posición válida en la pantalla vecina. En su lugar, obtenga la lista de pantallas utilizando QGuiApplication::screens() y utilice esa lista para razonar sobre la geometría de pantalla disponible.

Configuración de

Como usuario final, es posible que desee ajustar la configuración de PPP o escala para que coincida con el hardware de visualización, o para tener en cuenta la distancia de visualización y las preferencias personales. Estos ajustes deben realizarse utilizando la configuración de pantalla nativa de la plataforma, de modo que todas las aplicaciones coincidan en los mismos valores de PPP o factor de escala. Qt no proporciona facilidades al usuario final para configurar el comportamiento del soporte de Qt para PPP altos.

El sistema operativo puede representar el factor de escala como un factor (1.5), como un porcentaje (150%), o como puntos por pulgada (144 DPI). Qt traduce estos a la proporción de píxeles del dispositivo que ve la aplicación. En este último caso Qt asume un DPI "base" - por ejemplo, 96 en X11 - y calcula el ratio de píxeles del dispositivo resultante en consecuencia.

Los factores de escala enteros (por ejemplo, 1.0 o 2.0) son preferibles para obtener mejores resultados. "Redondear el factor de escala a incrementos del 25% también puede dar buenos resultados. Ajustar el factor de escala o los PPP a los PPP exactos de la pantalla física puede no dar buenos resultados visuales debido al escalado fraccional que implica. Si la aplicación sufre de artefactos visuales en este escenario, puede utilizar QGuiApplication::setHighDpiScaleFactorRoundingPolicy() para limitar los factores de escala que verá.

Detalles de la plataforma

La siguiente tabla describe cómo configurar los PPP altos en varias plataformas.

Configuración de X11

La entrada de configuración necesaria para Qt es el DPI lógico por pantalla. Actualmente, X11 proporciona DPI lógico global o DPI físico por pantalla. Ninguno de los dos es exactamente lo que Qt necesita, lo que puede hacer que la configuración DPI en X11 sea más complicada que en otras plataformas.

Entornos de escritorio como Ubuntu y Kubuntu implementan soluciones para la falta de DPI lógicos, y proporcionan un soporte de DPI altos fácilmente configurable. Si en cambio quieres configurar manualmente los ajustes de PPP de X11, esta sección describe qué ajustes de X11 lee Qt.

Algunos flujos de trabajo de configuración de X11 implican anular el tamaño físico informado de la pantalla para hacer que los cálculos de PPP produzcan un valor de PPP específico. Qt soporta este flujo de trabajo, pero esto requiere una opción, como se describe a continuación.

La prioridad exacta de configuración es la siguiente, donde Qt utiliza la primera opción disponible. Tenga en cuenta que el comportamiento depende de la versión de Qt en uso. El comportamiento de Qt 5 asume que AA_EnableHighDpiScaling ha sido configurado (esta bandera no es necesaria en Qt 6).

El override QT_USE_PHYSICAL_DPI

Establece QT_USE_PHYSICAL_DPI=1 para que Qt utilice los DPI físicos de RandR incondicionalmente; en concreto, se utilizan los campos mwidth y mheight de la estructura xcb_randr_screen_change_notify_event_t. El valor DPI se redondeará a un número entero.

Configuración de Windows

Qt utiliza la configuración de escala de pantalla de Windows automáticamente; no se requiere ninguna configuración específica. Por ejemplo, si una pantalla está configurada para una escala del 175%, entonces las aplicaciones Qt verán una relación de píxeles del dispositivo de 1,75 en esa pantalla.

Windows define varios niveles de DPI Awareness, que las aplicaciones configuran para optar a características de DPI altas. Qt 6 es Per-Monitor DPI Aware V2 por defecto. Si está incorporando código que asume un único DPI global, entonces es posible que desee establecer un nivel de conciencia diferente. Esto se puede hacer añadiendo una entrada a qt.conf:

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

Testing

QT_SCALE_FACTOR

Establezca la variable de entorno QT_SCALE_FACTOR para proporcionar un factor de escala global para la aplicación.

QT_SCALE_FACTOR=2 ./myapp

Esto escala toda la geometría de la aplicación (incluyendo la proporción de píxeles del dispositivo) por el factor dado, lo que permite probar el soporte de alta DPI independientemente del hardware disponible. El factor de escala establecido será utilizado tal cual por Qt y no se verá afectado por rounding policy.

El ratio de píxeles efectivo del dispositivo, devuelto por QWindow::devicePixelRatio(), será el producto del factor de escala establecido y el ratio de píxeles nativo del dispositivo. Por ejemplo, establecer QT_SCALE_FACTOR=2 en una pantalla Wayland 2x hará que la aplicación vea un ratio de píxeles del dispositivo de 4.

DprGadget

La aplicación de prueba DprGadget se puede utilizar para inspeccionar la configuración nativa, y cómo Qt reacciona a ella:

DprGadget muestra la relación de píxeles del dispositivo de la ventana, según QWindow::devicePixelRatio(). Además, muestra el DPI nativo y el ratio de pixel de dispositivo de la pantalla en la que se encuentra la ventana, tal y como informan QPlatformScreen::logicalDpi() y QPlatformScreen::devicePixelRatio().

Los valores mostrados deberían actualizarse automáticamente con los cambios de pantalla y DPI, y el diálogo debería mantener el mismo tamaño. Si no es así, podría ser un error de Qt.

DprGradget forma parte del conjunto de pruebas manuales de Qt, y puedes encontrarlo en qtbase/tests/manual/highdpi/dprgadget.

Referencia de variables de entorno

Esta sección enumera las variables de entorno relacionadas con los PPP altos reconocidas por Qt. En orden alfabético:

• QT_ENABLE_HIGHDPI_SCALING Póngala a 0 para deshabilitar el escalado a alta ppp; volviendo de hecho al comportamiento por defecto de Qt 5. Tenga en cuenta que esto no tiene ningún efecto en plataformas como Wayland o macOS - no desactiva ningún soporte nativo de alta DPI. Esta variable está pensada sólo para propósitos de prueba, y no se recomienda establecerla de forma permanente.
• QT_FONT_DPI Establece un DPI global. Esta es una variable de entorno heredada que se proporciona para compatibilidad con versiones anteriores.
• QT_SCALE_FACTOR Establece un factor de escala global. Para depuración y pruebas.
• QT_SCALE_FACTOR_ROUNDING_POLICY Establece el factor de escala rounding policy, que se aplica al factor de escala calculado a partir de los PPP de la pantalla. Los valores soportados incluyen
  • Round (Qt 5 por defecto)
  • PassThrough (Qt 6 por defecto)
• QT_SCREEN_SCALE_FACTORS Establece una lista de factores de escala de pantalla. La lista puede tener dos formatos: una lista de factores de escala de pantalla separada por punto y coma ("1;1.5;2"), o una lista de entradas de factor de pantalla separadas por punto y coma ("pantallaA=1;pantallaB=1.5;pantallaC=2"). No se recomienda configurar esta variable de entorno, ya que impide que Qt utilice los valores de PPP del sistema.
• QT_USE_PHYSICAL_DPI Hace que Qt use DPI físicos en lugar de DPI lógicos. Usar DPI lógicos es normalmente la mejor opción; esta variable de entorno puede establecerse en casos en los que los DPI lógicos no estén disponibles y se sepa que los DPI físicos son correctos.

Referencia de sistemas de coordenadas

• Píxeles independientes del dispositivo Este es el sistema de coordenadas principal de Qt. La geometría de las ventanas, widgets, elementos rápidos, eventos y pantallas están todas en píxeles independientes del dispositivo. Típicamente, un píxel independiente del dispositivo tiene un tamaño visual constante en todos los tipos de dispositivos y densidades de pantalla. Aunque esto es una generalización, el tamaño exacto depende de la configuración del dispositivo.
• Píxeles de dispositivo Este sistema de coordenadas se utiliza para la rasterización y las tareas gráficas de bajo nivel, por ejemplo, cuando se utiliza la API OpenGL. El sistema de coordenadas de píxeles del dispositivo suele ser equivalente al sistema de coordenadas físico de la pantalla, pero esto no está garantizado. Por ejemplo, tanto macOS como Ubuntu pueden aplicar un escalado adicional, dependiendo de la configuración de la pantalla.
• Píxeles nativos Este es el sistema de coordenadas utilizado por la API nativa, como Win32 o Cocoa (macOS). Dependiendo de la plataforma y de la configuración de la pantalla, los píxeles nativos pueden ser equivalentes a píxeles independientes del dispositivo o del dispositivo.