godot-docs/classes/class_giprobe.rst

:github_url: hide

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

.. _class_GIProbe:

GIProbe
=======

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

Real-time global illumination (GI) probe.

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

``GIProbe``\ s are used to provide high-quality real-time indirect light to scenes. They precompute the effect of objects that emit light and the effect of static geometry to simulate the behavior of complex light in real-time. ``GIProbe``\ s need to be baked before using, however, once baked, dynamic objects will receive light from them. Further, lights can be fully dynamic or baked.

Having ``GIProbe``\ s in a scene can be expensive, the quality of the probe can be turned down in exchange for better performance in the :ref:`ProjectSettings<class_ProjectSettings>` using :ref:`ProjectSettings.rendering/quality/gi_probes/quality<class_ProjectSettings_property_rendering/quality/gi_probes/quality>`.

Tutorials
---------

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

Properties
----------

+---------------------------------------+------------------------------------------------+---------------------------+
| :ref:`GIProbeData<class_GIProbeData>` | :ref:`data<class_GIProbe_property_data>`       |                           |
+---------------------------------------+------------------------------------------------+---------------------------+
| :ref:`Vector3<class_Vector3>`         | :ref:`extents<class_GIProbe_property_extents>` | ``Vector3( 10, 10, 10 )`` |
+---------------------------------------+------------------------------------------------+---------------------------+
| :ref:`Subdiv<enum_GIProbe_Subdiv>`    | :ref:`subdiv<class_GIProbe_property_subdiv>`   | ``1``                     |
+---------------------------------------+------------------------------------------------+---------------------------+

Methods
-------

+------+----------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`bake<class_GIProbe_method_bake>` **(** :ref:`Node<class_Node>` from_node=null, :ref:`bool<class_bool>` create_visual_debug=false **)** |
+------+----------------------------------------------------------------------------------------------------------------------------------------------+
| void | :ref:`debug_bake<class_GIProbe_method_debug_bake>` **(** **)**                                                                               |
+------+----------------------------------------------------------------------------------------------------------------------------------------------+

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

.. _enum_GIProbe_Subdiv:

.. _class_GIProbe_constant_SUBDIV_64:

.. _class_GIProbe_constant_SUBDIV_128:

.. _class_GIProbe_constant_SUBDIV_256:

.. _class_GIProbe_constant_SUBDIV_512:

.. _class_GIProbe_constant_SUBDIV_MAX:

enum **Subdiv**:

- **SUBDIV_64** = **0** --- Use 64 subdivisions. This is the lowest quality setting, but the fastest. Use it if you can, but especially use it on lower-end hardware.

- **SUBDIV_128** = **1** --- Use 128 subdivisions. This is the default quality setting.

- **SUBDIV_256** = **2** --- Use 256 subdivisions.

- **SUBDIV_512** = **3** --- Use 512 subdivisions. This is the highest quality setting, but the slowest. On lower-end hardware this could cause the GPU to stall.

- **SUBDIV_MAX** = **4** --- Represents the size of the :ref:`Subdiv<enum_GIProbe_Subdiv>` enum.

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

.. _class_GIProbe_property_data:

- :ref:`GIProbeData<class_GIProbeData>` **data**

+----------+-----------------------+
| *Setter* | set_probe_data(value) |
+----------+-----------------------+
| *Getter* | get_probe_data()      |
+----------+-----------------------+

The :ref:`GIProbeData<class_GIProbeData>` resource that holds the data for this ``GIProbe``.

----

.. _class_GIProbe_property_extents:

- :ref:`Vector3<class_Vector3>` **extents**

+-----------+---------------------------+
| *Default* | ``Vector3( 10, 10, 10 )`` |
+-----------+---------------------------+
| *Setter*  | set_extents(value)        |
+-----------+---------------------------+
| *Getter*  | get_extents()             |
+-----------+---------------------------+

The size of the area covered by the ``GIProbe``. If you make the extents larger without increasing the subdivisions with :ref:`subdiv<class_GIProbe_property_subdiv>`, the size of each cell will increase and result in lower detailed lighting.

----

.. _class_GIProbe_property_subdiv:

- :ref:`Subdiv<enum_GIProbe_Subdiv>` **subdiv**

+-----------+-------------------+
| *Default* | ``1``             |
+-----------+-------------------+
| *Setter*  | set_subdiv(value) |
+-----------+-------------------+
| *Getter*  | get_subdiv()      |
+-----------+-------------------+

Number of times to subdivide the grid that the ``GIProbe`` operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.

Method Descriptions
-------------------

.. _class_GIProbe_method_bake:

- void **bake** **(** :ref:`Node<class_Node>` from_node=null, :ref:`bool<class_bool>` create_visual_debug=false **)**

Bakes the effect from all :ref:`GeometryInstance<class_GeometryInstance>`\ s marked with :ref:`GeometryInstance.use_in_baked_light<class_GeometryInstance_property_use_in_baked_light>` and :ref:`Light<class_Light>`\ s marked with either :ref:`Light.BAKE_INDIRECT<class_Light_constant_BAKE_INDIRECT>` or :ref:`Light.BAKE_ALL<class_Light_constant_BAKE_ALL>`. If ``create_visual_debug`` is ``true``, after baking the light, this will generate a :ref:`MultiMesh<class_MultiMesh>` that has a cube representing each solid cell with each cube colored to the cell's albedo color. This can be used to visualize the ``GIProbe``'s data and debug any issues that may be occurring.

----

.. _class_GIProbe_method_debug_bake:

- void **debug_bake** **(** **)**

Calls :ref:`bake<class_GIProbe_method_bake>` with ``create_visual_debug`` enabled.