En esta página

DirectionalLight QML Type

Define una luz direccional en la escena. Más...

Import Statement: import QtQuick3D
Inherits:

Light

Propiedades

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.

Círculo verde que muestra la luz direccional que se emite a lo largo del eje Z

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
}

Círculo verde con sombreado que muestra una luz direccional girada

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.