En esta página

SkyMaterial QML Type

Crea un cielo procedural y genera datos de iluminación basados en imágenes. Más...

Import Statement: import QtQuick3D
Since: Qt 6.12

Propiedades

Descripción detallada

SkyMaterial representa un entorno de cielo en un mapa cúbico utilizando código de sombreador de fragmentos personalizado. El mapa cúbico resultante puede filtrarse opcionalmente y utilizarse como iluminación basada en imágenes (IBL) para el renderizado basado en la física.

El sombreador se evalúa para las seis caras del mapa cúbico y puede implementar cielos procedimentales arbitrarios, degradados o modelos analíticos.

El cubemap generado se utiliza tanto como fondo de la escena visible como fuente de iluminación basada en imágenes cuando está habilitada.

Nota: Los cambios en el código o las propiedades del sombreador pueden tardar un fotograma o más en reflejarse en la IBL generada.

Sombreador

El sombreador tiene acceso a la variable integrada ` qt_eyeDir ` (vec3), que proporciona el vector de dirección no normalizado desde el centro del mapa cúbico hasta la dirección de la muestra actual.

El sombreador de fragmentos debe definir un punto de entrada MAIN(), que se ejecuta para cada fragmento generado durante el renderizado del mapa cúbico.

El color final del píxel debe escribirse en FRAGCOLOR (vec4), que es la variable de salida del sombreador de fragmentos.

Un ejemplo mínimo de sombreador:

void MAIN()
{
    vec3 dir = normalize(qt_eyeDir);

    // Output color (encoded direction as RGB)
    FRAGCOLOR = vec4(dir * 0.5 + 0.5, 1.0);
}

Las propiedades QML personalizadas declaradas en SkyMaterial se exponen automáticamente como uniformes en el sombreador de fragmentos. El nombre de la propiedad debe coincidir con el nombre de la variable GLSL. No se requiere ninguna declaración explícita de uniformes.

Se admiten las siguientes correspondencias de tipos:

Tipo QMLTipo de sombreadorNotas
real, int, boolfloat, int, bool
colorvec4sRGB se convierte a espacio lineal
vector2dvec2
vector3dvec3
vector4dvec4
matriz4x4mat4
cuaterniónvec4w almacena el componente escalar
rectvec4
punto, tamañovec2
TextureInputsampler2D

Documentación de propiedades

enableIBL : bool [default: true, since 6.12]

Determina si el mapa cúbico del cielo generado se utiliza para la iluminación basada en imágenes.

Cuando está activada, el motor genera mapas de radiancia e irradiancia filtrados que se utilizan para la iluminación ambiental y los reflejos en el renderizado basado en la física.

Cuando está desactivada, el cielo solo se renderiza como fondo visual y no se realiza ningún preprocesamiento IBL.

Esta propiedad se introdujo en Qt 6.12.

Véase también SceneEnvironment::lightProbe.

fragmentShader : url [since 6.12]

Especifica un sombreador de fragmentos cargado desde un archivo o una URL de recurso.

Si se establecen tanto «fragmentShader» como « fragmentShaderCode », tiene prioridad « fragmentShaderCode ».

Si no se especifica ningún sombreador, se utiliza un sombreador de depuración integrado.

Esta propiedad se introdujo en Qt 6.12.

Véase también ` fragmentShaderCode`.

fragmentShaderCode : string [since 6.12]

Especifica el código fuente del sombreador de fragmentos en línea.

Se comporta de forma idéntica a ` fragmentShader ` y utiliza el mismo modelo de ejecución, las mismas funciones integradas y la misma asignación automática de propiedades a variables uniformes.

Si se definen tanto « fragmentShader » como «fragmentShaderCode», esta propiedad tiene prioridad.

Esta propiedad se introdujo en Qt 6.12.

Véase también ` fragmentShader`.

iblRenderFrames : int [default: 0, since 6.12]

