DirectionalLight QML Type
Define una luz direccional en la escena. Más...
| Import Statement: | import QtQuick3D |
| Inherits: |
Propiedades
- csmBlendRatio : real
(since 6.8) - csmNumSplits : int
(since 6.8) - csmSplit1 : real
(since 6.8) - csmSplit2 : real
(since 6.8) - csmSplit3 : real
(since 6.8) - lockShadowmapTexels : bool
(since 6.9)
Descripción detallada
La luz direccional emite luz en una sola dirección desde una fuente no identificable situada a una distancia infinita. Esto es similar al funcionamiento de la luz solar en la vida real. Una luz direccional tiene un alcance infinito y no se atenúa.
Si se activa la opción « castsShadow », las sombras serán paralelas a la dirección de la luz.
Una luz direccional no tiene, en la práctica, ninguna posición, por lo que moverla no tiene ningún efecto. La luz siempre se emitirá en la dirección del eje Z de la luz.
Al girar la luz a lo largo de su eje X o Y, cambiará la dirección de emisión de la luz.
El escalado de una luz direccional solo tendrá efecto en los siguientes casos:
- Si la escala Z se establece en un número negativo, la luz se emitirá en la dirección opuesta.
- Si la escala de cualquier eje se establece en 0, la luz se emitirá a lo largo del eje Z del mundo.
Nota: En ese caso,girar la luz no tendrá ningún efecto.
Veamos un ejemplo sencillo:
import QtQuick
import QtQuick3D
View3D {
anchors.fill: parent
PerspectiveCamera { z: 600 }
DirectionalLight {
}
Model {
source: "#Sphere"
scale: Qt.vector3d(4, 4, 4)
materials: PrincipledMaterial {
baseColor: "#40c060"
roughness: 0.1 // make specular highlight visible
}
}
}Aquí, la luz direccional (DirectionalLight) utiliza el color predeterminado « white » y emite en la dirección del eje Z del nodo DirectionalLight.

Girarla 60 grados alrededor del eje X daría lugar a lo siguiente. En lugar de emitirse directamente en la dirección del eje Z, la luz apunta ahora 60 grados «hacia abajo»:
DirectionalLight {
eulerRotation.x: 60
}
Para ver más ejemplos de uso, consulta Qt Quick 3D - Ejemplo de luces.
Véase también PointLight, SpotLight y Mapeado de sombras.
Documentación de propiedades
csmBlendRatio : real [since 6.8]
Esta propiedad define en qué medida la sombra de cualquier cascada debe fusionarse con la anterior.
Rango: [0.0, 1.0]
Valor por defecto: 0.05
Esta propiedad se introdujo en Qt 6.8.
csmNumSplits : int [since 6.8]
Esta propiedad define el número de divisiones en las que debe dividirse el frustum al renderizar el mapa de sombras. Si no se especifica ningún número de divisiones, el mapa de sombras se renderizará de manera que cubra la caja delimitadora de todos los objetos que proyectan y reciben sombras.
Rango: [0, 3]
Valor por defecto: 0
Esta propiedad se introdujo en Qt 6.8.
Véase también csmSplit1, csmSplit2 y csmSplit3.
csmSplit1 : real [since 6.8]
Esta propiedad define dónde se producirá la primera cascada de la división del mapa de sombras cuando el CSM esté activo.
Rango: [0.0, 1.0]
Valor por defecto: 0.1
Nota: Esta propiedad solo se utiliza cuando « DirectionalLight::csmNumSplits » es mayor que « 0 ».
Esta propiedad se introdujo en Qt 6.8.
Véase también « csmSplit2 » y « csmSplit3 ».
csmSplit2 : real [since 6.8]
Esta propiedad define dónde se producirá la segunda cascada de la división del mapa de sombras cuando el CSM esté activo.
Rango: [0.0, 1.0]
Valor por defecto: 0.25
Nota: Esta propiedad solo se utiliza cuando « DirectionalLight::csmNumSplits » es mayor que « 1 ».
Esta propiedad se introdujo en Qt 6.8.
Véase también « csmSplit1 » y « csmSplit3 ».
csmSplit3 : real [since 6.8]
Esta propiedad define dónde se producirá la tercera cascada de la división del mapa de sombras cuando el CSM esté activo.
Rango: [0.0, 1.0]
Valor por defecto: 0.5
Nota: Esta propiedad solo se utiliza cuando « DirectionalLight::csmNumSplits » es mayor que « 2 ».
Esta propiedad se introdujo en Qt 6.8.
Véase también « csmSplit1 » y « csmSplit2 ».
lockShadowmapTexels : bool [since 6.9]
Cuando esta propiedad está activada, los texeles del mapa de sombras quedan «fijados» en su posición en el mundo, lo que elimina el parpadeo de los bordes de las sombras a cambio de un mayor tamaño de los texeles del mapa de sombras. Funciona utilizando mapas de sombras de tamaño uniforme y alineados por texel para cada cascada.
Valor por defecto: false
Esta propiedad se introdujo en Qt 6.9.
© 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.