#################################
Building HOOPS Luminate Materials
#################################

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

    /book/subjects/bk_bm/bk_bm_material_layersets
    /book/subjects/bk_bm/bk_bm_using_built_in_luminate_materials
    /book/subjects/bk_bm/bk_bm_the_material_controller
    /book/subjects/bk_bm/bk_bm_the_shading_pipeline
    /book/subjects/bk_bm/bk_bm_writing_a_custom_material
    /book/subjects/bk_bm/bk_bm_rendering_priorities
    /book/subjects/bk_bm/bk_bm_material_batching
   

This book covers all the practicals aspects of material management in HOOPS Luminate. Materials are shapes attributes, as detailed by the :doc:`/book/subjects/bk_sgo/bk_sg_shape_attributes` page. A material defines the rendering look of a shape or of a tree of shapes below the node that owns the material, thanks to the material inheritance rules in HOOPS Luminate. Materials are shared among shapes: all shapes with the same rendering look should use the same material.


***********
Terminology
***********

A material defines the way a shape is rendered. A material is composed of shaders, that are organized in rendering passes. A shader is either dedicated to the rendering (a ``RED::RenderShader``), or dedicated to configuring the rendering (a ``RED::StateShader``).

A shader dedicated to the rendering is composed of programs executed on the graphics hardware or in software. Among these programs, we find the vertex program, the pixel program and the geometry program. These are also called vertex shaders, fragment shaders and geometry shaders in the literature.

A rendering pass consists in drawing the scene geometry once, for the purpose of a given effect.


********
Contents
********

This book contains two key parts:

    * :doc:`/book/subjects/bk_bm/bk_bm_using_built_in_luminate_materials`: if you want a ready-to-use material, please follow this link. We'll detail the various materials that exist in HOOPS Luminate and how to setup them for different purposes.
    * :doc:`/book/subjects/bk_bm/bk_bm_writing_a_custom_material`: if you want materials dedicated to a specific task, you may want to write your own material. Don't be scared, this is something easy if you rely on built-in HOOPS Luminate shaders. This book chapter details all the HOOPS Luminate built-in shaders as well as how to write your own shader.

And then we can review some other important topics in material management with HOOPS Luminate:

    * :doc:`/book/subjects/bk_bm/bk_bm_material_layersets`: Learn how layersets interfere with the definition of materials and shaders.
    * :doc:`/book/subjects/bk_bm/bk_bm_the_material_controller`: The material controller builds a semantic layer on top of a material to customize it's control for any kind of need.
    * :doc:`/book/subjects/bk_bm/bk_bm_the_shading_pipeline`: Please review this chapter if you're interested in the HOOPS Luminate shading pipeline. We detail a number of important concepts here and how shaders are assembled together and rendered to compose the final image.
    * :doc:`/book/subjects/bk_bm/bk_bm_rendering_priorities`: Learn how to control rendering priorities with a material. This is a must for all use cases where sorted rendering takes place.
    * :doc:`/book/subjects/bk_bm/bk_bm_material_batching`: This chapter covers very specific HOOPS Luminate material usage, to get the best rendering performance during the manipulation of heavily dynamic geometries, or if a very precise data organization into the memory is targeted by the application.


***************
Using Materials
***************

HOOPS Luminate materials are created and destroyed by the cluster's resource manager. Materials are shared resources across all scene graphs defined in the application cluster. First, let's learn how to create or to destroy a given material. The task below illustrates the way to proceed:

.. include:: /tasks/ta_ca/ta_ca_material/tk_creating_and_destroying_materials.rst

It's also a common way to proceed to duplicate an existing material. For instance a material template is loaded from a .red file and duplicated to be modified later on by the application. In this case, the following task applies:

.. include:: /tasks/ta_ca/ta_ca_material/tk_loading_and_duplicating_a_material.rst

