.. _stdlib_hd_global_illumination_component:

====================
HDGlobalIllumination
====================

.. das:module:: hd_global_illumination_component




+++++++
Classes
+++++++

.. _struct-hd_global_illumination_component-HDGlobalIllumination:

.. das:attribute:: HDGlobalIllumination : NativeComponent

This component provides control over global illumination (GI) properties in :ref:`HD Renderer <stdlib_hd_renderer>`.

The GI system simulates global light propagation, enabling indirect lighting from lit surfaces
and offscreen scene reflections. It is fully dynamic, reacting to scene changes at
runtime without baking or any additional authoring. Nevertheless, it's designed to work with static geometry,
so you need to tell which nodes of your scenes are static by setting ``isStatic`` property of
node's :ref:`Mesh <stdlib_mesh_component>` component (or ``meshStatic`` node property in the editor).

Internally, GI sees the scene as a set of cascaded voxel grids: an SDF (signed distance field) for
scene tracing and an albedo grid for surface color at hit points. Both are built and updated
automatically from the scene's static geometry. Using this representation, GI gradually computes
indirect lighting and stores it in radiance probes evenly distributed across another cascaded grid.
The final result is accumulated in screen-space probes, which provide detailed GI on screen and
extend coverage to distances beyond the radiance probe grid.

These settings control scene-dependent parameters that cannot be determined in advance to fit all
cases. Note that they're hints telling the renderer which setup you want. The actual values may be
adjusted internally to satisfy GI's constraints.

To use this component, add the following line to your project file::

    require engine.core_components.hd_global_illumination // or require engine.core

Usage example::

    let renderSettings = create_render_settings()
    add_component(renderSettings, new HDGlobalIllumination())
    get_component(renderSettings) $(var gi : HDGlobalIllumination?) {
        gi.coveredDistance = 200.0
        gi.albedoVoxelScale = 2.0
    }



:Properties:

.. _function-hd_global_illumination_component__dot__rq_coveredDistance_HDGlobalIllumination:

.. das:operator:: HDGlobalIllumination.coveredDistance() : float




.. _function-hd_global_illumination_component__dot__rq_coveredDistance_rq_clone_HDGlobalIllumination_float:

.. das:operator:: HDGlobalIllumination.coveredDistance =(value: float)

Minimum distance from camera to be covered by GI. Note that the number of radiance grid cascades is limited to 4, so increasing covered distance too far will make GI less detailed and prone to light leaking near the camera.


:Arguments: * **value** : float

.. _function-hd_global_illumination_component__dot__rq_verticalScale_HDGlobalIllumination:

.. das:operator:: HDGlobalIllumination.verticalScale() : float




.. _function-hd_global_illumination_component__dot__rq_verticalScale_rq_clone_HDGlobalIllumination_float:

.. das:operator:: HDGlobalIllumination.verticalScale =(value: float)

Height-to-width ratio. If a cascade covers ``N`` meters around the camera horizontally, it will cover ``N * verticalScale`` meters vertically. By default it's 0.5, assuming the scene is relatively flat. It reduces memory usage and increases performance because less data needs to be stored and updated per frame. But you can increase it up to 1 if your scene doesn't meet this assumption.


:Arguments: * **value** : float

.. _function-hd_global_illumination_component__dot__rq_baseSDFVoxelSize_HDGlobalIllumination:

.. das:operator:: HDGlobalIllumination.baseSDFVoxelSize() : float




.. _function-hd_global_illumination_component__dot__rq_baseSDFVoxelSize_rq_clone_HDGlobalIllumination_float:

.. das:operator:: HDGlobalIllumination.baseSDFVoxelSize =(value: float)

Voxel size of 0-th SDF cascade. On the ``N``-th cascade of the SDF scene, it will be ``baseSDFVoxelSize * pow(2, N)``. It also serves as a base size used for computing voxel/probe sizes of other GI scenes.


:Arguments: * **value** : float

.. _function-hd_global_illumination_component__dot__rq_albedoVoxelScale_HDGlobalIllumination:

.. das:operator:: HDGlobalIllumination.albedoVoxelScale() : float




.. _function-hd_global_illumination_component__dot__rq_albedoVoxelScale_rq_clone_HDGlobalIllumination_float:

.. das:operator:: HDGlobalIllumination.albedoVoxelScale =(value: float)

Scale factor for albedo scene's voxel size. On the ``N``-th cascade of the albedo scene, it will be ``baseSDFVoxelSize * albedoVoxelScale * pow(2, N)``.


:Arguments: * **value** : float