godot-docs/classes/class_lightmapgi.rst

:github_url: hide

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

.. _class_LightmapGI:

LightmapGI
==========

**Inherits:** :ref:`VisualInstance3D<class_VisualInstance3D>` **<** :ref:`Node3D<class_Node3D>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`

Computes and stores baked lightmaps for fast global illumination.

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

The ``LightmapGI`` node is used to compute and store baked lightmaps. Lightmaps are used to provide high-quality indirect lighting with very little light leaking. ``LightmapGI`` can also provide rough reflections using spherical harmonics if :ref:`directional<class_LightmapGI_property_directional>` is enabled. Dynamic objects can receive indirect lighting thanks to *light probes*, which can be automatically placed by setting :ref:`generate_probes_subdiv<class_LightmapGI_property_generate_probes_subdiv>`. Additional lightmap probes can also be added by creating :ref:`LightmapProbe<class_LightmapProbe>` nodes. The downside is that lightmaps are fully static and cannot be baked in an exported project. Baking a ``LightmapGI`` node is also slower compared to :ref:`VoxelGI<class_VoxelGI>`.

\ **Procedural generation:** Lightmap baking functionality is only available in the editor. This means ``LightmapGI`` is not suited to procedurally generated or user-built levels. For procedurally generated or user-built levels, use :ref:`VoxelGI<class_VoxelGI>` or SDFGI instead (see :ref:`Environment.sdfgi_enabled<class_Environment_property_sdfgi_enabled>`).

\ **Performance:** ``LightmapGI`` provides the best possible run-time performance for global illumination. It is suitable for low-end hardware including integrated graphics and mobile devices.

Properties
----------

