classref: Sync with latest 4.0-dev

classes/class_voxelgi.rst

@@ -0,0 +1,148 @@
+:github_url: hide
+
+.. Generated automatically by doc/tools/makerst.py in Godot's source tree.
+.. DO NOT EDIT THIS FILE, but the VoxelGI.xml source instead.
+.. The source is found in doc/classes or modules/<name>/doc_classes.
+
+.. _class_VoxelGI:
+
+VoxelGI
+=======
+
+**Inherits:** :ref:`VisualInstance3D<class_VisualInstance3D>` **<** :ref:`Node3D<class_Node3D>` **<** :ref:`Node<class_Node>` **<** :ref:`Object<class_Object>`
+
+Real-time global illumination (GI) probe.
+
+Description
+-----------
+
+``VoxelGI``\ 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. ``VoxelGI``\ 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 ``VoxelGI``\ 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/global_illumination/voxel_gi/quality<class_ProjectSettings_property_rendering/global_illumination/voxel_gi/quality>`.
+
+**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.
+
+Tutorials
+---------
+
+- :doc:`../tutorials/3d/voxel_gi`
+
+- `Third Person Shooter Demo <https://godotengine.org/asset-library/asset/678>`__
+
+Properties
+----------
+
++---------------------------------------+------------------------------------------------+-------------------------+
+| :ref:`VoxelGIData<class_VoxelGIData>` | :ref:`data<class_VoxelGI_property_data>`       |                         |
++---------------------------------------+------------------------------------------------+-------------------------+
+| :ref:`Vector3<class_Vector3>`         | :ref:`extents<class_VoxelGI_property_extents>` | ``Vector3(10, 10, 10)`` |
++---------------------------------------+------------------------------------------------+-------------------------+
+| :ref:`Subdiv<enum_VoxelGI_Subdiv>`    | :ref:`subdiv<class_VoxelGI_property_subdiv>`   | ``1``                   |
++---------------------------------------+------------------------------------------------+-------------------------+
+
+Methods
+-------
+
++------+----------------------------------------------------------------------------------------------------------------------------------------------+
+| void | :ref:`bake<class_VoxelGI_method_bake>` **(** :ref:`Node<class_Node>` from_node=null, :ref:`bool<class_bool>` create_visual_debug=false **)** |
++------+----------------------------------------------------------------------------------------------------------------------------------------------+
+| void | :ref:`debug_bake<class_VoxelGI_method_debug_bake>` **(** **)**                                                                               |
++------+----------------------------------------------------------------------------------------------------------------------------------------------+
+
+Enumerations
+------------
+
+.. _enum_VoxelGI_Subdiv:
+
+.. _class_VoxelGI_constant_SUBDIV_64:
+
+.. _class_VoxelGI_constant_SUBDIV_128:
+
+.. _class_VoxelGI_constant_SUBDIV_256:
+
+.. _class_VoxelGI_constant_SUBDIV_512:
+
+.. _class_VoxelGI_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_VoxelGI_Subdiv>` enum.
+
+Property Descriptions
+---------------------
+
+.. _class_VoxelGI_property_data:
+
+- :ref:`VoxelGIData<class_VoxelGIData>` **data**
+
++----------+-----------------------+
+| *Setter* | set_probe_data(value) |
++----------+-----------------------+
+| *Getter* | get_probe_data()      |
++----------+-----------------------+
+
+The :ref:`VoxelGIData<class_VoxelGIData>` resource that holds the data for this ``VoxelGI``.
+
+----
+
+.. _class_VoxelGI_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 ``VoxelGI``. If you make the extents larger without increasing the subdivisions with :ref:`subdiv<class_VoxelGI_property_subdiv>`, the size of each cell will increase and result in lower detailed lighting.
+
+----
+
+.. _class_VoxelGI_property_subdiv:
+
+- :ref:`Subdiv<enum_VoxelGI_Subdiv>` **subdiv**
+
++-----------+-------------------+
+| *Default* | ``1``             |
++-----------+-------------------+
+| *Setter*  | set_subdiv(value) |
++-----------+-------------------+
+| *Getter*  | get_subdiv()      |
++-----------+-------------------+
+
+Number of times to subdivide the grid that the ``VoxelGI`` operates on. A higher number results in finer detail and thus higher visual quality, while lower numbers result in better performance.
+
+Method Descriptions
+-------------------
+
+.. _class_VoxelGI_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:`GeometryInstance3D<class_GeometryInstance3D>`\ s marked with :ref:`GeometryInstance3D.GI_MODE_BAKED<class_GeometryInstance3D_constant_GI_MODE_BAKED>` and :ref:`Light3D<class_Light3D>`\ s marked with either :ref:`Light3D.BAKE_DYNAMIC<class_Light3D_constant_BAKE_DYNAMIC>` or :ref:`Light3D.BAKE_STATIC<class_Light3D_constant_BAKE_STATIC>`. 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 ``VoxelGI``'s data and debug any issues that may be occurring.
+
+----
+
+.. _class_VoxelGI_method_debug_bake:
+
+- void **debug_bake** **(** **)**
+
+Calls :ref:`bake<class_VoxelGI_method_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.)`
+.. |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.)`