#######
Windows
#######


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

    bk_ba_w/bk_ba_configuring_a_window
    bk_ba_w/bk_ba_integration_into_an_external_opengl_window
    bk_ba_w/bk_ba_managing_multiple_windows_and_external_opengl_contexts


The window is the second object to be created in a HOOPS Luminate application, after the resource manager:

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

The window can be created using an operating system specific window handle, or it can be created directly using an existing window OpenGL setup:

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

The window is used to:

    * See something on screen
    * Manage a list of offscreen rendering buffers
    * It implements the ``RED::IWindow`` and ``RED::IOptions`` interfaces

Image and all hardware operations can't be performed before the creation of a first window by the application, because the creation of the window initializes the OpenGL driver layer. This behavior also applies even if HOOPS Luminate is started in pure software mode.

A window contains rendering buffers (:doc:`/book/subjects/bk_ba/bk_ba_viewpoint_render_lists`) that contain cameras and scene graph to display.

As many windows as wished can be created by the application. The list of windows in the application can be retrieved from a call to ``RED::IResourceManager::GetWindowList``.

This chapter also reviews different topics about window setup and usage in a HOOPS Luminate based application:

    * :doc:`/book/subjects/bk_ba/bk_ba_w/bk_ba_configuring_a_window`: Review of the different parameters that can be setup at the window creation time.
    * :doc:`/book/subjects/bk_ba/bk_ba_w/bk_ba_integration_into_an_external_opengl_window`: This is a very important topic. HOOPS Luminate can be added to an existing OpenGL application without breaking the existing application graphics. Therefore, HOOPS Luminate graphics can be added to the application without having to rewrite everything.
    * :doc:`/book/subjects/bk_ba/bk_ba_w/bk_ba_managing_multiple_windows_and_external_opengl_contexts`: This paragraph will go further in the configuration and detail how HOOPS Luminate can be used in the scope of an existing multiple window application and smoothly insert its own graphics.


*********************************
Window and Viewpoint Render Lists
*********************************

.. figure:: window_vrl_buffers.png 
    :align: center
    
    **The relationship between a window and the list of VRL it stores**

A 'viewpoint render list' or VRL for short is either an onscreen or offscreen rendering buffer that owns a list of viewpoints to render. The window owns a default VRL at its creation. This VRL can be accessed using ``RED::IWindow::GetDefaultVRL``. This default VRL is associated with the onscreen rendering buffer of the application window specified at the HOOPS Luminate window creation. This means that the data rendered by this VRL will be displayed in the application window display area - if the application has a screen display, of course.

An auxiliary VRL must be created using ``RED::IWindow::CreateVRL`` and accessed using ``RED::IWindow::GetVRL``. The contents of an auxiliary VRL is rendered into an OpenGL offscreen rendering buffer. Depending on the hardware driver, GPU and operating system, this may be an OpenGL p-buffer or an OpenGL Framebuffer object.

If HOOPS Luminate runs in software mode, all the VRLs are rendered in software into the CPU memory. If HOOPS Luminate runs in hybrid modes, all the VRLs are rendered in hardware into the GPU memory.


*****************
Rendering Methods
*****************

The ``RED::IWindow`` interface provides all the HOOPS Luminate rendering methods. A rendering method is one of the 'RED::IWindow::FrameXXX' methods that can be found in the method's listing of the interface. Any rendering method will render all the VRLs of the window in sequence, from the last VRL to the first VRL (the default VRL).

We have three different categories of rendering methods:

    * ``RED::IWindow::FrameDrawing``: This is the hardware rendering call used to render a window contents using the GPU
    * ``RED::IWindow::FrameTracing``, ``RED::IWindow::FrameTracingImages``, ``RED::IWindow::FrameTracingImageLayers``, ``RED::IWindow::FrameTracingGICache``: All these rendering methods will render all ray-traced viewpoints found in all VRLs using HOOPS Luminate's software ray-tracer, and will render all non ray-traced viewpoints found using hardware rendering
    * ``RED::IWindow::FramePicking`` and ``RED::IWindow::FramePickingRectangle``: these are two pure CPU rendering calls (they don't do any GPU operation) that perform picking inside the window contents to find which data is hit by a picking ray or rectangular area