+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>`                               | :ref:`bias<class_LightmapGI_property_bias>`                                           | ``0.0005`` |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`int<class_int>`                                   | :ref:`bounces<class_LightmapGI_property_bounces>`                                     | ``1``      |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`bool<class_bool>`                                 | :ref:`directional<class_LightmapGI_property_directional>`                             | ``false``  |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`Color<class_Color>`                               | :ref:`environment_custom_color<class_LightmapGI_property_environment_custom_color>`   |            |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`float<class_float>`                               | :ref:`environment_custom_energy<class_LightmapGI_property_environment_custom_energy>` |            |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`Sky<class_Sky>`                                   | :ref:`environment_custom_sky<class_LightmapGI_property_environment_custom_sky>`       |            |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`EnvironmentMode<enum_LightmapGI_EnvironmentMode>` | :ref:`environment_mode<class_LightmapGI_property_environment_mode>`                   | ``0``      |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`GenerateProbes<enum_LightmapGI_GenerateProbes>`   | :ref:`generate_probes_subdiv<class_LightmapGI_property_generate_probes_subdiv>`       | ``0``      |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`bool<class_bool>`                                 | :ref:`interior<class_LightmapGI_property_interior>`                                   | ``false``  |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`LightmapGIData<class_LightmapGIData>`             | :ref:`light_data<class_LightmapGI_property_light_data>`                               |            |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`int<class_int>`                                   | :ref:`max_texture_size<class_LightmapGI_property_max_texture_size>`                   | ``16384``  |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`BakeQuality<enum_LightmapGI_BakeQuality>`         | :ref:`quality<class_LightmapGI_property_quality>`                                     | ``1``      |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+
| :ref:`bool<class_bool>`                                 | :ref:`use_denoiser<class_LightmapGI_property_use_denoiser>`                           | ``true``   |
+---------------------------------------------------------+---------------------------------------------------------------------------------------+------------+

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

.. _enum_LightmapGI_BakeQuality:

.. _class_LightmapGI_constant_BAKE_QUALITY_LOW:

.. _class_LightmapGI_constant_BAKE_QUALITY_MEDIUM:

.. _class_LightmapGI_constant_BAKE_QUALITY_HIGH:

.. _class_LightmapGI_constant_BAKE_QUALITY_ULTRA:

enum **BakeQuality**:

- **BAKE_QUALITY_LOW** = **0**

- **BAKE_QUALITY_MEDIUM** = **1**

- **BAKE_QUALITY_HIGH** = **2**

- **BAKE_QUALITY_ULTRA** = **3**

----

.. _enum_LightmapGI_GenerateProbes:

.. _class_LightmapGI_constant_GENERATE_PROBES_DISABLED:

.. _class_LightmapGI_constant_GENERATE_PROBES_SUBDIV_4:

.. _class_LightmapGI_constant_GENERATE_PROBES_SUBDIV_8:

.. _class_LightmapGI_constant_GENERATE_PROBES_SUBDIV_16:

.. _class_LightmapGI_constant_GENERATE_PROBES_SUBDIV_32:

enum **GenerateProbes**:

- **GENERATE_PROBES_DISABLED** = **0**

- **GENERATE_PROBES_SUBDIV_4** = **1**

- **GENERATE_PROBES_SUBDIV_8** = **2**

- **GENERATE_PROBES_SUBDIV_16** = **3**

- **GENERATE_PROBES_SUBDIV_32** = **4**

----

.. _enum_LightmapGI_BakeError:

.. _class_LightmapGI_constant_BAKE_ERROR_OK:

.. _class_LightmapGI_constant_BAKE_ERROR_NO_LIGHTMAPPER:

.. _class_LightmapGI_constant_BAKE_ERROR_NO_SAVE_PATH:

.. _class_LightmapGI_constant_BAKE_ERROR_NO_MESHES:

.. _class_LightmapGI_constant_BAKE_ERROR_MESHES_INVALID:

.. _class_LightmapGI_constant_BAKE_ERROR_CANT_CREATE_IMAGE:

.. _class_LightmapGI_constant_BAKE_ERROR_USER_ABORTED:

enum **BakeError**:

- **BAKE_ERROR_OK** = **0**

- **BAKE_ERROR_NO_LIGHTMAPPER** = **1**

- **BAKE_ERROR_NO_SAVE_PATH** = **2**

- **BAKE_ERROR_NO_MESHES** = **3**

- **BAKE_ERROR_MESHES_INVALID** = **4**

- **BAKE_ERROR_CANT_CREATE_IMAGE** = **5**

- **BAKE_ERROR_USER_ABORTED** = **6**

----

.. _enum_LightmapGI_EnvironmentMode:

.. _class_LightmapGI_constant_ENVIRONMENT_MODE_DISABLED:

.. _class_LightmapGI_constant_ENVIRONMENT_MODE_SCENE:

.. _class_LightmapGI_constant_ENVIRONMENT_MODE_CUSTOM_SKY:

.. _class_LightmapGI_constant_ENVIRONMENT_MODE_CUSTOM_COLOR:

enum **EnvironmentMode**:

- **ENVIRONMENT_MODE_DISABLED** = **0**

- **ENVIRONMENT_MODE_SCENE** = **1**

- **ENVIRONMENT_MODE_CUSTOM_SKY** = **2**

- **ENVIRONMENT_MODE_CUSTOM_COLOR** = **3**

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

.. _class_LightmapGI_property_bias:

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

+-----------+-----------------+
| *Default* | ``0.0005``      |
+-----------+-----------------+
| *Setter*  | set_bias(value) |
+-----------+-----------------+
| *Getter*  | get_bias()      |
+-----------+-----------------+

----

.. _class_LightmapGI_property_bounces:

- :ref:`int<class_int>` **bounces**

+-----------+--------------------+
| *Default* | ``1``              |
+-----------+--------------------+
| *Setter*  | set_bounces(value) |
+-----------+--------------------+
| *Getter*  | get_bounces()      |
+-----------+--------------------+

----

.. _class_LightmapGI_property_directional:

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

+-----------+------------------------+
| *Default* | ``false``              |
+-----------+------------------------+
| *Setter*  | set_directional(value) |
+-----------+------------------------+
| *Getter*  | is_directional()       |
+-----------+------------------------+

----

.. _class_LightmapGI_property_environment_custom_color:

- :ref:`Color<class_Color>` **environment_custom_color**

+----------+-------------------------------------+
| *Setter* | set_environment_custom_color(value) |
+----------+-------------------------------------+
| *Getter* | get_environment_custom_color()      |
+----------+-------------------------------------+

----

.. _class_LightmapGI_property_environment_custom_energy:

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

+----------+--------------------------------------+
| *Setter* | set_environment_custom_energy(value) |
+----------+--------------------------------------+
| *Getter* | get_environment_custom_energy()      |
+----------+--------------------------------------+

----

.. _class_LightmapGI_property_environment_custom_sky:

- :ref:`Sky<class_Sky>` **environment_custom_sky**

+----------+-----------------------------------+
| *Setter* | set_environment_custom_sky(value) |
+----------+-----------------------------------+
| *Getter* | get_environment_custom_sky()      |
+----------+-----------------------------------+

----

.. _class_LightmapGI_property_environment_mode:

- :ref:`EnvironmentMode<enum_LightmapGI_EnvironmentMode>` **environment_mode**

+-----------+-----------------------------+
| *Default* | ``0``                       |
+-----------+-----------------------------+
| *Setter*  | set_environment_mode(value) |
+-----------+-----------------------------+
| *Getter*  | get_environment_mode()      |
+-----------+-----------------------------+

----

.. _class_LightmapGI_property_generate_probes_subdiv:

- :ref:`GenerateProbes<enum_LightmapGI_GenerateProbes>` **generate_probes_subdiv**

+-----------+----------------------------+
| *Default* | ``0``                      |
+-----------+----------------------------+
| *Setter*  | set_generate_probes(value) |
+-----------+----------------------------+
| *Getter*  | get_generate_probes()      |
+-----------+----------------------------+

----

.. _class_LightmapGI_property_interior:

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

+-----------+---------------------+
| *Default* | ``false``           |
+-----------+---------------------+
| *Setter*  | set_interior(value) |
+-----------+---------------------+
| *Getter*  | is_interior()       |
+-----------+---------------------+

----

.. _class_LightmapGI_property_light_data:

- :ref:`LightmapGIData<class_LightmapGIData>` **light_data**

+----------+-----------------------+
| *Setter* | set_light_data(value) |
+----------+-----------------------+
| *Getter* | get_light_data()      |
+----------+-----------------------+

----

.. _class_LightmapGI_property_max_texture_size:

- :ref:`int<class_int>` **max_texture_size**

+-----------+-----------------------------+
| *Default* | ``16384``                   |
+-----------+-----------------------------+
| *Setter*  | set_max_texture_size(value) |
+-----------+-----------------------------+
| *Getter*  | get_max_texture_size()      |
+-----------+-----------------------------+

----

.. _class_LightmapGI_property_quality:

- :ref:`BakeQuality<enum_LightmapGI_BakeQuality>` **quality**

+-----------+-------------------------+
| *Default* | ``1``                   |
+-----------+-------------------------+
| *Setter*  | set_bake_quality(value) |
+-----------+-------------------------+
| *Getter*  | get_bake_quality()      |
+-----------+-------------------------+

----

.. _class_LightmapGI_property_use_denoiser:

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

+-----------+-------------------------+
| *Default* | ``true``                |
+-----------+-------------------------+
| *Setter*  | set_use_denoiser(value) |
+-----------+-------------------------+
| *Getter*  | is_using_denoiser()     |
+-----------+-------------------------+

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