/****************************************************************************
**
** Copyright (C) 2014 Digia Plc
** All rights reserved.
** For any questions to Digia, please use the contact form at
** http://qt.digia.com/
**
** This file is part of Qt Quick 2d Renderer.
**
** Licensees holding valid Qt Enterprise licenses may use this file in
** accordance with the Qt Enterprise License Agreement provided with the
** Software or, alternatively, in accordance with the terms contained in
** a written agreement between you and Digia.
**
** If you have questions regarding the use of this file, please use
** the contact form at http://qt.digia.com/
**
****************************************************************************/

/*!
    \page qtquick2drenderer-installation-guide.html
    \previouspage index.html
    \nextpage qtquick2drenderer-limitations.html

    \title Installation Guide

    The building of \RENDERER is complicated by the fact that \l{Qt Quick} 2
    always requires OpenGL support regardless of whether it is being used or
    not. You will need to build Qt with support for OpenGL even if the target
    system does not support it. If you have a Qt build that already supports
    OpenGL, you can skip to \l {building-renderer}{Building \RENDERER}.

    \section1 Providing the OpenGL Dependency

    \RENDERER works in such a way that it renders the Qt Quick 2 scene
    graph with QPainter, instead of using hardware acceleration via the OpenGL API.
    However, Qt Quick 2 still assumes that OpenGL is always available. With
    \RENDERER we can avoid making OpenGL calls, but that does not change the
    fact that QtQuick 2 requires the OpenGL development headers to be available
    at build-time and will link against OpenGL libraries at run-time.

    The solution is to provide a dummy OpenGL library and development
    headers to build Qt against. In this way you can build Qt with virtual OpenGL
    support and get access to the QtQuick 2 APIs. You should have no problems
    using \RENDERER provided that you use a platform plugin that does not make calls to
    EGL or OpenGL commands, and that you refrain from using APIs that access OpenGL directly.

    \section1 How to use the OpenGL Dummy Libraries

    The OpenGL dummy libraries provide both headers and shared object files
    containing the symbols for both OpenGL and EGL. The headers get copied
    into your INCLUDE path, and the shared object files get copied into your LIB
    path in both the sysroot, as well as in the target image distributed on the
    device. The library that is generated contains all the symbols needed to
    link an application as if you had support for OpenGL and EGL. It is important
    to make sure that you do not call any of these symbols in your application.

    \section2 Prerequisites

    Three elements are required:
    \list 1
        \li Toolchain to cross compile code for your device.
        \li Sysroot containing development headers and shared objects to link
        against when building applications.
        \li Target image intended to be deployed to your device.
    \endlist

    \section2 How to build the OpenGL Dummy Libraries

    Set up your build environment by defining where your compiler and sysroot
    are located:
    \badcode
    export CC=/opt/arm-toolchain/usr/bin/arm-linux-gnueabi-g++
    export SYSROOT=/opt/device-name/sysroot/
    \endcode
    Run the build script inside the client-dummy directory:
    \badcode
    cd client-dummy
    ./build-gcc.sh
    \endcode
    That should generate two files: \c libEGL.so, \c libGLESv2.so

    \section2 Installation of Files

    Copy the include folder to the /usr/include folder in your sysroot.  This
    installs the OpenGL/EGL headers:
    \badcode
    cp -r include/* ${SYSROOT}/usr/include/
    \endcode
    Copy \c libEGL.so and \c libGLESv2.so to the /usr/lib folder in your sysroot:
    \badcode
    cp src/lib*.so ${SYSROOT}/usr/lib/
    \endcode

    Copy the \c libEGL.so and \c libGLESv2.so libraries to the target device image as well.

    \section1 Building Qt

    When configuring Qt, make sure to append \c {-opengl es2} to your configure arguments.

    \target building-renderer
    \section1 Building \RENDERER

    Build \RENDERER like any other Qt module:
    \badcode
    qmake
    make
    make install
    \endcode

    \section1 Deployment

    Now, when you deploy your Qt build to the device, it will depend on the dummy
    libs \c libEGL.so and \c libGLESv2.so, but as long as you are using the \RENDERER
    plugin you will be able to use Qt Quick 2 without actually making any
    OpenGL or EGL calls.

*/