###################################
HOOPS Luminate Scene Graph Overview
###################################

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

    /book/subjects/bk_sgo/bk_sg_transform_shapes
    /book/subjects/bk_sgo/bk_sg_mesh_shapes
    /book/subjects/bk_sgo/bk_sg_line_shapes
    /book/subjects/bk_sgo/bk_sg_point_shapes
    /book/subjects/bk_sgo/bk_sg_light_shapes
    /book/subjects/bk_sgo/bk_sg_volumetric_shapes
    /book/subjects/bk_sgo/bk_sg_text_shapes
    /book/subjects/bk_sgo/bk_sg_instances
    /book/subjects/bk_sgo/bk_sg_shape_attributes
    /book/subjects/bk_sgo/bk_sg_culling_methods
    

This book details the scene graph part of the HOOPS Luminate API. The scene graph is a key element in the definition of a 2D or 3D world to display. During the course of this book, we'll review all the different objects that are part of the HOOPS Luminate scene graph and see how they can be organized together.

HOOPS Luminate scene graph objects are divided into two categories:

  * Shapes: these are the graphic entities to display. Shapes can be composed of all common graphical entities: triangles, lines, points, texts, lights, ...
  * Atomic attributes: these define the way a given scene graph is to be displayed on screen. Among them, we'll find bounding spheres, layersets, matrices, ...


**********************
What is a Scene Graph?
**********************

The HOOPS Luminate scene graph is a graph of shapes. More precisely, it's a Direct Acyclic Graph. We'll often refer to this using the "DAG" acronym. A direct acyclic graph defines:

  * A parent to children relationship among its shapes
  * It don't support loops. Consequently, the graph has a root element and leaves elements
  * A reference / instance relationship: a given shape may have more than one parent

The picture below illustrates these properties:

We identify 
An instanced shape is stored once in memory (the reference) and is visualized as many times as there are different paths from the scene graph root down to the shape itself (the instances).

.. figure:: what_is_a_scene_graph.png 
    :align: center
    
    **The Direct Acyclic Graph (DAG) properties.**

.. include:: /tasks/ta_ca/ta_ca_scenegraph/tk_creating_and_destroying_shapes.rst


*****************************
Shapes Types in a Scene Graph
*****************************

The HOOPS Luminate scene graph features the following base shape types that can be used to assemble the visible geometrical primitives of a scene to render:

+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
| Shape Name                                                               | CID                       | Main Interfaces              | Illustrations                  |
|                                                                          |                           |                              |                                | 
+==========================================================================+===========================+==============================+================================+
|                                                                          | ``CID_REDMeshShape``      | ``RED::IShape``              |                                |
| :doc:`Mesh Shapes </book/subjects/bk_sgo/bk_sg_mesh_shapes>`             |                           |                              | .. image:: mesh_shape.png      |
|                                                                          |                           | ``RED::IMeshShape``          |   :align: center               |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDLineShape``      | ``RED::IShape``              |                                |
| :doc:`Line Shapes </book/subjects/bk_sgo/bk_sg_line_shapes>`             |                           |                              | .. image:: line_shape.png      |
|                                                                          |                           | ``RED::ILineShape``          |   :align: center               |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDPointShape``     | ``RED::IShape``              |                                |
| :doc:`Point Shapes </book/subjects/bk_sgo/bk_sg_point_shapes>`           |                           |                              | .. image:: point_shape.png     |
|                                                                          |                           | ``RED::IPointShape``         |   :align: center               |
|                                                                          |                           |                              |                                |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDTransformShape`` | ``RED::IShape``              |                                |
| :doc:`Transform Shapes </book/subjects/bk_sgo/bk_sg_transform_shapes>`   |                           |                              | .. image:: transform_shape.png |
|                                                                          |                           | ``RED::ITransformShape``     |   :align: center               |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDTextShape``      | ``RED::IShape``              |                                |
| :doc:`Text Shapes </book/subjects/bk_sgo/bk_sg_text_shapes>`             |                           |                              | .. image:: text_shape.png      |
|                                                                          |                           | ``RED::ITextShape``          |   :align: center               |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDLightShape``     | ``RED::IShape``              |                                |
|                                                                          |                           |                              | .. image:: light_shape.png     |
| :doc:`Light Shapes </book/subjects/bk_sgo/bk_sg_light_shapes>`           |                           | ``RED::ILightShape``         |   :align: center               |
|                                                                          |                           |                              |                                |
|                                                                          |                           | ``RED::IPhysicalLightShape`` |                                |
|                                                                          |                           |                              |                                |
|                                                                          |                           | ``RED::ISkyLightShape``      |                                |
|                                                                          |                           |                              |                                |
|                                                                          |                           | ``RED::ISunLightShape``      |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+
|                                                                          | ``CID_REDVolumeShape``    | ``RED::IShape``              |                                |
| :doc:`Volumetric Shapes </book/subjects/bk_sgo/bk_sg_volumetric_shapes>` |                           |                              | .. image:: volume_shape.png    |
|                                                                          |                           | ``RED::IVolumeShape``        |   :align: center               |
|                                                                          |                           |                              |                                |
+--------------------------------------------------------------------------+---------------------------+------------------------------+--------------------------------+


HOOPS Luminate's mesh, line and point display shapes are just atomic. They respectively load triangles, line segments (or strips) and points. There's no built-in tessellation service HOOPS Luminate except for planar polygons. HOOPS Luminate data is usually sourced from external modelling software that provide the data arrays to use to fill-in the shapes. Each shape is a ``RED::Object`` created by ``RED::Factory::CreateInstance`` using the appropriate CID and implementing the following interfaces:

There are also several other shape types available in HOOPS Luminate:

Transformation shapes are mandatory to define the relative placement of objects. They actually define the real positioning of objects thanks to the transformation matrix they store. Texts are 2D or 3D primitives that are used to display various types of texts inside an application. Light sources are needed to provide some illumination to the geometries found inside a scene graph, and volumetric effects are rather advanced objects used for the definition of gaseous effects in a high quality image rendering.


**********************
Scene Graph Attributes
**********************

A shape stores several attributes that indicate HOOPS Luminate how to display the shape, or how external application data can be linked to a shape. Attributes are standalone or may be inherited along the hierarchy defined by the scene graph DAG. The details of these attributes and how they are to be used is here: :doc:`/book/subjects/bk_sgo/bk_sg_shape_attributes`.


*******
Culling
*******
 
HOOPS Luminate delivers a number of built-in culling methods that can be used to speed-up the display of some scenes. All these methods are reviewed in the paragraph here: :doc:`/book/subjects/bk_sgo/bk_sg_culling_methods`

