godot-docs/classes/class_directionallight.rst

:github_url: hide

.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
.. DO NOT EDIT THIS FILE, but the DirectionalLight.xml source instead.
.. The source is found in doc/classes or modules/<name>/doc_classes.

.. _class_DirectionalLight:

DirectionalLight
================

**Inherits:** :ref:`Light<class_Light>` **<** :ref:`VisualInstance<class_VisualInstance>` **<** :ref:`Spatial<class_Spatial>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Directional light from a distance, as from the Sun.

Description
-----------

A directional light is a type of :ref:`Light<class_Light>` node that models an infinite number of parallel rays covering the entire scene. It is used for lights with strong intensity that are located far away from the scene to model sunlight or moonlight. The worldspace location of the DirectionalLight transform (origin) is ignored. Only the basis is used to determine light direction.

Tutorials
---------

- :doc:`../tutorials/3d/lights_and_shadows`

Properties
----------

+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_bias_split_scale<class_DirectionalLight_property_directional_shadow_bias_split_scale>` | ``0.25``                    |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`bool<class_bool>`                                         | :ref:`directional_shadow_blend_splits<class_DirectionalLight_property_directional_shadow_blend_splits>`         | ``false``                   |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`ShadowDepthRange<enum_DirectionalLight_ShadowDepthRange>` | :ref:`directional_shadow_depth_range<class_DirectionalLight_property_directional_shadow_depth_range>`           | ``0``                       |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_max_distance<class_DirectionalLight_property_directional_shadow_max_distance>`         | ``100.0``                   |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`ShadowMode<enum_DirectionalLight_ShadowMode>`             | :ref:`directional_shadow_mode<class_DirectionalLight_property_directional_shadow_mode>`                         | ``2``                       |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_normal_bias<class_DirectionalLight_property_directional_shadow_normal_bias>`           | ``0.8``                     |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_split_1<class_DirectionalLight_property_directional_shadow_split_1>`                   | ``0.1``                     |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_split_2<class_DirectionalLight_property_directional_shadow_split_2>`                   | ``0.2``                     |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | :ref:`directional_shadow_split_3<class_DirectionalLight_property_directional_shadow_split_3>`                   | ``0.5``                     |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+
| :ref:`float<class_float>`                                       | shadow_bias                                                                                                     | ``0.1`` *(parent override)* |
+-----------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------+-----------------------------+

Enumerations
------------

.. _enum_DirectionalLight_ShadowMode:

.. _class_DirectionalLight_constant_SHADOW_ORTHOGONAL:

.. _class_DirectionalLight_constant_SHADOW_PARALLEL_2_SPLITS:

.. _class_DirectionalLight_constant_SHADOW_PARALLEL_4_SPLITS:

enum **ShadowMode**:

- **SHADOW_ORTHOGONAL** = **0** --- Renders the entire scene's shadow map from an orthogonal point of view. May result in blockier shadows on close objects.

- **SHADOW_PARALLEL_2_SPLITS** = **1** --- Splits the view frustum in 2 areas, each with its own shadow map.

- **SHADOW_PARALLEL_4_SPLITS** = **2** --- Splits the view frustum in 4 areas, each with its own shadow map.

----

.. _enum_DirectionalLight_ShadowDepthRange:

.. _class_DirectionalLight_constant_SHADOW_DEPTH_RANGE_STABLE:

.. _class_DirectionalLight_constant_SHADOW_DEPTH_RANGE_OPTIMIZED:

enum **ShadowDepthRange**:

- **SHADOW_DEPTH_RANGE_STABLE** = **0** --- Keeps the shadow stable when the camera moves, at the cost of lower effective shadow resolution.

- **SHADOW_DEPTH_RANGE_OPTIMIZED** = **1** --- Tries to achieve maximum shadow resolution. May result in saw effect on shadow edges.

Property Descriptions
---------------------

.. _class_DirectionalLight_property_directional_shadow_bias_split_scale:

- :ref:`float<class_float>` **directional_shadow_bias_split_scale**

