En esta página

Alto DPI

Las pantallas de alta resolución (DPI) —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 da como resultado una alta densidad de píxeles o un elevado número de puntos por pulgada (DPI). El aumento de la resolución se utiliza para ofrecer un contenido más detallado en pantalla (texto más nítido, iconos más detallados), en lugar de más contenido (más ventanas, ventanas de mayor tamaño).

Qt es compatible con las pantallas de alta resolución en todas las plataformas y ofrece una API unificada que abstrae las diferencias entre plataformas. Qt tiene en cuenta automáticamente la resolución de la pantalla al utilizar APIs de nivel superior como Qt Widgets y Qt Quick, y las aplicaciones solo tienen que proporcionar recursos de alta resolución, como imágenes e iconos. Los cambios en las preferencias de usuario de la plataforma se detectan automáticamente.

El dibujo gráfico de bajo nivel (como el código OpenGL) debe tener en cuenta el alto DPI, pero puede utilizar las API multiplataforma de Qt 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 mapean a los píxeles físicos de la pantalla mediante un factor de escala, conocido como 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 de manera informal como 1x y 2x.

Por ejemplo, al crear un QWindow o un QWidget y establecer su tamaño en 200x200, se cubren 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 abarca 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 API de alto nivel de « Qt GUI », «Widgets» y «Quick», incluida la geometría de widgets y elementos, la geometría de eventos, la geometría del escritorio, de las ventanas y de la pantalla, así como las velocidades de animación.

Nota: El modelo no tiene en cuenta las diferencias entre clases de la interfaz de usuario, como el tamaño de los objetivos táctiles frente al de los objetivos del ratón.

Dibujo

Qt aprovecha automáticamente la mayor densidad de una pantalla de alto DPI al utilizar API de dibujo como ` QPainter`, o al renderizar primitivas gráficas o texto en ` Qt Quick`.

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

Sin embargo, al utilizar API de dibujo de nivel inferior, por ejemplo, OpenGL, la aplicación debe tener en cuenta la relación de píxeles del dispositivo de la pantalla. Esto está disponible tanto por ventana, como en QWindow::devicePixelRatio() (que realiza un seguimiento de la relación de píxeles del dispositivo de la ventana cuando se desplaza entre pantallas), como por pantalla, como en QScreen::devicePixelRatio().

Los búferes de imagen, como QImage y QPixmap, representan los píxeles sin procesar y, por lo tanto, no operan 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 adapta a un « QWindow » de 200x200 en una pantalla de alta densidad (2x), o se reduce automáticamente a 200x200 durante el dibujo si se destina a una pantalla de densidad estándar (1x). Consulta Drawing High Resolution Versions of Pixmaps and Images para obtener más detalles.

Recursos de imagen

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

Geometría de pantalla independiente del dispositivo

Las aplicaciones Qt suelen funcionar con píxeles independientes del dispositivo. Esto incluye las geometrías de ventana y pantalla que se comunican a la aplicación.

Esto significa que QScreen::geometry() puede no devolver el recuento de píxeles físicos de la pantalla, ni el tamaño de píxel tal y como lo indica 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 colocar las pantallas de forma que se ajusten a su configuración física, normalmente a través de un cuadro de 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), 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), el tratamiento que Qt da a la geometría de la pantalla puede introducir huecos en la geometría del escritorio virtual que no son utilizados por ninguna pantalla.

Concretamente, Qt escala el tamaño de la pantalla (lo que da como resultado una pantalla «más pequeña» para factores de escala positivos), pero no cambia la posición de la pantalla. Esto produce una geometría de escritorio virtual del tipo «islas de pantallas».

El código de la aplicación no debe dar por sentado que una posición inmediatamente adyacente a una pantalla y fuera de ella es una posición válida en la pantalla vecina. En su lugar, se debe obtener la lista de pantallas mediante QGuiApplication::screens() y utilizar esa lista para determinar la geometría de pantalla disponible.

Configuración

Es posible que desee ajustar la configuración de DPI o de escala para adaptarla al hardware de visualización, o para tener en cuenta la distancia de visualización y las preferencias personales. Estos ajustes deben realizarse mediante la configuración nativa de pantalla de la plataforma, de modo que todas las aplicaciones utilicen los mismos valores de DPI o factores de escala. Qt no ofrece herramientas para que el usuario final configure el comportamiento de la compatibilidad con alta resolución (DPI) de Qt.

El sistema operativo puede representar el factor de escala como un número (1,5), como un porcentaje (150 %) o como puntos por pulgada (144 DPI). Qt convierte estos valores a la relació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 la relación de píxeles del dispositivo resultante en consecuencia.

