En esta página

QRhiSwapChainHdrInfo Struct

Describe la información relacionada con el alto rango dinámico de la salida asociada a la cadena de intercambio. Más información...

Encabezado: #include <rhi/qrhi.h>
CMake: find_package(Qt6 REQUIRED COMPONENTS GuiPrivate)
target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)
qmake: QT += gui-private
Desde: Qt 6.6

Tipos públicos

enum LimitsType { LuminanceInNits, ColorComponentValue }
enum LuminanceBehavior { SceneReferred, DisplayReferred }

Variables públicas

union QRhiSwapChainHdrInfo::(unnamed union) limits
QRhiSwapChainHdrInfo::LimitsType limitsType
QRhiSwapChainHdrInfo::LuminanceBehavior luminanceBehavior
float sdrWhiteLevel

Descripción detallada

Para realizar un mapeo de tonos compatible con HDR, en el que el rango de destino no es [0,1], a menudo es necesario conocer la luminancia máxima de la pantalla a la que está asociada la ventana de la cadena de intercambio. Aunque esto suele ser configurable por el usuario (piensa en el brillo, el gamma y ajustes similares en los videojuegos), puede resultar muy útil establecer valores por defecto basados en los valores que proporciona la propia pantalla, lo que ofrece un buen punto de partida.

Sin embargo, existen algunos problemas: la información se presenta de formas diferentes en distintas plataformas, mientras que, en el caso de las API gráficas multiplataforma, a menudo no existe ninguna solución asociada, ya que la gestión de dicha información no entra dentro del ámbito de la API (y puede obtenerse, en su caso, a través de otros medios específicos de cada plataforma).

Con Metal en macOS/iOS, las API de la plataforma no exponen valores de luminancia. En su lugar, se proporciona el valor máximo del componente de color, que sería 1,0 en una configuración no HDR. El campo « limitsType » indica qué tipo de información está disponible. Depende entonces de los clientes de « QRhi » acceder a los datos correctos de la unión « limits » y utilizarlos como consideren oportuno.

Con una API como Vulkan, en la que no hay forma de obtener dicha información, los valores son siempre los predeterminados integrados.

Por lo tanto, la estructura devuelta por QRhiSwapChain::hdrInfo() contiene o bien valores predeterminados codificados de forma fija, o bien valores reales recibidos de una API como DXGI (IDXGIOutput6) o Cocoa (NSScreen). Cuando no hay consultas de plataforma disponibles (o se necesita utilizar funciones de la plataforma que quedan fuera del ámbito de QRhi), los valores predeterminados codificados son una luminancia máxima de 1000 nits y un nivel de blanco SDR de 200.

La estructura también expone el comportamiento de luminancia previsto de la plataforma y su compositor, para indicar cómo se trata un valor de componente de color de 1,0 en un búfer de color HDR. En algunos casos será necesario realizar una corrección de color del contenido no HDR compuesto con contenido HDR. Para habilitar esto, se consulta el nivel de blanco SDR al sistema en algunas plataformas (Windows) y se muestra aquí.

Nota: Se trata de una API de RHI con garantías de compatibilidad limitadas; consulta QRhi para obtener más detalles.

Véase también QRhiSwapChain::hdrInfo().

Documentación sobre los tipos de miembros

enum QRhiSwapChainHdrInfo::LimitsType

ConstanteValorDescripción
QRhiSwapChainHdrInfo::LuminanceInNits0Indica que la unión « limits » tiene definida su estructura « luminanceInNits »
QRhiSwapChainHdrInfo::ColorComponentValue1Indica que la unión « limits » tiene la estructura « colorComponentValue » establecida

enum QRhiSwapChainHdrInfo::LuminanceBehavior

ConstanteValorDescripción
QRhiSwapChainHdrInfo::SceneReferred0Indica que el valor de color 1,0 se interpreta como 80 nits. Este es el comportamiento de las ventanas con HDR habilitado en el compositor de Windows. Consulta esta página para obtener más información sobre el HDR en Windows.
QRhiSwapChainHdrInfo::DisplayReferred1Indica que el valor de color 1,0 se interpreta como el valor del blanco SDR. (que puede ser, por ejemplo, 200 nits, pero variará en función del brillo de la pantalla). Este es el comportamiento de las ventanas compatibles con HDR en plataformas de Apple. Consulta esta página para obtener más información sobre el sistema EDR de Apple.

Documentación de variables de miembro

union QRhiSwapChainHdrInfo::(unnamed union) QRhiSwapChainHdrInfo::limits

