:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/3.6/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/3.6/doc/classes/GIProbe.xml. .. _class_GIProbe: GIProbe ======= **Inherits:** :ref:`VisualInstance` **<** :ref:`CullInstance` **<** :ref:`Spatial` **<** :ref:`Node` **<** :ref:`Object` Real-time global illumination (GI) probe. .. rst-class:: classref-introduction-group 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` using :ref:`ProjectSettings.rendering/quality/voxel_cone_tracing/high_quality`. \ **Procedural generation:** **GIProbe** can be baked in an exported project, which makes it suitable for procedurally generated or user-built levels as long as all the geometry is generated in advance. \ **Performance:** **GIProbe** is relatively demanding on the GPU and is not suited to low-end hardware such as integrated graphics (consider :ref:`BakedLightmap` instead). To provide a fallback for low-end hardware, consider adding an option to disable **GIProbe** in your project's options menus. A **GIProbe** node can be disabled by hiding it. \ **Note:** Meshes should have sufficiently thick walls to avoid light leaks (avoid one-sided walls). For interior levels, enclose your level geometry in a sufficiently large box and bridge the loops to close the mesh. To further prevent light leaks, you can also strategically place temporary :ref:`MeshInstance` nodes with :ref:`GeometryInstance.use_in_baked_light` enabled. These temporary nodes can then be hidden after baking the **GIProbe** node. \ **Note:** Due to a renderer limitation, emissive :ref:`ShaderMaterial`\ s cannot emit light when used in a **GIProbe**. Only emissive :ref:`SpatialMaterial`\ s can emit light in a **GIProbe**. .. rst-class:: classref-introduction-group Tutorials --------- - :doc:`GI probes <../tutorials/3d/gi_probes>` - `Third Person Shooter Demo `__ .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`bias` | ``1.5`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`compress` | ``false`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`GIProbeData` | :ref:`data` | | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`int` | :ref:`dynamic_range` | ``4`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`energy` | ``1.0`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`Vector3` | :ref:`extents` | ``Vector3( 10, 10, 10 )`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`bool` | :ref:`interior` | ``false`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`normal_bias` | ``0.0`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`float` | :ref:`propagation` | ``0.7`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ | :ref:`Subdiv` | :ref:`subdiv` | ``1`` | +---------------------------------------+------------------------------------------------------------+---------------------------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +------+----------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`bake` **(** :ref:`Node` from_node=null, :ref:`bool` create_visual_debug=false **)** | +------+----------------------------------------------------------------------------------------------------------------------------------------------+ | void | :ref:`debug_bake` **(** **)** | +------+----------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Enumerations ------------ .. _enum_GIProbe_Subdiv: .. rst-class:: classref-enumeration enum **Subdiv**: .. _class_GIProbe_constant_SUBDIV_64: .. rst-class:: classref-enumeration-constant :ref:`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. .. _class_GIProbe_constant_SUBDIV_128: .. rst-class:: classref-enumeration-constant :ref:`Subdiv` **SUBDIV_128** = ``1`` Use 128 subdivisions. This is the default quality setting. .. _class_GIProbe_constant_SUBDIV_256: .. rst-class:: classref-enumeration-constant :ref:`Subdiv` **SUBDIV_256** = ``2`` Use 256 subdivisions. .. _class_GIProbe_constant_SUBDIV_512: .. rst-class:: classref-enumeration-constant :ref:`Subdiv` **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. .. _class_GIProbe_constant_SUBDIV_MAX: .. rst-class:: classref-enumeration-constant :ref:`Subdiv` **SUBDIV_MAX** = ``4`` Represents the size of the :ref:`Subdiv` enum. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_GIProbe_property_bias: .. rst-class:: classref-property :ref:`float` **bias** = ``1.5`` .. rst-class:: classref-property-setget - void **set_bias** **(** :ref:`float` value **)** - :ref:`float` **get_bias** **(** **)** Offsets the lookup of the light contribution from the **GIProbe**. This can be used to avoid self-shadowing, but may introduce light leaking at higher values. This and :ref:`normal_bias` should be played around with to minimize self-shadowing and light leaking. \ **Note:** ``bias`` should usually be above 1.0 as that is the size of the voxels. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_compress: .. rst-class:: classref-property :ref:`bool` **compress** = ``false`` .. rst-class:: classref-property-setget - void **set_compress** **(** :ref:`bool` value **)** - :ref:`bool` **is_compressed** **(** **)** *Deprecated.* This property has been deprecated due to known bugs and no longer has any effect when enabled. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_data: .. rst-class:: classref-property :ref:`GIProbeData` **data** .. rst-class:: classref-property-setget - void **set_probe_data** **(** :ref:`GIProbeData` value **)** - :ref:`GIProbeData` **get_probe_data** **(** **)** The :ref:`GIProbeData` resource that holds the data for this **GIProbe**. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_dynamic_range: .. rst-class:: classref-property :ref:`int` **dynamic_range** = ``4`` .. rst-class:: classref-property-setget - void **set_dynamic_range** **(** :ref:`int` value **)** - :ref:`int` **get_dynamic_range** **(** **)** The maximum brightness that the **GIProbe** will recognize. Brightness will be scaled within this range. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_energy: .. rst-class:: classref-property :ref:`float` **energy** = ``1.0`` .. rst-class:: classref-property-setget - void **set_energy** **(** :ref:`float` value **)** - :ref:`float` **get_energy** **(** **)** Energy multiplier. Makes the lighting contribution from the **GIProbe** brighter. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_extents: .. rst-class:: classref-property :ref:`Vector3` **extents** = ``Vector3( 10, 10, 10 )`` .. rst-class:: classref-property-setget - void **set_extents** **(** :ref:`Vector3` value **)** - :ref:`Vector3` **get_extents** **(** **)** The size of the area covered by the **GIProbe**. If you make the extents larger without increasing the subdivisions with :ref:`subdiv`, the size of each cell will increase and result in lower detailed lighting. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_interior: .. rst-class:: classref-property :ref:`bool` **interior** = ``false`` .. rst-class:: classref-property-setget - void **set_interior** **(** :ref:`bool` value **)** - :ref:`bool` **is_interior** **(** **)** If ``true``, ignores the sky contribution when calculating lighting. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_normal_bias: .. rst-class:: classref-property :ref:`float` **normal_bias** = ``0.0`` .. rst-class:: classref-property-setget - void **set_normal_bias** **(** :ref:`float` value **)** - :ref:`float` **get_normal_bias** **(** **)** Offsets the lookup into the **GIProbe** based on the object's normal direction. Can be used to reduce some self-shadowing artifacts. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_propagation: .. rst-class:: classref-property :ref:`float` **propagation** = ``0.7`` .. rst-class:: classref-property-setget - void **set_propagation** **(** :ref:`float` value **)** - :ref:`float` **get_propagation** **(** **)** How much light propagates through the probe internally. A higher value allows light to spread further. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_property_subdiv: .. rst-class:: classref-property :ref:`Subdiv` **subdiv** = ``1`` .. rst-class:: classref-property-setget - void **set_subdiv** **(** :ref:`Subdiv` value **)** - :ref:`Subdiv` **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. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_GIProbe_method_bake: .. rst-class:: classref-method void **bake** **(** :ref:`Node` from_node=null, :ref:`bool` create_visual_debug=false **)** Bakes the effect from all :ref:`GeometryInstance`\ s marked with :ref:`GeometryInstance.use_in_baked_light` and :ref:`Light`\ s marked with either :ref:`Light.BAKE_INDIRECT` or :ref:`Light.BAKE_ALL`. If ``create_visual_debug`` is ``true``, after baking the light, this will generate a :ref:`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. \ **Note:** :ref:`bake` works from the editor and in exported projects. This makes it suitable for procedurally generated or user-built levels. Baking a **GIProbe** generally takes from 5 to 20 seconds in most scenes. Reducing :ref:`subdiv` can speed up baking. \ **Note:** :ref:`GeometryInstance`\ s and :ref:`Light`\ s must be fully ready before :ref:`bake` is called. If you are procedurally creating those and some meshes or lights are missing from your baked **GIProbe**, use ``call_deferred("bake")`` instead of calling :ref:`bake` directly. .. rst-class:: classref-item-separator ---- .. _class_GIProbe_method_debug_bake: .. rst-class:: classref-method void **debug_bake** **(** **)** Calls :ref:`bake` with ``create_visual_debug`` enabled. .. |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.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)`