
3DF Bridge Demo Projects
========================

The Bridge Demo consist of three projects. 

The main application project is called ``hoops_luminate_demo`` and it uses Qt to create a simple application with two widgets that is capable of rendering 3D objects. The first widget uses HOOPS Visualize 3DF to render and manipulate the scene in real time. The second widget uses HOOPS Luminate and synchronizes with the first widget to render the same scene using a realistic rendering technique called path tracing. 

The second application project is called ``hoops_luminate_bridge``. It is a library of objects and tools that are based on Hoops Luminate. It is used to initialize HOOPS Luminate and set up the scene. All of the HOOPS Luminate code that is relevant to either the initialization of the rendering pipeline, the conversion of the scene, or the synchronization with Hoops Visualize is done in this library.

The third application project is called ``hoops_luminate_widgets``. It is a set of Qt widgets that is used by the demo application for handling calls in HOOPS Luminate and manipulates the data from HOOPS Luminate.


**************************
Preparation & Requirements
**************************

The HV 3DF package provides both binaries of the ``hoops_luminate_bridge`` and ``hoops_luminate_widgets`` libraries as well as the ``hoops_luminate_demo`` application; Thus you can directly start to test out the demo.

If you want to go deeper into the code, in order to compile and execute the demo, you will need to download the latest HOOPS Luminate package from the `Developer Zone <https://developer.techsoft3d.com/start>`__ and unzip it in the location of your choice. 

Then you can use the provided QTCreator projects (.pro) to recompile the ``hoops_luminate_bridge`` and ``hoops_luminate_widgets`` libraries as well as the ``hoops_luminate_demo`` sandbox. For this purpose, you must add in QTCreator projects the environment variable ``HLUMINATE_INSTALL_DIR`` pointing to the root folder of the HOOPS Luminate package, and have a valid license for Hoops Visualize and Hoops Luminate as mentioned on the :doc:`Licensing </general/setting_license>` page.


********************************
*hoops_luminate_bridge*: Library
********************************

*hoops_luminate_bridge* Tools and Objects
-----------------------------------------

The ``hoops_luminate_bridge`` project is used to regroup all of the basic code relative to HOOPS Luminate in order to instantiate a rendering pipeline, convert the data from HOOPS Visualize to HOOPS Luminate, and then to synchronize them. It offers a set of tools and objects to utilize from the main application in order to use HOOPS Luminate. 

    * ``AxisTriad``: Create and synchronize the axis triad in the right bottom corner of the HOOPS Luminate view.

    * ``ConversionTools``: Load images and create materials in HOOPS Luminate.

    * ``Hoops3DFLuminateBridge``: Convert geometry to HOOPS Luminate and get camera info from 3DF.

    * ``HoopsLuminateBridge``: Virtual class to initialize Luminate and to manage the scene and camera. This is the main API entry to manipulate HOOPS Luminate.

    * ``LightingEnvironment``: Setup background, environment, and lights.

*hoops_luminate_bridge* Classes
-------------------------------

The main class for using the ``hoops_luminate_bridge`` library is ``LuminateBridge3DF`` in file ``Hoops3DFLuminateBridge.h``. 

This class is initialized with a ``HBaseView`` and uses it to retrieve all of the HV 3DF data. Here is the list of functions necessary to call when integrating it into an application:

    * ``initialize``: Initialize HOOPS Luminate by setting the license and creating the rendering window.

    * ``shutdown``: Completely shutdown Luminate instance. This will destroy and free all of the HOOPS Luminate resources.

    * ``resize``: Resize the Luminate rendering window.

    * ``syncScene``: Synchronize the HOOPS Luminate scene with the current HV 3DF scene. The previous scene will be destroyed.

    * ``draw``: Request to draw a new frame. This method must be called continuously and will check by itself if the camera must be synchronized and if a new render must be processed.


***********************************
*hoops_luminate_widgets*: Library
***********************************

The ``hoops_luminate_widgets`` project is used to regroup all of the Qt widgets used by the demo application that deals with HOOPS Luminate code. It offers a set of tool widgets and objects that are usable from the main application in order to use Luminate. 

The main class used by the ``hoops_luminate_demo`` is the ``LuminateWidget class`` located in the file ``LuminateWidget.h``.

This class is initialized with a ``HBaseView`` and uses it to instantiate ``LuminateBridge3DF``. The widget handles the call of most of the Bridge functions. 

    * The constructor calls ``LuminateBridge3DF::initialize`` in order to initiate Luminate and create the rendering window. 

    * The destructor calls ``LuminateBridge3DF.shutdown`` in order to cleanly destroy all of Luminate resources.

    * The resizeEvent calls ``LuminateBridge3DF.resize`` in order to resize the rendering window.

    * A timer is used in order to call ``LuminateBridge3DF.draw`` repetitively.


************************************************
*hoops_luminate_demo:* Qt Sandbox with Visualize
************************************************

*hoops_luminate_bridge* Functionalities: 
-----------------------------------------

The ``hoops_luminate_demo`` project is the demo application based on Qt. It use the functionalities offered by ``hoops_luminate_bridge`` in order to initialize and manipulate HOOPS Luminate data. 

    * ``HQApplication``: Main Qt application, initilializing the UI.

    * ``HQWidget``: Parent class for ``SimpleHQWidget``.

    * ``main``: Entry point of the demo.

    * ``SimpleHQWidget``: HOOPS Visualize 3DF view widget.

Others widgets are: 

    * **Material Widget**: Allows you to show the material library and apply a material to the selected segment of the geometry.

    * **Parameterization Widget**: Allows you to change the parameterization of the selected segment of the geometry, which will change how the textures will be applied to the part.

    * **Rendering Option Widget**: Allows you to manipulate all the rendering parameters of Luminate (see `here <https://docs.techsoft3d.com/luminate/latest/api/namespaceRED.html#_CPPv4N3RED7OPTIONSE>`__).

    * **Lighting Widget**: Allows you to change the lighting environment of the scene.


*hoops_luminate_demo* Classes
-----------------------------

The ``HQApplication`` calls the ``syncGeometry`` function of the widget ``LuminateWidget`` when loading a new model is requested. This function will synchronize the scene between HV 3DF and Luminate by calling ``LuminateBridge3DF.syncScene``.

The ``HQApplication`` will also be responsible to instantiate the tool widgets and link them. For communication between widgets, we use the signal and slot mechanism of Qt, allowing data to be passed from one widget to the other, and in order to communicate with the ``hoops_luminate_bridge``.

Performances / Threads
----------------------

Luminate uses a lot of threads in order to render the image efficiently. Thus, the main UI thread (or any other thread used in your application) could be slowed down during the rendering. In order to remain interactive for the user, we implemented some functionalities to pause and restart the Luminate rendering during camera manipulation. For this purpose, we use a click event on the ``SimpleHQWidget`` in order to pause and restart the Luminate rendering. 

For the zoom with the mouse wheel, we use a timer to detect the end of the scroll interaction. As soon as the user start to scroll, we interrupt the Luminate rendering and start a timer. If the user stops to scroll for more than 400ms, the rendering restarts automatically.

Sandbox Parameters
------------------

The demo application can be launched in command line with some options:

**hoops_luminate_demo.exe**

    * **".\bnc.hsf"**: Object to load (could be hsf, hmf or obj files).

    * **".\Light.hdr"**: hdr environment map to use as a background and a source of lighting.