Determina cómo se distribuye el funcionamiento del prefiltro IBL entre los fotogramas.

  • 0 — Todo en un solo fotograma: la acumulación de muestras, la normalización y la irradiancia se evalúan en el mismo fotograma.
  • N ≥ 1 — Las muestras de « iblSampleCount » se reparten en N fotogramas de corte (ceil(iblSampleCount / N) muestras por fotograma), seguidos de un fotograma dedicado a la normalización y a la irradiancia.

Los valores más altos reparten el coste del prefiltro GGX entre más fotogramas, lo cual resulta útil cuando el cielo cambia con poca frecuencia y se requiere un « iblSampleCount » elevado para garantizar la calidad.

Nota: Esta propiedad no tiene ningún efecto cuando el valor de « enableIBL » es « false ».

Esta propiedad se introdujo en Qt 6.12.

Véase también « iblSampleCount » y « enableIBL ».

iblSampleCount : int [default: 32, since 6.12]

El número total de muestras de importancia GGX evaluadas por texel de salida del mapa de radiancia filtrado. Los valores más altos reducen el efecto de destello en elementos de alta frecuencia, como el disco solar, a costa del tiempo de generación.

Los valores se limitan al intervalo [1, 1024].

Nota: Esta propiedad no tiene ningún efecto cuando « enableIBL » es « false ».

Esta propiedad se introdujo en Qt 6.12.

Véase también « iblRenderFrames » y « enableIBL ».

radianceMapSize : int [default: 512, since 6.12]

Especifica la resolución del mapa cúbico del entorno generado que se utiliza para la iluminación basada en imágenes y las sondas de reflexión.

Los valores más altos mejoran la nitidez de los reflejos y la calidad de la iluminación, especialmente en materiales brillantes, pero aumentan el consumo de memoria y el coste de renderizado.

Los valores se redondean a la potencia de dos más cercana y se limitan al rango [8, 2048].

Nota: Cuando « skyboxMode » está configurado en un valor « ScreenSpace », el cielo visible se evalúa directamente en pantalla y esta propiedad solo afecta al cubemap de IBL/reflexión. Con « SkyMaterial.Cubemap », también determina la nitidez del fondo visible. Cuando « enableIBL » es « false », « skyboxMode » es un valor « ScreenSpace » y no hay sondas de reflexión presentes, no se genera ningún cubemap.

Esta propiedad se introdujo en Qt 6.12.

Véase también skyboxMode y enableIBL.

skyboxMode : enumeration [default: SkyMaterial.Cubemap, since 6.12]

Selecciona lo que el ` SkyMaterial ` genera como fondo visible.

ConstanteDescripción
SkyMaterial.CubemapEl fondo muestrea el mapa cúbico de radiancia (el mismo cubo que se utiliza para la iluminación basada en imágenes), cuya resolución se rige por radianceMapSize. En el caso de un cielo estático, el cubo se renderiza una vez y luego se muestrea de forma económica en cada fotograma, por lo que este es el coste por fotograma más bajo cuando solo se mueve la cámara. La nitidez tiene un límite máximo de radianceMapSize.
SkyMaterial.ScreenSpaceFullEl sombreador del cielo se evalúa directamente en pantalla a la resolución completa de la ventana de visualización en cada fotograma (la opción más nítida, pero también la más costosa).
SkyMaterial.ScreenSpaceHalfEvaluación directa en el espacio de pantalla a media resolución por eje (una cuarta parte de los píxeles), escalada al área de visualización.
SkyMaterial.ScreenSpaceQuarterEvaluación directa en el espacio de pantalla a un cuarto de resolución por eje (una dieciseisava parte de los píxeles), escalada al visor.

Los modos « ScreenSpace » desacoplan el fondo visible del cubo IBL y son los más adecuados para cielos dinámicos (por ejemplo, sol en movimiento, nubes volumétricas animadas); « Cubemap » es la mejor opción para cielos estáticos. « Cubemap » fuerza la generación del mapa de cubo incluso cuando « enableIBL » está en « false ».

Esta propiedad se introdujo en Qt 6.12.

Véase también radianceMapSize y enableIBL.

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