.. _stdlib_render_core:

=============
Render module
=============


To use the entire render module, add the following line to your project file::

   ``require engine.render_core`` or ``require engine.core``

The render engine used in EdenSpark features an advanced multidraw indirect rendering pipeline with GPU culling for all geometry rendering.
The render system gathers all nodes with :ref:`Mesh <stdlib_mesh_component>` ( :ref:`LODSelector <stdlib_lod_selector_component>` ) and sorts them by their material and mesh.
After that, only the modified data is submitted to the GPU, which then performs GPU culling and gathers draw calls.

You should have at least one active :ref:`Camera <stdlib_camera_component>` in your scene to render it.

.. note:: If you have more than one active camera in your scene, the scene will be rendered for all of them. Be careful and turn off the cameras you don't need.

We provide a set of components to help you set up rendering in your scene:

* :ref:`ShadowSettings <stdlib_shadow_settings_component>`: Shadows are based on the cascaded shadow maps technique.
* :ref:`AmbientSettings <stdlib_ambient_settings_component>`: Ambient lights can be set either with a constant color or with a sky color.
* :ref:`Tonemap <stdlib_tonemap_component>`: Global color grading.
* :ref:`Sky <stdlib_sky_component>`: Allows you to set a material for the sky (e.g., a skybox, a panorama image, or a procedural shader).
* :ref:`AntiAliasing <stdlib_anti_aliasing_component>`: Anti-aliasing settings (FXAA, MSAA).

To use it::

    let renderSettings = create_render_settings("RenderSettings")
    // AntiAliasing and Tonemap are disabled by default

    get_component(renderSettings) $(var settings : ShadowSettings?) {
        // set up the shadows
    }

    get_component(renderSettings) $(var settings : AmbientSettings?) {
        // set up the ambient color
    }

    get_component(renderSettings) $(var settings : Tonemap?) {
        // set up the tonemap
    }

    get_component(renderSettings) $(var settings : AntiAliasing?) {
        // set up anti-aliasing
    }

    get_component(renderSettings) $(var settings : Sky?) {
        // set up the sky
    }

To add lighting to your scenes, you can use the following light sources:

* :ref:`DirectionLight <stdlib_direction_light_component>`: Represents a directional light, or sunlight; it emits light in a single direction.
* :ref:`SpotLight <stdlib_spot_light_component>`: Represents a spotlight source; it emits light in a cone shape.
* :ref:`PointLight <stdlib_point_light_component>`: Represents a point source of light; it emits light in all directions within a certain radius.




+++++++++
Functions
+++++++++

  *  :ref:`create_base_render_settings (name: string = "render_settings") : NodeId <function-render_core_create_base_render_settings_string>` 
  *  :ref:`create_render_settings (name: string = "render_settings") : NodeId <function-render_core_create_render_settings_string>` 
  *  :ref:`set_panorama (node: NodeId; texture: TextureId) <function-render_core_set_panorama_NodeId_TextureId>` 
  *  :ref:`set_skybox (node: NodeId; cubemap: TextureId) <function-render_core_set_skybox_NodeId_TextureId>` 

.. _function-render_core_create_base_render_settings_string:

.. das:function:: create_base_render_settings(name: string = "render_settings") : NodeId

Creates base render settings, without any components attached (e.g. shadows, ambient light, skybox, anti-aliasing, tonemap etc.)
It is useful for creating custom render settings

:Arguments: * **name** : string

.. _function-render_core_create_render_settings_string:

.. das:function:: create_render_settings(name: string = "render_settings") : NodeId

Creates render settings.
Render settings allow you to modify the render pipeline (e.g. shadows, ambient light, skybox, anti-aliasing, tonemap etc.)

:Arguments: * **name** : string -  the name of the render settings



.. _function-render_core_set_panorama_NodeId_TextureId:

.. das:function:: set_panorama(node: NodeId; texture: TextureId)

Set a panorama texture as the skybox

:Arguments: * **node** :  :ref:`NodeId <handle-public_scene-NodeId>`  -  the render settings node of the scene, the result of the ``create_render_settings()`` call

            * **texture** :  :ref:`TextureId <handle-public_resources-TextureId>`  -  the panorama texture, it should be 2D texture with width to height ratio equal to 2 



.. _function-render_core_set_skybox_NodeId_TextureId:

.. das:function:: set_skybox(node: NodeId; cubemap: TextureId)

Set a skybox texture as the skybox. See :ref:`CubeMap (SkyBox) <stdlib_cubemap_import_window>`.

:Arguments: * **node** :  :ref:`NodeId <handle-public_scene-NodeId>`  -  the render settings node of the scene, the result of the ``create_render_settings()`` call

            * **cubemap** :  :ref:`TextureId <handle-public_resources-TextureId>`  -  the skybox texture, it should be cubemap texture.