godot-docs/classes/class_directionallight3d.rst

:github_url: hide

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

.. _class_DirectionalLight3D:

DirectionalLight3D
==================

**Inherits:** :ref:`Light3D<class_Light3D>` **<** :ref:`VisualInstance3D<class_VisualInstance3D>` **<** :ref:`Node3D<class_Node3D>` **<** :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:`Light3D<class_Light3D>` 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 DirectionalLight3D transform (origin) is ignored. Only the basis is used to determine light direction.

Tutorials
---------

- :doc:`Lights and shadows <../tutorials/3d/lights_and_shadows>`

Properties
----------

+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                               | :ref:`directional_shadow_blend_splits<class_DirectionalLight3D_property_directional_shadow_blend_splits>` | ``false``                                                              |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_fade_start<class_DirectionalLight3D_property_directional_shadow_fade_start>`     | ``0.8``                                                                |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_max_distance<class_DirectionalLight3D_property_directional_shadow_max_distance>` | ``100.0``                                                              |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`ShadowMode<enum_DirectionalLight3D_ShadowMode>` | :ref:`directional_shadow_mode<class_DirectionalLight3D_property_directional_shadow_mode>`                 | ``2``                                                                  |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_pancake_size<class_DirectionalLight3D_property_directional_shadow_pancake_size>` | ``20.0``                                                               |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_split_1<class_DirectionalLight3D_property_directional_shadow_split_1>`           | ``0.1``                                                                |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_split_2<class_DirectionalLight3D_property_directional_shadow_split_2>`           | ``0.2``                                                                |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | :ref:`directional_shadow_split_3<class_DirectionalLight3D_property_directional_shadow_split_3>`           | ``0.5``                                                                |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`float<class_float>`                             | shadow_bias                                                                                               | ``0.1`` (overrides :ref:`Light3D<class_Light3D_property_shadow_bias>`) |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+
| :ref:`bool<class_bool>`                               | :ref:`use_in_sky_only<class_DirectionalLight3D_property_use_in_sky_only>`                                 | ``false``                                                              |
+-------------------------------------------------------+-----------------------------------------------------------------------------------------------------------+------------------------------------------------------------------------+

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

.. _enum_DirectionalLight3D_ShadowMode:

.. _class_DirectionalLight3D_constant_SHADOW_ORTHOGONAL:

.. _class_DirectionalLight3D_constant_SHADOW_PARALLEL_2_SPLITS:

.. _class_DirectionalLight3D_constant_SHADOW_PARALLEL_4_SPLITS:

enum **ShadowMode**:

- **SHADOW_ORTHOGONAL** = **0** --- Renders the entire scene's shadow map from an orthogonal point of view. This is the fastest directional shadow mode. May result in blurrier shadows on close objects.

- **SHADOW_PARALLEL_2_SPLITS** = **1** --- Splits the view frustum in 2 areas, each with its own shadow map. This shadow mode is a compromise between :ref:`SHADOW_ORTHOGONAL<class_DirectionalLight3D_constant_SHADOW_ORTHOGONAL>` and :ref:`SHADOW_PARALLEL_4_SPLITS<class_DirectionalLight3D_constant_SHADOW_PARALLEL_4_SPLITS>` in terms of performance.

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

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

.. _class_DirectionalLight3D_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. Enabling shadow blend splitting also has a moderate performance cost. This is ignored when :ref:`directional_shadow_mode<class_DirectionalLight3D_property_directional_shadow_mode>` is :ref:`SHADOW_ORTHOGONAL<class_DirectionalLight3D_constant_SHADOW_ORTHOGONAL>`.

----

.. _class_DirectionalLight3D_property_directional_shadow_fade_start:

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

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

Proportion of :ref:`directional_shadow_max_distance<class_DirectionalLight3D_property_directional_shadow_max_distance>` at which point the shadow starts to fade. At :ref:`directional_shadow_max_distance<class_DirectionalLight3D_property_directional_shadow_max_distance>`, the shadow will disappear. The default value is a balance between smooth fading and distant shadow visibility. If the camera moves fast and the :ref:`directional_shadow_max_distance<class_DirectionalLight3D_property_directional_shadow_max_distance>` is low, consider lowering :ref:`directional_shadow_fade_start<class_DirectionalLight3D_property_directional_shadow_fade_start>` below ``0.8`` to make shadow transitions less noticeable. On the other hand, if you tuned :ref:`directional_shadow_max_distance<class_DirectionalLight3D_property_directional_shadow_max_distance>` to cover the entire scene, you can set :ref:`directional_shadow_fade_start<class_DirectionalLight3D_property_directional_shadow_fade_start>` to ``1.0`` to prevent the shadow from fading in the distance (it will suddenly cut off instead).

----

.. _class_DirectionalLight3D_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. Increasing this value will make directional shadows visible from further away, at the cost of lower overall shadow detail and performance (since more objects need to be included in the directional shadow rendering).

----

.. _class_DirectionalLight3D_property_directional_shadow_mode:

- :ref:`ShadowMode<enum_DirectionalLight3D_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_DirectionalLight3D_ShadowMode>`.

----

.. _class_DirectionalLight3D_property_directional_shadow_pancake_size:

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

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

Sets the size of the directional shadow pancake. The pancake offsets the start of the shadow's camera frustum to provide a higher effective depth resolution for the shadow. However, a high pancake size can cause artifacts in the shadows of large objects that are close to the edge of the frustum. Reducing the pancake size can help. Setting the size to ``0`` turns off the pancaking effect.

----

.. _class_DirectionalLight3D_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_DirectionalLight3D_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight3D_property_directional_shadow_mode>` is :ref:`SHADOW_PARALLEL_2_SPLITS<class_DirectionalLight3D_constant_SHADOW_PARALLEL_2_SPLITS>` or :ref:`SHADOW_PARALLEL_4_SPLITS<class_DirectionalLight3D_constant_SHADOW_PARALLEL_4_SPLITS>`.

----

.. _class_DirectionalLight3D_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_DirectionalLight3D_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight3D_property_directional_shadow_mode>` is :ref:`SHADOW_PARALLEL_4_SPLITS<class_DirectionalLight3D_constant_SHADOW_PARALLEL_4_SPLITS>`.

----

.. _class_DirectionalLight3D_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_DirectionalLight3D_property_directional_shadow_max_distance>`. Only used when :ref:`directional_shadow_mode<class_DirectionalLight3D_property_directional_shadow_mode>` is :ref:`SHADOW_PARALLEL_4_SPLITS<class_DirectionalLight3D_constant_SHADOW_PARALLEL_4_SPLITS>`.

----

.. _class_DirectionalLight3D_property_use_in_sky_only:

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

+-----------+---------------------+
| *Default* | ``false``           |
+-----------+---------------------+
| *Setter*  | set_sky_only(value) |
+-----------+---------------------+
| *Getter*  | is_sky_only()       |
+-----------+---------------------+

If ``true``, this ``DirectionalLight3D`` will not be used for anything except sky shaders. Use this for lights that impact your sky shader that you may want to hide from affecting the rest of the scene. For example, you may want to enable this when the sun in your sky shader falls below the horizon.

.. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)`
.. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)`
.. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)`
.. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)`
.. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`
.. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)`