En esta página

Uso de la iluminación basada en imágenes

Introducción

Qt Quick 3D admite IBL (iluminación basada en imágenes) para iluminar escenas o materiales individuales.

La IBL es una técnica de iluminación que permite iluminar escenas con imágenes. Esto resulta especialmente útil cuando se desea crear iluminación y reflejos realistas en escenas de interior y exterior.

Se puede utilizar cualquier archivo de imagen para IBL, pero se recomienda utilizar imágenes HDR (alto rango dinámico) de 360º. Las imágenes HDR tienen un rango dinámico mucho mayor que, por ejemplo, las imágenes JPEG o PNG. Un rango dinámico más alto proporciona una iluminación más realista gracias a una amplia gama de niveles de luminancia, desde muy brillantes hasta muy oscuros.

El siguiente ejemplo muestra el efecto de iluminación sobre un objeto utilizando una imagen HDR frente a una sola luz direccional:

LuzMaterial dieléctrico lisoMaterial dieléctrico rugosoMaterial metálico lisoMaterial metálico rugoso
Luz unidireccional

Esfera lisa con una única luz direccional

Esfera rugosa con una única luz direccional

Esfera metálica lisa con una luz unidireccional

Esfera metálica rugosa con una única luz direccional

Luz basada en imágenes

Esfera lisa con iluminación ambiental basada en imágenes

Esfera rugosa con iluminación ambiental basada en imágenes

Esfera metálica lisa con iluminación ambiental basada en imágenes

Esfera metálica rugosa con iluminación ambiental basada en imágenes

Iluminación de la escena

Para iluminar un objeto « scene » utilizando una imagen, debes añadir la imagen como una « Texture » a la propiedad « lightProbe ».

lightProbe: Texture {
    source: "maps/OpenfootageNET_garage-1024.hdr"
}

Una vez seleccionada la imagen, la IBL queda configurada para tu escena. Por defecto, todos los modelos de la escena quedan iluminados por la sonda de luz.

Nota: Tambiénpuedes combinar IBL con cualquier otra fuente de luz para complementar el efecto de iluminación sobre un objeto.

Ahora que ya tienes el IBL configurado para tu escena, echemos un vistazo a las diferentes propiedades de la sonda. En muchos casos, los valores por defecto ofrecen un resultado satisfactorio, pero puedes ajustar los siguientes valores de las propiedades en función de la imagen y del resultado deseado:

  • Exposure La cantidad de luz emitida por la sonda de luz.
  • Horizon Cut-Off Al aumentar el valor, se añade oscuridad (negro) a la mitad inferior del entorno, lo que hace que la iluminación provenga predominantemente de la parte superior de la imagen (y elimina reflejos específicos de la mitad inferior).
  • Orientation Esta propiedad define la orientación de la sonda de luz. La orientación se define en términos de ángulos de Euler en grados sobre los ejes x, y y z.
PropiedadMaterial metálicoMaterial dieléctrico
Ajustes predeterminados

Esfera metálica lisa con iluminación ambiental basada en imágenes

Esfera lisa con iluminación ambiental basada en imágenes

Exposición

Esfera metálica lisa que muestra el ajuste de la exposición de la sonda de luz

Esfera lisa que muestra el ajuste de la exposición de la sonda de luz

Corte del horizonte

Esfera metálica lisa que muestra el ajuste del horizonte de la sonda de luz

Esfera lisa que muestra el ajuste del horizonte de la sonda de luz

Orientación

Esfera metálica lisa que muestra la orientación de la sonda de luz

Esfera lisa que muestra la orientación de la sonda de luz

Iluminación del material

Para utilizar la iluminación basada en imágenes solo en un material en lugar de en toda la escena, o para utilizar una sonda de luz independiente para un modelo ya iluminado mediante iluminación basada en imágenes, configura la imagen como la « light probe » (Sonda de luz del material) para dicho material.

Una vez que hayas seguido los pasos anteriores, dispondrás de una sonda de luz independiente configurada para el material. Esta sonda de luz anula la sonda de luz de la escena, si se ha especificado alguna.

