######################
Analyzing Performances
######################

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

    /book/subjects/bk_ap/bk_ap_hardware_display_performances
    /book/subjects/bk_ap/bk_ap_software_display_performances
    /book/subjects/bk_ap/bk_ap_memory_usage
    /book/subjects/bk_ap/bk_ap_modifying_engine_data
    /book/subjects/bk_ap/bk_ap_anti_aliasing


.. figure:: performance_monitor.png
    :align: center
    
    **The well known windows performance monitor!**

This book is about performance. Performance is key to 3d graphics, for all kinds of images that can be processed: it's key in 2D drafting for the rendering of large datasets, it's key in real-time 3D to add more effects to the rendering and it's also key to photo-realistic images generation as you don't want to spend hours waiting for one single image!

So this book will try to provide hints on how to get the best rendering performance out of HOOPS Luminate. First, we can access some measurements on what has happened during the rendering of a frame. These measurements can be found in the ``RED::FrameStatistics`` class.


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


Reading Frame Statistics
========================

As illustrated below, ``RED::FrameStatistics`` may show a lot of informations. Here's an example below captured from one of the HOOPS Luminate tutorials, using hardware rendering:

.. figure:: frame_statistics_passes.png
    :align: center
    
    **A typical RED::FrameStatistics report**

In this example, all timers have been enabled using ``RED::FrameStatistics::QueryPassTime``. Consequently, reported times are greater than the real-time that can be measured with no timers enabled, because ``RED::FrameStatistics`` timers are intrusive: they force a hardware flush before and after the measurement to really capture the amount of time spent within one single rendering pass.

The ``RED::FrameStatistics`` report is made of ``RED::ViewpointStatistics`` for each camera in each VRL, and each viewpoint statistics is composed of all the rendering passes that are needed to render that viewpoint. Therefore, back to our example above, we see:

    * A first VRL (no 0), composed of two cameras: the main scene (camera 0) and the small 3 axis scene (camera 1)
    * An auxiliary VRL (no 1), with one camera, used to render the texture with the red rotating cube, that is reused by one of the materials in the VRL 0

If we look at the pass details of the VRL no 1, camera no 0, we see:

    * A set of culling passes: These passes are CPU rendering passes, in the engine, that are looking for the set of data to render in that context
    * Rendering passes: here, we have a ``RED::RPA_PRELIT_OPAQUE`` pass and a ``RED::RPA_LIT_OPAQUE`` pass, indicating that we have something to draw in the ``RED::MTL_PRELIT`` pass of the red cube's material and at least one light to process too (see :doc:`/book/subjects/bk_bm/bk_bm_the_shading_pipeline` for details on the rendering pipeline)

If we look at the details of each pass, we'll see:

    * A number of draw calls: this is the actual number of calls to glDrawElements by HOOPS Luminate that have occurred for that pass
    * A number of matrix swaps: this is the number of interruptions during the draw to setup a new transformation matrix
    * A number of material setups: this is the number of times we had to setup the rendering pipeline (shaders, parameters, etc...)

Of course, the lower the better: reducing these numbers will increase the rendering performance for the considered pass. More on this can be found here: :doc:`/book/subjects/bk_ap/bk_ap_hardware_display_performances`.


Hardware Display
================

If you're using the GPU with HOOPS Luminate, then there are several key items to consider to reach a good performance level for your application. Some items are related to the data you send to HOOPS Luminate, and some other items are just general facts to consider for hardware rendering. Details can be found here: :doc:`/book/subjects/bk_ap/bk_ap_hardware_display_performances`.


Software Display
================

As HOOPS Luminate is a hybrid engine delivering both hardware and software rendering solutions, caution should be also taken for the setup of scenes aimed at being rendered in software. The key performance items are not the same as for hardware rendering. Software rendering is generally used to generate higher quality images than hardware rendering and thus uses different rendering algorithms to reach its objectives. Details here: :doc:`/book/subjects/bk_ap/bk_ap_software_display_performances`.


How is Memory Used?
===================

One important point to be aware of for a good graphic application is the memory consumption of the graphics. Graphic applications nowadays can use extremely large data (huge sky textures, massive meshes, etc...) and therefore it's really important to have an insight of the amount of memory consumed by the engine and by the data. If we consider a simple 2D background image, for a 4k HD rendering, we'll easily go for a 16384 x 8192 RGB HDR image, so that's up to 800 Mb of memory for a single image. You've got to be prepared to that. If it has to go to the GPU, wow, even with a 4 Gb GPU, with a single background texture you may have consumed a big part of its memory. Consider that the graphic driver keeps a copy of that image (just in case of need or if the video has to flush the texture away due to insufficient space) and still for a single texture image, you can consume nearly 2Gb of memory. That's worth noting it.

After reading this you'll think we're exaggerating, and yes, of course, you may use smaller background images. But the idea is there: screen resolutions are getting higher and higher, so does texture dimensions, and generally speaking all other resources involved in your rendering application. 

So this chapter will talk about that, and give you insights of how memory is managed by HOOPS Luminate and what happens if we're too short in memory. See here: :doc:`/book/subjects/bk_ap/bk_ap_memory_usage`.


Editing the Scene
=================

The way the engine will react to changes is also a key parameter to consider in our discussions on performances. HOOPS Luminate is a fully dynamic engine, meaning that nothing is pre-calculated and anything in the data can be changed anytime. This is true for real-time rendering, but also true for software rendering. Of course, this don't mean that changing the data or the organization of the rendered scene comes at no cost! There's a cost for each modification. Many of them are neglectable, others may require attention from the application. See the details here: :doc:`/book/subjects/bk_ap/bk_ap_modifying_engine_data`.


Using Anti Aliasing
===================

Anti-aliasing is often required for a high quality display whether be it real-time or photo-realistic. HOOPS Luminate features a wide range of anti-aliasing techniques, ranging from those that come at no cost up to pure brute force image supersampling. Learn all the details here: :doc:`/book/subjects/bk_ap/bk_ap_anti_aliasing`.

