#####################################
Building a HOOPS Luminate Application
#####################################

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

    /book/subjects/bk_ba/bk_ba_luminate_features_at_a_glance
    /book/subjects/bk_ba/bk_ba_programming_language
    /book/subjects/bk_ba/bk_ba_deployment
    /book/subjects/bk_ba/bk_ba_error_tracking
    /book/subjects/bk_ba/bk_ba_opengl
    /book/subjects/bk_ba/bk_ba_metal
    /book/subjects/bk_ba/bk_ba_software_startup
    /book/subjects/bk_ba/bk_ba_hardware_platforms
    /book/subjects/bk_ba/bk_ba_virtualization_platforms
    /book/subjects/bk_ba/bk_ba_resource_manager
    /book/subjects/bk_ba/bk_ba_data_manager
    /book/subjects/bk_ba/bk_ba_windows
    /book/subjects/bk_ba/bk_ba_viewpoint_render_lists
    /book/subjects/bk_ba/bk_ba_viewpoints
    /book/subjects/bk_ba/bk_ba_options
    /book/subjects/bk_ba/bk_ba_transaction_management
    /book/subjects/bk_ba/bk_ba_life_cycle_of_luminate_objects
    /book/subjects/bk_ba/bk_ba_picking
    /book/subjects/bk_ba/bk_ba_backbone

Welcome to HOOPS Luminate! This book is one of the first you may want to read to get a practical overview of HOOPS Luminate. We'll cover various topics in this book, which are divided into three categories: high level product review (feature set review, example applications), general informations (licensing, deployment, support) and finally how to assemble a HOOPS Luminate application using the base HOOPS Luminate classes (resource manager, windows, viewpoints, ...).

*************************
High Level Product Review
*************************

Please refer to this page: :doc:`/book/subjects/bk_ba/bk_ba_luminate_features_at_a_glance` for a high level review of HOOPS Luminate feature set. This chapter will provide you a summary of HOOPS Luminate capabilities in terms of real-time 2D and 3D rendering as well as for photo-realistic rendering.


********************
General Informations
********************

This part of the book covers all the stuff that may sound a bit boring, but that we have to put somewhere because it's essential anyway:

    * :doc:`/book/subjects/bk_ba/bk_ba_programming_language`: HOOPS Luminate is a C++ API. Get all the details on using it here and have a look at our coding principles too!
    * :doc:`/book/subjects/bk_ba/bk_ba_deployment`: Here more informations on how to deploy a HOOPS Luminate based application. You can't do something easier.
    * :doc:`/book/subjects/bk_ba/bk_ba_error_tracking`: Find here details on errors and error tracking in HOOPS Luminate.
    * :doc:`/book/subjects/bk_ba/bk_ba_software_startup`: HOOPS Luminate is a hybrid hardware / software engine. It can start in pure software or in pure hardware or in hybrid mode, using both rendering modes at the same time in an application. This is a very important feature of HOOPS Luminate. Learn all the details here!
    * :doc:`/book/subjects/bk_ba/bk_ba_hardware_platforms`: HOOPS Luminate has an API to identify the system graphics in use and also to query and recommend graphic driver updates whenever needed.
    * :doc:`/book/subjects/bk_ba/bk_ba_opengl`: HOOPS Luminate uses OpenGL if it has to run using the graphic hardware. Get details on how OpenGL is used by HOOPS Luminate here!
    * :doc:`/book/subjects/bk_ba/bk_ba_virtualization_platforms`: HOOPS Luminate can run on virtualization platforms. This chapter provides some useful informations on how virtualization platforms behave with HOOPS Luminate.


*********************************************
Building a HOOPS Luminate Application Cluster
*********************************************

Basic HOOPS Luminate objects are detailed in their respective chapters indicated below:

    * :doc:`/book/subjects/bk_ba/bk_ba_resource_manager`: The resource manager is the first HOOPS Luminate object in charge of all graphics assets.
    * :doc:`/book/subjects/bk_ba/bk_ba_windows`: Windows are rendering areas, and connected to operating system windows.
    * :doc:`/book/subjects/bk_ba/bk_ba_viewpoint_render_lists`: Viewpoint Render Lists or VRLs for short are classes in charge of the display setup of cameras (viewport, draw order,...).
    * :doc:`/book/subjects/bk_ba/bk_ba_viewpoints`: The camera chapter that detail how camera can be manipulated in HOOPS Luminate.
    * :doc:`/book/subjects/bk_ba/bk_ba_data_manager`: This class is used to the management of loaded .red files.
    * :doc:`/book/subjects/bk_ba/bk_ba_options`: Learn how HOOPS Luminate engine options can be accessed and controlled.

Some more important topics must be covered for operating a HOOPS Luminate application cluster, so we'll provide the links now:

    * :doc:`/book/subjects/bk_ba/bk_ba_transaction_management`: Learn how HOOPS Luminate uses transactions that define engine states for reading and writing.
    * :doc:`/book/subjects/bk_ba/bk_ba_life_cycle_of_luminate_objects`: Learn how HOOPS Luminate objects are created and terminated.
    * :doc:`/book/subjects/bk_ba/bk_ba_picking`: For many applications, picking is a must have, and HOOPS Luminate has a complete picking API, detailed in that chapter.
    * :doc:`/book/subjects/bk_ba/bk_ba_backbone`: Learn how to customize memory allocators, file system tools used by HOOPS Luminate.

Then, let's start gathering all objects we need to run a HOOPS Luminate based program now! A minimal HOOPS Luminate application must - at least - contain the following objects:

.. figure:: minimal_cluster.png
  :align: center
  
  **The minimal set of HOOPS Luminate objects needed to run an application**

The resource manager is a singleton, that is used to store and manage most resources in a HOOPS Luminate based application. A window is the rendering area that we'll need to display something onscreen or to render something offscreen. We'll also need a viewpoint to define how we do observe a scene, that must be at least composed of a shape.

The resource manager is created using the code example below:

.. include:: /tasks/ta_ca/ta_ca_application/tk_creating_or_accessing_the_resource_manager.rst

Then, the window is created using similar means and the ``RED::Factory`` class:

.. include:: /tasks/ta_ca/ta_ca_application/tk_creating_a_luminate_window_using_the_red_factory.rst

And to complete our schema, we'll need to create a viewpoint and a shape to visualize some data. Both are also created using the ``RED::Factory`` again:

.. include:: /tasks/ta_ca/ta_ca_application/tk_creating_and_destroying_objects_using_the_red_factory.rst

At this point in our setup we have created all the objects that we need: a resource manager in charge of the storage and management of all graphic assets of the application; a window for the display of our rendered images; and some data to visualize: a camera that define the observer parameters and some shapes with some graphic data to be visualized. So this is the minimal setup. Of course, from this we'll complete our specification with the creation of materials, images, scene hierarchies, etc...but the basics are there: a resource manager + a window + a viewpoint + a shape.

The 'live' windows are automatically known to the resource manager, and can be accessed anytime using ``RED::IResourceManager::GetWindowList``. Then viewpoints have to be linked to windows to be displayed, and shapes have to be linked to viewpoints to be seen either. We need to add these two links to complete our schema on top of this paragraph:

.. include:: /tasks/ta_ca/ta_ca_application/tk_assembling_a_minimal_luminate_application.rst
