.. _stdlib_material_resource:

======================
Material Scripting API
======================

Module::

    engine.resources.material_resource

Handle Type::

    MaterialId

++++++++++++
Enumerations
++++++++++++

.. _enum-material_resource-MaterialReusePolicy:

.. das:attribute:: MaterialReusePolicy

Policy for material reusing. It is important to reduce amount of materials in the scene to improve rendering performance. So we provide material reusing by default to reach maximum efficiency.

:Values: * **ReuseExisting** = 0 - Reuse existing material with same ``MaterialImport``. We caclulate hash of ``MaterialImport`` and try to find material with same hash.

         * **AlwaysCreateNew** = 1 - Always create new material, even if we have material with same ``MaterialImport``.


++++++++++
Structures
++++++++++

.. _struct-material_resource-MaterialImport:

.. das:attribute:: MaterialImport

This struct allow to create materials from code, see :ref:`stdlib_material_scripting`.

:Fields: * **name** : string - Material name

         * **shaderName** : string - Shader name, see :ref:`stdlib_builtin_shaders`

         * **transparencyMode** :  :ref:`TransparencyMode <enum-material_property_enums-TransparencyMode>`  = material_property_enums::TransparencyMode.Opaque - Transparency mode, see :ref:`stdlib_material_properties`. Equal to ``TransparencyMode Opaque`` by default

         * **faceCullMode** :  :ref:`FaceCullMode <enum-material_property_enums-FaceCullMode>`  = material_property_enums::FaceCullMode.Back - Face cull mode, see :ref:`stdlib_material_properties`. Equal to ``FaceCullMode Back`` by default

         * **diffuse** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Diffuse texture, slot 0

         * **normal** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Normal texture, slot 1

         * **specular** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Specular texture, slot 2

         * **roughness** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Roughness texture, slot 3

         * **ao** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Ambient occlusion texture, slot 4

         * **emission** :  :ref:`TextureId <handle-public_resources-TextureId>`  - Emission texture, slot 5

         * **properties** :  :ref:`MaterialProperties <struct-material_properties-MaterialProperties>`  - Material properties


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

  *  :ref:`request_material (path_to_asset: string) : MaterialId <function-material_resource_request_material_string>` 
  *  :ref:`create_material (material: MaterialImport; reuse_policy: MaterialReusePolicy = material_resource::MaterialReusePolicy.ReuseExisting) : MaterialId <function-material_resource_create_material_MaterialImport_MaterialReusePolicy>` 
  *  :ref:`copy_material (material: MaterialId) : MaterialId <function-material_resource_copy_material_MaterialId>` 
  *  :ref:`update_material (resId: MaterialId; import_settings: MaterialImport) <function-material_resource_update_material_MaterialId_MaterialImport>` 

.. _function-material_resource_request_material_string:

.. das:function:: request_material(path_to_asset: string) : MaterialId

Requests a material asset by the path to it and returns the corresponding resource ID.

:Arguments: * **path_to_asset** : string -  the path to the material asset



:Returns: *  :ref:`MaterialId <handle-public_resources-MaterialId>`  -  the resource ID of the material asset

Usage example::

    let materialId = request_material("my_material")

.. _function-material_resource_create_material_MaterialImport_MaterialReusePolicy:

.. das:function:: create_material(material: MaterialImport; reuse_policy: MaterialReusePolicy = material_resource::MaterialReusePolicy.ReuseExisting) : MaterialId

Creates material resource with given ``MaterialImport`` and ``MaterialReusePolicy``.
If ``MaterialReusePolicy`` is ``ReuseExisting`` and material with same ``MaterialImport`` already exists, it will return existing material.
If ``MaterialReusePolicy`` is ``AlwaysCreateNew`` it will always create new material.
Returns new or existing MaterialId, depends on ``MaterialReusePolicy``.

.. note::
  It is recommended to use ``MaterialReusePolicy ReuseExisting`` to improve performance of render.


:Arguments: * **material** :  :ref:`MaterialImport <struct-material_resource-MaterialImport>` 

            * **reuse_policy** :  :ref:`MaterialReusePolicy <enum-material_resource-MaterialReusePolicy>` 

.. _function-material_resource_copy_material_MaterialId:

.. das:function:: copy_material(material: MaterialId) : MaterialId

Create a copy of existed material.

:Arguments: * **material** :  :ref:`MaterialId <handle-public_resources-MaterialId>` 

.. _function-material_resource_update_material_MaterialId_MaterialImport:

.. das:function:: update_material(resId: MaterialId; import_settings: MaterialImport)

Update material resource with given ``import_settings``

:Arguments: * **resId** :  :ref:`MaterialId <handle-public_resources-MaterialId>` 

            * **import_settings** :  :ref:`MaterialImport <struct-material_resource-MaterialImport>`