Generación previa del mapa cúbico IBL

Cuando se utiliza IBL, la aplicación debe generar un mapa cúbico para la imagen IBL. Por defecto, esto ocurre durante el inicio de la aplicación y puede resultar bastante lento, especialmente en dispositivos integrados y móviles. Por lo tanto, es posible pregenerar este mapa cúbico utilizando Balsam. Basta con ejecutar Balsam con el archivo .hdr como entrada y este generará un archivo de mapa cúbico con el mismo nombre que el de entrada, pero con la extensión .ktx. A continuación, se puede hacer referencia a este archivo en el ` Texture` asociado a la propiedad `lightProbe`, y Qt cargará el mapa cúbico pregenerado sin ningún procesamiento costoso en tiempo de ejecución.

Generación manual

A modo de ejemplo, supongamos que la aplicación utiliza una imagen .hdr para sus sondas de luz o para el skybox:

View3D {
    environment: SceneEnvironment {
        backgroundMode: SceneEnvironment.SkyBox
        lightProbe: Texture {
            source: "environment.hdr"
        }
        probeOrientation: Qt.vector3d(0, -90, 0)
    }
    // ...
}

Esto funciona perfectamente, siempre que environment.hdr esté disponible en tiempo de ejecución. Sin embargo, cargar la imagen .hdr implica un preprocesamiento costoso. Esto se puede evitar ejecutando:

balsam environment.hdr

El resultado es un nuevo archivo environment.ktx. Distribuir este archivo en lugar del archivo .hdr y cambiar la fuente de textura proporciona tiempos de carga significativamente más rápidos.

lightProbe: Texture {
    source: "environment.ktx"
}

Cocción en tiempo de compilación mediante CMake

Ejecutar manualmente balsam en los recursos no siempre es lo ideal. Por lo tanto, se recomienda que las aplicaciones utilicen CMake para realizar automáticamente la misma tarea en el momento de la compilación de la aplicación.

Esto se hace utilizando la función de CMake `qt_add_lightprobe_images() `, proporcionada por el componente Quick3D del paquete Qt6:

...
find_package(Qt6 COMPONENTS Quick3D)
...
qt_add_lightprobe_images(application_target "ibl_assets"
    PREFIX
        "/ibl"
    FILES
        "environment.hdr"
)

Sustituye application_target por el objetivo adecuado. De este modo, ya no es necesario ejecutar «balsam» manualmente sobre «environment.hdr», y tampoco es preciso incluir el archivo .hdr con la aplicación. En su lugar, durante la compilación se invocará «balsam» automáticamente y se añadirá un archivo «environment.ktx» a los recursos de la aplicación en :/ibl/environment.ktx. A continuación, el « Texture » de «lightProbe» debe hacer referencia a este archivo.

lightProbe: Texture {
    source: "qrc:/ibl/environment.ktx"
}

Nota: Al configurar PREFIX de modo que el nombre final en el sistema de recursos tenga una ruta que coincida con la ubicación del archivo .qml, se permite utilizar una ruta de origen relativa en lugar de tener que proporcionar una ruta absoluta con el esquema qrc.

Además de PREFIX, también está disponible la palabra clave BASE. Su comportamiento es similar al de qt_add_resources(). Por ejemplo, lo siguiente da lugar a la generación de :/ibl/maps/environment.ktx:

qt_add_lightprobe_images(application_target "ibl_assets"
    PREFIX
        "/ibl"
    BASE
        "../data/shared"
    FILES
        "../data/shared/maps/environment.hdr"
)

Al igual que en `qt_add_shaders()`, la palabra clave `OUTPUTS` permite especificar un nombre totalmente personalizado para el archivo en el sistema de recursos. Por ejemplo, el siguiente código también genera ` :/ibl/maps/environment.ktx`:

qt_add_lightprobe_images(application_target "ibl_assets"
    PREFIX
        "/ibl"
    FILES
        "../data/shared/maps/environment.hdr"
    OUTPUTS
        "maps/environment.ktx"
)

Nota: Por cada entrada de la lista FILES, debe haber una entrada correspondiente en OUTPUTS.

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