- Qt 6.12
- Qt Quick 3D
- QML Types
- DirectionalLight
- Qt Quick 3D | Commercial or GPLv3

# DirectionalLight QML Type

Defines a directional light in the scene. More...

Import Statement: | `import QtQuick3D`
Inherits: | Light

- List of all members, including inherited members

## Properties

- 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)`

## Detailed Description

The directional light emits light in one direction from an unidentifiable source located infinitely far away. This is similar to the way sunlight works in real life. A directional light has infinite range and does not diminish.

If castsShadow is enabled, shadows will be parallel to the light direction.

A directional light effectively have no position, so moving it does not have any effect. The light will always be emitted in the direction of the light's Z axis.

Rotating the light along its X or Y axis will change the direction of the light emission.

Scaling a directional light will only have an effect in the following cases:

- If Z scale is set to a negative number, the light will be emitted in the opposite direction.
- If the scale of any axis is set to 0, the light will be emitted along the world's Z axis.

  Note: Rotating the light will then have no effect.

Let's look at a simple example:

     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
             }
         }
     }

Here the DirectionalLight uses the default `white` color, emitting in the direction of the DirectionalLight node's Z axis.

Rotating 60 degrees around the X axis would lead to the following. Instead of emitting straight in the direction of the Z axis, the light is now pointing 60 degrees "down":

     DirectionalLight {
         eulerRotation.x: 60
     }

For further usage examples, see Qt Quick 3D - Lights Example.

See also PointLight, SpotLight, and Shadow Mapping.

## Property Documentation

### csmBlendRatio : real `[since 6.8]`

This property defines how much of the shadow of any cascade should be blended together with the previous one.

Range: `[0.0, 1.0]`

Default value: `0.05`

This property was introduced in Qt 6.8.

### csmNumSplits : int `[since 6.8]`

This property defines the number of splits the frustum should be split by when rendering the shadowmap. No splits means that the shadowmap will be rendered so that it covers the bounding box of all shadow casting and receiving objects.

Range: `[0, 3]`

Default value: `0`

This property was introduced in Qt 6.8.

See also csmSplit1, csmSplit2, and csmSplit3.

### csmSplit1 : real `[since 6.8]`

This property defines where the first cascade of the shadow map split will occur when CSM is active.

Range: `[0.0, 1.0]`

Default value: `0.1`

Note: This property is only used when DirectionalLight::csmNumSplits is greater than `0`.

This property was introduced in Qt 6.8.

See also csmSplit2 and csmSplit3.

### csmSplit2 : real `[since 6.8]`

This property defines where the second cascade of the shadow map split will occur when CSM is active.

Range: `[0.0, 1.0]`

Default value: `0.25`

Note: This property is only used when DirectionalLight::csmNumSplits is greater than `1`.

This property was introduced in Qt 6.8.

See also csmSplit1 and csmSplit3.

### csmSplit3 : real `[since 6.8]`

This property defines where the third cascade of the shadow map split will occur when CSM is active.

Range: `[0.0, 1.0]`

Default value: `0.5`

Note: This property is only used when DirectionalLight::csmNumSplits is greater than `2`.

This property was introduced in Qt 6.8.

See also csmSplit1 and csmSplit2.

### lockShadowmapTexels : bool `[since 6.9]`

When this property is enabled, the shadowmap texels are "locked" in position in the world eliminating shadow edge shimmering at the cost of bigger shadowmap texels. It works by using uniform sized, and texel aligned shadowmaps for each cascade.

Default value: `false`

This property was introduced in Qt 6.9.