+-----------+------------------+
| *Default* | ``0.25``         |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

Amount of extra bias for shadow splits that are far away. If self-shadowing occurs only on the splits far away, increasing this value can fix them.

----

.. _class_DirectionalLight_property_directional_shadow_blend_splits:

- :ref:`bool<class_bool>` **directional_shadow_blend_splits**

+-----------+---------------------------+
| *Default* | ``false``                 |
+-----------+---------------------------+
| *Setter*  | set_blend_splits(value)   |
+-----------+---------------------------+
| *Getter*  | is_blend_splits_enabled() |
+-----------+---------------------------+

If ``true``, shadow detail is sacrificed in exchange for smoother transitions between splits.

----

.. _class_DirectionalLight_property_directional_shadow_depth_range:

- :ref:`ShadowDepthRange<enum_DirectionalLight_ShadowDepthRange>` **directional_shadow_depth_range**

+-----------+-------------------------------+
| *Default* | ``0``                         |
+-----------+-------------------------------+
| *Setter*  | set_shadow_depth_range(value) |
+-----------+-------------------------------+
| *Getter*  | get_shadow_depth_range()      |
+-----------+-------------------------------+

Optimizes shadow rendering for detail versus movement. See :ref:`ShadowDepthRange<enum_DirectionalLight_ShadowDepthRange>`.

----

.. _class_DirectionalLight_property_directional_shadow_max_distance:

- :ref:`float<class_float>` **directional_shadow_max_distance**

+-----------+------------------+
| *Default* | ``100.0``        |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

The maximum distance for shadow splits.

----

.. _class_DirectionalLight_property_directional_shadow_mode:

- :ref:`ShadowMode<enum_DirectionalLight_ShadowMode>` **directional_shadow_mode**

+-----------+------------------------+
| *Default* | ``2``                  |
+-----------+------------------------+
| *Setter*  | set_shadow_mode(value) |
+-----------+------------------------+
| *Getter*  | get_shadow_mode()      |
+-----------+------------------------+

The light's shadow rendering algorithm. See :ref:`ShadowMode<enum_DirectionalLight_ShadowMode>`.

----

.. _class_DirectionalLight_property_directional_shadow_normal_bias:

- :ref:`float<class_float>` **directional_shadow_normal_bias**

+-----------+------------------+
| *Default* | ``0.8``          |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

Can be used to fix special cases of self shadowing when objects are perpendicular to the light.

----

.. _class_DirectionalLight_property_directional_shadow_split_1:

- :ref:`float<class_float>` **directional_shadow_split_1**

+-----------+------------------+
| *Default* | ``0.1``          |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

The distance from camera to shadow split 1. Relative to :ref:`directional_shadow_max_distance<class_DirectionalLight_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight_property_directional_shadow_mode>` is ``SHADOW_PARALLEL_2_SPLITS`` or ``SHADOW_PARALLEL_4_SPLITS``.

----

.. _class_DirectionalLight_property_directional_shadow_split_2:

- :ref:`float<class_float>` **directional_shadow_split_2**

+-----------+------------------+
| *Default* | ``0.2``          |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

The distance from shadow split 1 to split 2. Relative to :ref:`directional_shadow_max_distance<class_DirectionalLight_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight_property_directional_shadow_mode>` is ``SHADOW_PARALLEL_2_SPLITS`` or ``SHADOW_PARALLEL_4_SPLITS``.

----

.. _class_DirectionalLight_property_directional_shadow_split_3:

- :ref:`float<class_float>` **directional_shadow_split_3**

+-----------+------------------+
| *Default* | ``0.5``          |
+-----------+------------------+
| *Setter*  | set_param(value) |
+-----------+------------------+
| *Getter*  | get_param()      |
+-----------+------------------+

The distance from shadow split 2 to split 3. Relative to :ref:`directional_shadow_max_distance<class_DirectionalLight_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight_property_directional_shadow_mode>` is ``SHADOW_PARALLEL_4_SPLITS``.