#######################################
Using Built-in HOOPS Luminate Materials
#######################################

.. toctree::
    :maxdepth: 1
    :titlesonly:
    :hidden:

    bk_bm_brm/bk_bm_builtin_generic
    bk_bm_brm/bk_bm_builtin_lib
    bk_bm_brm/bk_bm_builtin_realistic
    bk_bm_brm/bk_bm_builtin_editor


Building custom materials and programming custom shaders can be a tough and time-consuming task. Fortunately, HOOPS Luminate provides various ready-to-use built-in materials, either via its large external library or via internal functions.

**********************
The Realistic Material
**********************

HOOPS Luminate contains a special 'ready-to-use' material called the realistic material. This is an all-purpose, fully customizable material able to reproduce the look and feel of almost every surface in nature. This material features energy preservation, an anisotropic reflectance model, transmission scattering and much more. It can be used in real-time application, but its main usage is for the creation of photo-realistic images. 

More details about this material here: :doc:`/book/subjects/bk_bm/bk_bm_brm/bk_bm_builtin_realistic`, and a tutorial here: :doc:`/tutorials/workflows/wf_rendering/wf_using_realistic_material`.


********************
The Generic Material
********************

The generic material is an all-purpose, fast and simple material intended for real-time as for photo-realism. It have to be created via the HOOPS Luminate function ``RED::IMaterial::SetupGenericMaterial``.

All you need to know about the generic material is located in the page :doc:`/book/subjects/bk_bm/bk_bm_brm/bk_bm_builtin_generic`, and a tutorial can also be found here: :doc:`/tutorials/workflows/wf_rendering/wf_material_generic`.


************************************
HOOPS Luminate's Library of Material
************************************

The other way to use built-in materials is by accessing the large external HOOPS Luminate materials library. This library contains several materials for all usages filtered by categories like bricks, stone and wood. Use this path inside the package to see the library if you are a legacy product owner: ``HOOPS_Luminate_2024/BuildImage/RedMaterials/Catalog/Catalog.html``


.. figure:: material_library_01.png 
  :align: center
  
  **The material library**

All the details about installing, loading and using the REDMaterial library can be found in the following page: :doc:`/book/subjects/bk_bm/bk_bm_brm/bk_bm_builtin_lib`.

A tutorial is also available to learn how to load a library material and assign it to a shape: :doc:`/tutorials/workflows/wf_rendering/wf_using_realistic_material`.


*******************
The Material Editor
*******************

REDMaterialEditor is a standalone program that lets you create, save & edit realistic-based materials to later use in your application. The page ':doc:`/book/subjects/bk_bm/bk_bm_brm/bk_bm_builtin_editor`' explains how to use it.

.. figure:: material_editor_01.png 
  :align: center
  
  **The material editor**


***************************
Using PBR Metallic Material
***************************

Several material and texturing softwares use a PBR (Physically Based Rendering) metallic workflow. HOOPS Luminate provides a helper function to convert data from PBR metallic to the realistic material: ``RED::ImageTools::ConvertMetallicToRealisticMaterial``.

Basically, a metallic workflow works with these material data:

    * albedo map
    * roughness map
    * metalness map
    * ao map
    * normal map
    * displacement map

Some of these maps can't be plugged directly in the realistic material. The ``RED::ImageTools::ConvertMetallicToRealisticMaterial`` function converts the 4 maps: albedo, roughness, metalness and ao into 3 new textures: diffuse, reflection and anisotropy that are valid inputs for the realisitic material. The normal and displacement maps can be plugged directly.

.. figure:: bk_bm_using_built_in_luminate_materials_pbr.png 
  :align: center
  
  **The metallic workflow from front to back: albedo, roughness, metalness, ao, normal, displacement**
