> For the complete documentation index, see [llms.txt](https://doc.velneo.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://doc.velneo.com/velneo/funcionalidades-comunes/soporte-de-alta-resolucion-highdpi.md).

# Soporte de alta resolución (HighDPI)

Velneo ofrece soporte de alta resolución para todos sus componentes, denominado comercialmente **Retina Display** o **soporte HighDPI**. Este soporte permite que las aplicaciones se ejecuten en entornos de alta resolución adaptándose automáticamente mientras mantienen su tamaño aparente.

## Plataformas soportadas

La funcionalidad está disponible para:

* Windows
* Linux
* OS X
* Android
* iOS

## Concepto de Device Pixel Ratio

El ratio de píxeles del dispositivo es:

* 1 para DPI normal.
* 2 para alta resolución.

En dispositivos de alta resolución, la resolución física duplica la lógica, escalando elementos al doble de tamaño físico mientras se mantiene el tamaño lógico.

## Comportamiento en múltiples pantallas

Si la pantalla principal soporta HighDPI, al resto aplicará HighDPI, si lo soportan, o zoom, si no es así.

## Variables de entorno de sistemas operativos para HighDPI

{% hint style="info" %}
Estas variables son para ajuste puntual o depuración. Para uso permanente en producción, la solución recomendada es adaptar los formularios al escalado del sistema.
{% endhint %}

Se trata de variables que podemos configurar en el ámbito del sistema operativo.

#### QT\_ENABLE\_HIGHDPI\_SCALING

Habilita o deshabilita el escalado automático basado en la densidad de píxeles del monitor.

* `1` - habilitado (valor por defecto).
* `0` - deshabilitado.

{% hint style="info" %}
Nota: En la versión 35 y anteriores esta variable se llamaba QT\_AUTO\_SCREEN\_SCALE\_FACTOR y aceptaba `true` o `false`.
{% endhint %}

#### QT\_SCALE\_FACTOR

Define un factor de escala global para toda la aplicación, incluyendo las fuentes.

Ejemplo: `QT_SCALE_FACTOR=0.8` para compensar un escalado del sistema del 125%.

#### QT\_SCREEN\_SCALE\_FACTORS

Especifica factores de escala individuales por pantalla, separados por el carácter <kbd>;</kbd>. Ejemplo:

```
QT_SCREEN_SCALE_FACTORS=1;2;2;1.5
QT_SCREEN_SCALE_FACTORS=pantalla1=1;pantalla2=2;pantalla3=1.5
```

#### QT\_SCALE\_FACTOR\_ROUNDING\_POLICY

Controla cómo se redondea el factor de escala calculado.

* `Round` - redondea al entero más cercano.
* `PassThrough` - usa el valor exacto sin redondear (que es el comportamiento por defecto).

#### Configuración en Windows

Si se necesita deshabilitar el escalado del sistema en Windows, la opción recomendada es hacerlo en las propiedades de compatibilidad del propio ejecutable (vClient.exe, por ejemplo):

1. Click derecho en vClient.exe → Propiedades → pestaña "Compatibilidad".
2. Activar "Reemplazar comportamiento de escalado de PPP de alta resolución".
3. Seleccionar "Aplicación".
4. Aceptar y reiniciar el vClient.

Opción alternativa: configurar en el sistema operativo la variable de entorno `QT_ENABLE_HIGHDPI_SCALING=0`, cerrar sesión de Windows y volver a entrar para que surta efecto.

#### Configuración en Linux

Para Velneo vClient en Linux (X11), si el sistema no aplica correctamente el escalado, configurar manualmente:

```
QT_ENABLE_HIGHDPI_SCALING=0
QT_SCALE_FACTOR=<factor>
```

{% hint style="info" icon="triangle-exclamation" %}
En entornos *Wayland* (GNOME, KDE con Ubuntu 22.04+), QT\_ENABLE\_HIGHDPI\_SCALING no tiene efecto. El escalado lo gestiona el compositor del escritorio.
{% endhint %}

## Recomendaciones para dibujos

En los [dibujos](/velneo-vdevelop/proyectos-objetos-y-editores/de-aplicacion-y-datos/dibujo.md) o campos [objeto dibujo](/velneo-vdevelop/proyectos-objetos-y-editores/proyecto-de-aplicacion/formulario/controles-de-edicion/objeto-dibujo.md), en la propiedad **aspecto de dibujo** recomendamos usar siempre el valor **proporcionar** o **proporcionar sin ampliar**, para que estos se vean correctamente. Evitar la propiedad **tamaño original**.

Asimismo, recomendamos usar imágenes del doble del tamaño del sitio donde vayan a ir para soportar HighDPI con ratio 2, o más para ratios mayores. Aplicable tanto a Velneo como a [QML](/velneo-vdevelop/scripts/lenguajes/qml.md).