Para obtener los mejores resultados, es preferible utilizar factores de escala enteros (por ejemplo, 1,0 o 2,0). «Redondear» el factor de escala a incrementos del 25 % también puede dar buenos resultados. Establecer el factor de escala o los DPI exactamente al valor físico de la pantalla puede no dar buenos resultados visuales debido al escalado fraccionario que conlleva. Si la aplicación presenta artefactos visuales en este caso, puede utilizar QGuiApplication::setHighDpiScaleFactorRoundingPolicy() para limitar los factores de escala que ve.

Detalles de la plataforma

La siguiente tabla describe cómo configurar el alto DPI en diversas plataformas:

PlataformaConfiguración
macOSEstablece la escala de cada pantalla en las preferencias de pantalla. macOS transmite este valor a Qt como una relación de píxeles del dispositivo en forma de número entero.
WindowsEstablece el factor de escala para cada pantalla en la configuración de pantalla. El factor de escala base es del 100 % y se puede ajustar en incrementos del 25 %. Consulta «Configuración de Windows».
UbuntuConfigure el factor de escala en los ajustes de pantalla. En Ubuntu 20.04 y versiones posteriores, esto se puede hacer por pantalla en incrementos del 25 %.
X11Configure Xft.dpi o active la opción para utilizar los DPI físicos. Consulte «Configuración de X11».
WaylandQt lee ` wl_output::scale`, que está restringido a valores enteros. Los compositores de Wayland suelen tener una opción de configuración para establecer el factor de escala; por ejemplo, ` weston --scale`.
EGLFSEstablece ` QT_FONT_DPI ` en el valor de DPI lógico deseado, por ejemplo, ` QT_FONT_DPI=192`. Qt asume que el DPI base es 96 y escala la interfaz de usuario en consecuencia.

Nota: Algunos sistemas de ventanas pueden tener limitaciones que se reflejan en Qt. Qt no ofrece soluciones alternativas para estas limitaciones. En su lugar, se deben considerar soluciones alternativas a nivel del sistema de ventanas.

Configuración de X11

La configuración que debe proporcionarse a Qt es el DPI lógico por pantalla. Actualmente, X11 ofrece o bien un DPI lógico global o bien un DPI físico por pantalla. Ninguna de estas opciones es exactamente lo que necesita Qt, lo que puede hacer que la configuración del DPI en X11 resulte más complicada que en otras plataformas.

Los entornos de escritorio como Ubuntu y Kubuntu implementan soluciones alternativas para suplir la falta de DPI lógico y ofrecen compatibilidad con DPI alto fácilmente configurable. Si, por el contrario, deseas configurar los ajustes de DPI de X11 manualmente, en esta sección se describe qué ajustes de X11 lee Qt.

Algunos procesos de configuración de X11 implican anular el tamaño físico indicado de la pantalla para que los cálculos de DPI den como resultado un valor de DPI específico. Qt admite este proceso, pero es necesario activarlo, tal y como se describe a continuación.

La prioridad exacta de configuración es la siguiente, y Qt utiliza la primera opción disponible.

Prioridad de configuración del DPI de X11
PrioridadPropiedadDescripción
1Xft/DPIA partir de la configuración de X. Valor DPI lógico global.
2Xft.dpiDe los recursos de X. Valor DPI lógico global.
3DPI físico de RandR (solo Qt 5)DPI calculado a partir del tamaño físico y el tamaño en píxeles de cada pantalla, tal y como se indica en randr. Concretamente, se utilizan los campos « mwidth » y « mheight » de la estructura « xcb_randr_screen_change_notify_event_t ». El DPI se redondea a un número entero y se limita para que no sea inferior a 96.
496 pppValor de reserva.

Uso del DPI físico en X11

Para obligar a Qt a utilizar el DPI físico de RandR de forma incondicional en lugar del DPI lógico, establezca ` QT_USE_PHYSICAL_DPI=1`. A continuación, Qt lee los campos ` mwidth ` y ` mheight ` de la estructura ` xcb_randr_screen_change_notify_event_t ` y redondea el valor de DPI resultante a un número entero.

Esto resulta útil cuando el DPI lógico no está disponible y se sabe que el DPI físico de la pantalla es correcto. Véase también Referencia de variables de entorno.

Configuración de Windows

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

Windows define varios niveles de reconocimiento de DPI, que las aplicaciones pueden establecer para activar las funciones de alto DPI. Qt 6 utiliza de forma predeterminada el reconocimiento de DPI por monitor V2. Si estás incorporando código que asume un único DPI global, es posible que desees establecer un nivel de reconocimiento diferente. Para ello, añade lo siguiente a ` qt.conf`:

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

Pruebas