Contiene los valores reales consultados a la API gráfica o a la plataforma. El tipo de datos viene indicado por ` limitsType`. Se trata, por tanto, de una unión. Actualmente hay dos opciones:

Valores de luminancia en nits:

struct {
    float minLuminance;
    float maxLuminance;
} luminanceInNits;

En Windows, la luminancia mínima y máxima depende del brillo de la pantalla. Aunque esto no es relevante para los ordenadores de sobremesa, en los portátiles el brillo de la pantalla puede cambiar en cualquier momento. Aumentar el brillo implica una disminución de la luminancia máxima. Además, los resultados también pueden depender del «Brillo del contenido HDR» establecido en la vista «Sistema/Pantalla/HDR» de la configuración de Windows, si existe dicho ajuste.

Sin embargo, ten en cuenta que los cambios realizados en el brillo de la pantalla del portátil o en la configuración del sistema mientras la aplicación está en ejecución no se reflejan necesariamente en los valores devueltos, lo que significa que volver a llamar a hdrInfo() puede seguir devolviendo el mismo rango de luminancia que antes durante el resto de la vida del proceso. El comportamiento exacto depende de DXGI y Qt no tiene control sobre ello.

Nota: El compositor de Windows funciona en modo «scene-referred» para el contenido HDR. Un valor de componente de color de 1,0 corresponde a una luminancia de 80 nits. Al renderizar contenido que no sea HDR (por ejemplo, elementos de la interfaz de usuario en 2D), a menudo es necesaria la corrección del nivel de blanco. (Por ejemplo, generar el color de fragmento (1, 1, 1) probablemente dará lugar a que se muestre en pantalla un tono de blanco demasiado tenue). Véase sdrWhiteLevel.

Para macOS/iOS, se proporcionan los valores máximos actuales y máximos potenciales de los componentes de color:

struct {
    float maxColorComponentValue;
    float maxPotentialColorComponentValue;
} colorComponentValue;

El valor puede depender del brillo de la pantalla, lo que en los portátiles significa que el resultado puede cambiar en la siguiente llamada a hdrInfo() si se ha modificado el brillo entretanto. El brillo máximo de la pantalla implica un valor de color máximo de 1,0.

Nota: El EDRde Apple se refiere a la pantalla. 1,0 corresponde a un nivel de luminancia del blanco SDR (por ejemplo, 200 nits), cuyo valor varía en función del brillo de la pantalla y, posiblemente, de otros ajustes. El valor exacto de luminancia correspondiente, o la luminancia máxima de la pantalla, no se revelan a las aplicaciones.

Nota: Se ha observado que, en algunos sistemas macOS, los valores de los componentes de color no se establecen inmediatamente en el valor correcto (superior a 1) al iniciar el sistema, pero tienden a cambiar durante o después del primer fotograma.

Véase también QRhiSwapChain::hdrInfo().

QRhiSwapChainHdrInfo::LimitsType QRhiSwapChainHdrInfo::limitsType

Con Metal en macOS/iOS, las API de la plataforma no exponen valores de luminancia. En su lugar, se proporciona el valor máximo del componente de color, que sería 1,0 en una configuración que no sea HDR. Este valor indica qué tipo de información está disponible en limits.

Véase también QRhiSwapChain::hdrInfo().

QRhiSwapChainHdrInfo::LuminanceBehavior QRhiSwapChainHdrInfo::luminanceBehavior

Describe el comportamiento previsto de la plataforma en lo que respecta a los valores de color.

Véase también sdrWhiteLevel.

float QRhiSwapChainHdrInfo::sdrWhiteLevel

En Windows, se trata del nivel de blanco SDR dinámico expresado en nits. El valor depende del brillo de la pantalla (en portátiles) y de los ajustes de «Brillo del contenido SDR o HDR» en la sección «Sistema/Pantalla/HDR» de la configuración de Windows.

Para realizar la corrección del nivel de blanco en contenidos que no sean HDR (SDR), como los elementos de la interfaz de usuario en 2D, multiplica el color final por sdrWhiteLevel / 80,0 siempre que luminanceBehavior sea SceneReferred. (suponiendo que se utilice Windows y un espacio de color sRGB lineal ampliado (scRGB))

En otras plataformas, el valor es siempre un valor predefinido: 200. Es posible que este no coincida con el nivel de blanco SDR real del sistema, pero el valor de esta variable no es relevante en la práctica cuando luminanceBehavior es DisplayReferred, ya que, en ese caso, el valor del componente de color 1,0 se refiere al blanco SDR de forma predeterminada.

Véase también luminanceBehavior.

© 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.