/**
\page tutorial-ogre Rendering a 3D scene with Ogre
\tableofcontents

\section tutorial-ogre-intro 1. Introduction

[Ogre](https://www.ogre3d.org/) is a cross-platform 3D rendering library. It is open-source and hosted on [github](https://github.com/OGRECave).

This renderer can output a color image, with support for textures and lighting.

It can also be used in the Model-Based Tracker to check the visibility of the object (see \ref mbdep_settings_visibility_ogre).
There is also the optional [OIS](https://github.com/wgois/OIS) library that can be used to animate the rendered object using the keyboard.

\section tutorial-ogre-install 2. Ogre installation
\subsection tutorial-ogre-install-ubuntu 2.1. Installation on Ubuntu

- It is recommended to install Ogre and OIS from the apt packages.

  To install the 1.9 version of Ogre, run:
  \code{.sh}
  $ sudo apt install libogre-1.9-dev libois-dev
  \endcode

  To install the 1.12 version of Ogre, run:
  \code{.sh}
  $ sudo apt install libogre-1.12-dev libois-dev
  \endcode

  Other Ogre packages exist but their compatibility with ViSP has not been tested at the moment.

- If you want newer versions of Ogre, you can download the sources and compile it manually.

  First, install Ogre dependencies:
  \code{.sh}
  $ sudo apt install libgles2-mesa-dev libvulkan-dev glslang-dev libxrandr-dev libxaw7-dev libx11-dev libzzip-dev libsdl2-dev libois-dev
  \endcode

  Then, get Ogre sources and compile it:
  \code{.sh}
  $ mkdir -p $VISP_WS/3rdparty
  $ cd $VISP_WS/3rdparty
  $ git clone https://github.com/OGRECave/ogre
  $ cd ogre
  $ git checkout $OGRE_VERSION # where OGRE_VERSION is a tag name corresponding to a version of ogre, such as v13.1.0 or v14.0.0
  $ mkdir build && mkdir install && cd build
  $ cmake ../ -DCMAKE_INSTALL_PREFIX=$VISP_WS/3rdparty/ogre/install
  $ make -j$(nproc) install
  \endcode

  \note Only the tags v1.12.10 , v13.1.0 and v14.0.0 were tested.

  Finally, to build ViSP with Ogre support, run the following commands:
  \code{.sh}
  $ cd $VISP_WS/visp-build
  $ cmake ../visp -DOGRE_DIR=$VISP_WS/3rdparty/ogre/install/lib/OGRE/cmake/
  $ make -j$(nproc)
  \endcode

\subsection tutorial-ogre-install-windows 2.2. Installation on Windows (MSVC)

- Download [Pre-built SDK](https://www.ogre3d.org/download/sdk/sdk-ogre#) for Windows (MSVC). At the time this tutorial
  was written, we downloaded `ogre-sdk-v14.4.1-msvc142-x64.zip` file.
- Unzip the Pre-built SDK in `%%VISP_WS%\3rdparty\ogre-sdk-v14.4.1-msvc142-x64`
- Set `OGRE_DIR` environment var with the location of the SDK uding a Command (`cmd`) line terminal
\code{.sh}
C:\> setx OGRE_DIR %VISP_WS%\3rdparty\ogre-sdk-v14.4.1-msvc142-x64
\endcode
- Modify `Path` environment variable to add the path to Ogre dlls. In our case we added `%%OGRE_DIR%\bin`.
- Close all the Command line terminals to ensure that both environment variables are taken into account.

\subsection tutorial-ogre-install-otherplatforms 2.3.Installation on other platforms

- See [Ogre download section](https://www.ogre.org/download/sdk/sdk-ogre) to see the available binaries
  or the [Ogre building guide](https://ogrecave.github.io/ogre/api/latest/building-ogre.html) to see how to compile
  it from sources.

\section tutorial-ogre-usage 3.Using Ogre for rendering

An example that shows how to exploit Ogre in ViSP to render a color image with support for textures and lighting in
camera space is given in AROgre.cpp.

This example reads a sequence of images, on each image calculates the pose of the camera with respect the a
frame located at the center of the 4 small blobs, then using the estimated pose, renders a new image with the image
of the sequence in the background, augmented by a grass plate and an animated robot.

To be able to run the program, you need to have downloaded [ViSP dataset](https://github.com/lagadic/visp-images) and
correctly made ViSP detect this dataset (following e.g. \ref install_brew_dataset \ref install_win10_mingw_dataset or \ref install_ubuntu_dataset)

\subsection tutorial-ogre-usage-inheriting-class 3.1 Inheriting from vpAROgre to extend its functionalities.

In order to extend the default behavior, we will write a class `vpAROgreExample` that inherits from the `vpAROgre` class.
A class inheriting from the `vpAROgre` class should be instanciated with the camera parameters that must be used to
render the scene (which correspond to the real camera in case of an Augmented Reality application). The width and height
of the rendering window must also be given.

The vpAROgre::init() method must be called in order to load the resources and create the
Ogre scene. It should be called either with a color image or a gray-scale image. You should also
indicate if you want to listen to keyboard events (which is possible only if you install OIS library on your computer)
and if you want to hide the rendering window.

\note When using Ogre 14.0.0, the hidden attribute does not seem to work.

The creation and initialization of the `vpAROgreExample` object can be found below:
\snippet AROgre.cpp Ogre initialization

It will call the overriden vpAROgre::createScene() method that creates the different components needed in the scene.

A light must be added in the scene for the rendering. The Ogre API must be used to do so:
\snippet AROgre.cpp Light creation

Additionally, the robot that we want to insert in our AR application must be added to the scene:
\snippet AROgre.cpp Mesh insertion

To make it more fun, let's animate the robot:
\snippet AROgre.cpp Animating the mesh

To update the animation, the following method must be defined and will be called at the end of each frame:
\snippet AROgre.cpp Updating the animation

To make it less weird, we will add a plane on which the robot will stand:
\snippet AROgre.cpp Ground insertion

Finally, a method to manage keyboard events is written in case of the OIS library is installed:
\snippet AROgre.cpp Listening for keyboard events

\subsection tutorial-ogre-usage-rendering-loop 3.2. Rendering loop

The rendering loop is given below:
\snippet AROgre.cpp Rendering loop

First, the image is acquired and converted in gray-scale format:
\snippet AROgre.cpp Image acquisition

Then, the pose of the object in the image is computed from the tracked dots:
\snippet AROgre.cpp Pose computation

This pose is then used by the renderer in order to display the virtual object at the correct
location in the image:
\snippet AROgre.cpp Rendering

\section tutorial-ogre-full-code 4. Tutorial full code

The full code of AROgre.cpp is given below.
\include AROgre.cpp

\section tutorial-ogre-run 5.Running the tutorial

Once ViSP is built, you may run the tutorial by:
\code{.sh}
$ cd $VISP_WS/visp-build/example/ogre-simulator
$ ./AROgre -c
\endcode

The `-c` option permits not to click on the dots of the marker when initializing the sequence.

When this `-c` option is not used, you have to click counter clockwise on the 4 small white blobs like in the following image:
\image html img-ogre-init-pose.jpg Location of the points to click to initialize AROgre example.

A window will appear to select the value of the Ogre settings, such as should we display in `Full Screen` mode or the
`Video Mode` that specifies the size of the window that will appear to render the sceen.
\image html img-ogre-settings-windows.jpg Ogre settings window.

Once settings are accepted, you should see a virtual robot moving on a grass floor. When OIS third-party is
enabled, this robot can be animated using keyboard arrows.

\image html img-ogre-robot.jpg Robot added in augmented reality.

\section tutorial-ogre-issue 6. Known issues
\subsection tutorial-ogre-issue-library-texture 6.1. Texture not displayed

When running the example, the texture of the robot can not be displayed properly.
Changing the rendering subsystem should fix the issue.

\subsection tutorial-ogre-issue-display 6.2. Problem of display with OpenGL ES renderer

When using `OpenGL ES renderer`, the window might appear entirely black.
Chosing another renderer subsystem like `OpenGL Rendering SubSystem` should fix the issue.
*/