Al desarrollar o depurar la compatibilidad con alta resolución (DPI), a menudo no resulta práctico depender de un hardware específico. Qt proporciona una variable de entorno para simular diferentes factores de escala, así como una aplicación de prueba para comprobar cómo interpreta Qt la configuración actual de la pantalla.

QT_SCALE_FACTOR

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

Por ejemplo:

QT_SCALE_FACTOR=2 ./myapp

Esto escala toda la geometría de la aplicación (incluida la relación de píxeles del dispositivo) según el factor indicado, lo que permite probar la compatibilidad con alta resolución (DPI) independientemente del hardware disponible.

Qt utiliza el factor de escala establecido tal cual y no se ve afectado por rounding policy.

La relación de píxeles del dispositivo efectiva, tal y como la devuelve QWindow::devicePixelRatio(), es el producto del factor de escala establecido y la relación de píxeles nativa del dispositivo. Por ejemplo, al establecer QT_SCALE_FACTOR=2 en una pantalla Wayland de 2x, la aplicación ve una relación de píxeles del dispositivo de 4.

Aplicación de prueba DprGadget

Puedes utilizar la aplicación de prueba DprGadget para inspeccionar la configuración nativa y cómo reacciona Qt ante ella:

DprGadget muestra la relación de píxeles del dispositivo y los valores de DPI nativos

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

Los valores mostrados deberían actualizarse automáticamente cuando cambien la pantalla y el DPI, y el cuadro de diálogo debería mantener el mismo tamaño. De no ser así, podría tratarse de un error de Qt.

DprGadget forma parte del conjunto de pruebas manuales de Qt y se puede encontrar en qtbase/tests/manual/highdpi/dprgadget.

Referencia de variables de entorno

En esta sección se enumeran las variables de entorno relacionadas con el alto DPI que reconoce Qt. Por orden alfabético:

VariableDescripción
QT_ENABLE_HIGHDPI_SCALINGEstablecer en 0 para desactivar el escalado de alta resolución.

Nota: Esto no tiene ningún efecto en plataformas como Wayland o macOS, ya que no desactiva ninguna compatibilidad nativa con alta resolución (DPI). Esta variable está pensada únicamente con fines de prueba, y no se recomienda establecerla de forma permanente.

QT_FONT_DPIEstablece un DPI lógico global. En plataformas integradas sin un sistema de ventanas nativo (como EGLFS), esta es la forma recomendada de configurar el escalado. En otras plataformas, evita esta variable y utiliza en su lugar los ajustes de escalado del sistema operativo.
QT_SCALE_FACTOREstablece un factor de escala global. Para fines de depuración y pruebas.
QT_SCALE_FACTOR_ROUNDING_POLICYEstablece el factor de escala rounding policy, que se aplica al factor de escala calculado a partir del DPI de la pantalla.

Valores admitidos:

  • Redondear
  • PassThrough (por defecto)
QT_SCREEN_SCALE_FACTORSEstablece una lista de factores de escala de pantalla. La lista puede tener cualquiera de estos formatos:
  • Una lista de factores de escala de pantalla separados por punto y coma («1;1,5;2»),
  • Una lista de entradas «pantalla=factor» 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 DPI del sistema.

QT_USE_PHYSICAL_DPIHace que Qt utilice el DPI físico en lugar del DPI lógico. Normalmente, la mejor opción es utilizar el DPI lógico; esta variable de entorno se puede configurar en los casos en que el DPI lógico no esté disponible y se sepa que el DPI físico es correcto.

Referencia de sistemas de coordenadas

En las API de Qt se utilizan los siguientes sistemas de coordenadas. La mayor parte del código de las aplicaciones opera en píxeles independientes del dispositivo; los demás sistemas son relevantes principalmente para gráficos de bajo nivel y la integración con la plataforma:

Sistema de coordenadasDescripción
Píxeles independientes del dispositivoEste es el sistema de coordenadas principal de Qt. La geometría de las ventanas, los widgets, los elementos Qt Quick, los eventos y la pantalla se expresa en píxeles independientes del dispositivo. Normalmente, un píxel independiente del dispositivo tiene un tamaño visual constante en todos los tipos de dispositivos y densidades de pantalla. Aunque se trata de una generalización, el tamaño exacto depende de la configuración del dispositivo.
Píxeles del dispositivoEste sistema de coordenadas se utiliza para tareas de rasterización y gráficos de bajo nivel, por ejemplo, al utilizar la API de 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 nativosEste es el sistema de coordenadas utilizado por las API nativas, como Win32 o Cocoa (macOS). Dependiendo de la plataforma y la configuración de la pantalla, los píxeles nativos pueden ser equivalentes a los píxeles independientes del dispositivo o a los píxeles del dispositivo.

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.