Doc: Add some basic documentation

Change-Id: Id6f986bc5d46912355f42e6ae8d72fe2738c2c19
Reviewed-by: Laszlo Agocs <laszlo.agocs@theqtcompany.com>

10 files changed, 385 insertions, 65 deletions

diff --git a/doc/qtquick2drenderer.qdocconf b/doc/qtquick2drenderer.qdocconf
deleted file mode 100644
index e69961c00f..0000000000
--- a/doc/qtquick2drenderer.qdocconf
+++ /dev/null
@@ -1,31 +0,0 @@
-include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
-
-navigation.homepage = "Qt Quick 2D Renderer"
-buildversion = "Qt Quick 2D Renderer $QT_VERSION Reference Documentation"
-
-project = QtQuick2dRenderer
-description = Qt Quick 2D Renderer
-version = $QT_VERSION
-
-sourcedirs += .
-headerdirs += .
-
-imagedirs += images
-
-depends += qtcore qtgui qtquick
-
-qhp.projects            = QtQuick2dRenderer
-
-qhp.QtQuick2dRenderer.file                = qtquick2drenderer.qhp
-qhp.QtQuick2dRenderer.namespace           = com.digia.qtquick2drenderer.$QT_VERSION_TAG
-qhp.QtQuick2dRenderer.virtualFolder       = qtquick2drenderer
-qhp.QtQuick2dRenderer.indexTitle          = Qt Quick 2D Renderer
-
-qhp.QtQuick2dRenderer.filterAttributes    = qtquick2drenderer $QT_VERSION
-qhp.QtQuick2dRenderer.customFilters.Qt.name = QtQuick2dRenderer $QT_VERSION
-qhp.QtQuick2dRenderer.customFilters.Qt.filterAttributes = qtquick2drenderer $QT_VERSION
-
-qhp.QtQuick2dRenderer.subprojects                   = manual
-qhp.QtQuick2dRenderer.subprojects.manual.title      = Qt Quick 2D Renderer
-qhp.QtQuick2dRenderer.subprojects.manual.indexTitle = Qt Quick 2D Renderer
-qhp.QtQuick2dRenderer.subprojects.manual.type       = manual
diff --git a/doc/qtquick2drenderer_overview.qdoc b/doc/qtquick2drenderer_overview.qdoc
deleted file mode 100644
index 8d6e37f312..0000000000
--- a/doc/qtquick2drenderer_overview.qdoc
+++ /dev/null
@@ -1,26 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2013 Digia Plc and/or its subsidiary(-ies).
-** Contact: http://www.qt-project.org/legal
-**
-** This file is part of the documentation of QtQuick 2D Renderer.
-**
-** $QT_BEGIN_LICENSE:FDL$
-** Commercial License Usage
-** Licensees holding valid commercial Qt licenses may use this file in
-** accordance with the commercial license agreement provided with the
-** Software or, alternatively, in accordance with the terms contained in
-** a written agreement between you and Digia.  For licensing terms and
-** conditions see http://qt.digia.com/licensing.  For further information
-** use the contact form at http://qt.digia.com/contact-us.
-**
-****************************************************************************/
-
-/*!
-\page qtquick2drenderer-index.html
-\contentspage {qtquick2drenderer-index.html}{Contents}
-
-\title Qt Quick 2D Renderer
-
-The Qt Quick 2D Renderer is a scenegraph plugin that allows QtQuick 2 applications to be run on systems without support for OpenGL.
-*/
diff --git a/scenegraph-raster.pro b/scenegraph-raster.pro
index d1417303b8..58c33f27ca 100644
--- a/scenegraph-raster.pro
+++ b/scenegraph-raster.pro
@@ -1,8 +1 @@
 load(qt_parts)
-
-QMAKE_DOCS = $$PWD/doc/qtquick2drenderer.qdocconf
-load(qt_docs)
-OTHER_FILES += \
-               doc/qtquick2drenderer_overview.qdoc \
-               doc/qtquick2drenderer.qdocconf
-
diff --git a/src/doc/config/qtquick2drenderer.qdocconf b/src/doc/config/qtquick2drenderer.qdocconf
new file mode 100644
index 0000000000..bf4791e6fd
--- /dev/null
+++ b/src/doc/config/qtquick2drenderer.qdocconf
@@ -0,0 +1,54 @@
+include($QT_INSTALL_DOCS/global/qt-html-templates-offline.qdocconf)
+include($QT_INSTALL_DOCS/global/qt-cpp-defines.qdocconf)
+include($QT_INSTALL_DOCS/global/fileextensions.qdocconf)
+
+HTML.nobreadcrumbs    = "true"
+
+HTML.footer = \
+    "  <div class=\"ft\">\n" \
+    "    <span></span>\n" \
+    "  </div>\n" \
+    "</div> \n" \
+    "<div class=\"footer\">\n" \
+    "    <p>\n" \
+    "      <acronym title=\"Copyright\">&copy;</acronym> 2014 Digia Plc and/or its\n" \
+    "      subsidiaries.</p>\n" \
+    "    <p>\n" \
+    "       Licensees holding valid Qt Commercial licenses may use this document in\n" \
+    "       accordance with the Qt Commercial License Agreement provided with the\n" \
+    "       Software or, alternatively, in accordance with the terms contained in a\n" \
+    "       written agreement between you and Digia.<\p>\n" \
+    "    <p>\n" \
+    "      Digia, Qt and their respective logos are trademarks of Digia Plc \n" \
+    "      in Finland and/or other countries worldwide. All other trademarks are property\n" \
+    "      of their respective owners. <a title=\"Privacy Policy\"\n" \
+    "      href=\"http://qt.digia.com/Digia-Legal-Notice--Privacy-Policy/\">Privacy Policy</a></p>\n" \
+    "</div>\n"
+
+naturallanguate             = en_US
+outputencoding              = UTF-8
+sourceencoding              = UTF-8
+
+projects                    = QtQuick2dRenderer
+description                 = Qt Quick 2D Renderer Documentation
+version                     = $QT_VERSION
+
+sourcedirs                   = ../src
+imagedirs                    += ../images
+
+qhp.projects            = QtQuick2dRenderer
+
+qhp.QtQuick2dRenderer.file                  = qtquick2drenderer.qhp
+qhp.QtQuick2dRenderer.namespace             = com.digia.qtquick2drenderer.$QT_VERSION_TAG
+qhp.QtQuick2dRenderer.virtualFolder         = qtquick2drenderer
+qhp.QtQuick2dRenderer.indexTitle            = Qt Quick 2D Renderer Documentation
+qhp.QtQuick2dRenderer.indexRoot             =
+
+qhp.QtQuick2dRenderer.subprojects           = manual
+qhp.QtQuick2dRenderer.manual.index          = Qt Quick 2D Renderer
+qhp.QtQuick2dRenderer.manual.indexTitle     = Qt Quick 2D Renderer
+qhp.QtQuick2dRenderer.manual.type           = manual
+
+macro.RENDERER                    = "Qt Quick 2D Renderer"
+
+navigation.landingpage = "Qt Quick 2D Renderer"
diff --git a/src/doc/doc.pro b/src/doc/doc.pro
new file mode 100644
index 0000000000..1077195338
--- /dev/null
+++ b/src/doc/doc.pro
@@ -0,0 +1,9 @@
+TEMPLATE = aux
+QMAKE_DOCS = $$PWD/config/qtquick2drenderer.qdocconf
+
+OTHER_FILES += \
+    $$PWD/config/qtquick2drenderer.qdocconf \
+    $$PWD/src/qtquick2drenderer-index.qdoc \
+    $$PWD/src/qtquick2drenderer-installation-guide.qdoc \
+    $$PWD/src/qtquick2drenderer-performance.qdoc \
+    $$PWD/src/qtquick2drenderer-limitations.qdoc
diff --git a/src/doc/src/qtquick2drenderer-index.qdoc b/src/doc/src/qtquick2drenderer-index.qdoc
new file mode 100644
index 0000000000..b86b8dc9c2
--- /dev/null
+++ b/src/doc/src/qtquick2drenderer-index.qdoc
@@ -0,0 +1,49 @@
+/****************************************************************************
+**
+** 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/
+**
+****************************************************************************/
+
+/*!
+    \contentspage{index.html}{Qt Quick 2D Renderer}
+    \page index.html
+    \nextpage qtquick2drenderer-installation-guide.html
+    \title Qt Quick 2D Renderer
+
+    \RENDERER is an alternative renderer for Qt Quick 2 that uses the Raster
+    paint engine to render the contents of the scene graph instead of OpenGL.
+    As a result of not using OpenGL to render the scene graph some features
+    and optimizations are no longer available. Most Qt Quick 2 applications
+    will run without modification though any attempts to use unsupported
+    features will be ignored. By using the \RENDERER is now possible to run Qt
+    Quick 2 applications on hardware and platforms that do not have OpenGL
+    support.
+
+    \RENDERER is a Qt module that contains a scene graph renderer plugin.
+
+    To use \RENDERER add the following to your run environment:
+    \badcode
+    export QMLSCENE_DEVICE=softwarecontext
+    \endcode
+
+    \section1 Contents
+
+    \list
+        \li \l{Installation Guide}
+        \li \l{Limitations}
+        \li \l{Performance Guide}
+    \endlist
+*/
diff --git a/src/doc/src/qtquick2drenderer-installation-guide.qdoc b/src/doc/src/qtquick2drenderer-installation-guide.qdoc
new file mode 100644
index 0000000000..6dd2386f4d
--- /dev/null
+++ b/src/doc/src/qtquick2drenderer-installation-guide.qdoc
@@ -0,0 +1,127 @@
+/****************************************************************************
+**
+** 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/
+**
+****************************************************************************/
+
+/*!
+    \contentspage{index.html}{Qt Quick 2D Renderer}
+    \page qtquick2drenderer-installation-guide.html
+    \previouspage index.html
+    \nextpage qtquick2drenderer-limitations.html
+
+    \title Installation Guide
+
+    The building of \RENDERER is made complicated by the fact that Qt Quick 2
+    always requires OpenGL support regardless of whether is is being used or
+    not. You will need to build Qt with support for OpenGL even if the target
+    system does not have support for using it. If you have a build of Qt that
+    already supports OpenGL you can skip to Building \RENDERER
+
+    \target Providing the OpenGL Dependency
+    \section1 Providing the OpenGL Dependency
+
+    The way that \RENDERER works is to render 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 to is to provide a dummy OpenGL library and development
+    headers to build Qt against. This way you can build Qt with virtual OpenGL
+    support and get access to the QtQuick 2 APIs. Provided you use a platform
+    plugin that does not make calls EGL or OpenGL commands, and you refrain
+    from using APIs that access OpenGL directly you should have no problems
+    using \RENDERER.
+
+    \target How to use the OpenGL dummy libraries
+    \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 gets 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.
+
+    \target Prerequisites
+    \section2 Prerequisites
+
+    You need to have three things:
+    \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 inteded to be deployed to your device.
+    \endlist
+
+    \target How to build the OpenGL dummy libraries
+    \section2 How to build the OpengL dummy libraries
+
+    Setup 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 a two files: libEGL.so, libGLESv2.so
+
+    \target Installation of Files
+    \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 libEGL.so and libGLESv2.so to the /usr/lib folder in your sysroot:
+    \badcode
+    cp src/lib*.so ${SYSROOT}/usr/lib/
+    \endcode
+
+    Copy the libEGL.so and libGLESv2.so libraries to the target device image as well.
+
+    \target Building Qt
+    \section1 Building Qt
+
+    When configuring Qt make sure to append -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
+
+    \target Deployment
+    \section1 Deployment
+
+    Now when you deploy your Qt build to the device it will depend on the dummy
+    libs libEGL.so and 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.
+
+*/
diff --git a/src/doc/src/qtquick2drenderer-limitations.qdoc b/src/doc/src/qtquick2drenderer-limitations.qdoc
new file mode 100644
index 0000000000..26d522652f
--- /dev/null
+++ b/src/doc/src/qtquick2drenderer-limitations.qdoc
@@ -0,0 +1,58 @@
+/****************************************************************************
+**
+** 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/
+**
+****************************************************************************/
+
+/*!
+    \contentspage{index.html}{Qt Quick 2D Renderer}
+    \page qtquick2drenderer-limitations.html
+    \previouspage qtquick2drenderer-installation-guide.html
+    \nextpage qtquick2drenderer-performance.html
+
+    \title Limitations
+
+    Qt Quick 2 was designed to take full advantage of OpenGL to make the most
+    out of available graphics hardware.  By not relying on OpenGL, \RENDERER
+    presents certain limitations regarding the available features.
+
+    Since \RENDERER does not use OpenGL there are some features that can not be
+    supported.  The following are known limitations:
+
+    \target ShaderEffects
+    \section1 ShaderEffects
+    ShaderEffect components in QtQuick 2 can not be rendered with \RENDERER.
+
+    \target QtGraphicalEffects
+    \section1 QtGraphicalEffects
+    QtGraphicalEffects uses ShaderEffect items to render effects.  If you use a
+    graphical effect from QtGraphicalEffects the you should not hide the source
+    item so that the original item can still be rendered.
+
+    \target Particles
+    \section1 Particles
+    It is not possible to render particle effects with \RENDERER. Whenever
+    possible, remove particles completely from the scene. Otherwise, even
+    though they are not visible with \RENDERER, a certain amount of processing
+    is done for them.
+
+    \target Sprites
+    \section1 Sprites
+    The Sprite item depends on OpenGL functions we dont have access to and will
+    not be visible.
+
+
+*/
diff --git a/src/doc/src/qtquick2drenderer-performance.qdoc b/src/doc/src/qtquick2drenderer-performance.qdoc
new file mode 100644
index 0000000000..3254c33e24
--- /dev/null
+++ b/src/doc/src/qtquick2drenderer-performance.qdoc
@@ -0,0 +1,85 @@
+/****************************************************************************
+**
+** 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/
+**
+****************************************************************************/
+
+/*!
+    \contentspage{index.html}{Qt Quick 2D Renderer}
+    \page qtquick2drenderer-performance.html
+    \previouspage qtquick2drenderer-limitations.html
+
+    \title Performance Guide
+
+    Since \RENDERER does not use OpenGL we loose the ability to use many
+    optimizations that can improve rendering speed. To get the most out of
+    \RENDERER there are some guidelines that should be followed.
+
+    \target 2D Hardware Acceleration
+    \section1 2D Hardware Acceleration
+
+    \RENDERER is designed to use operations that can be accelerated by 2D
+    acceleration hardware.  By using platform plugins that take advantage of
+    the QBlitter API (like DirectFB) is is possible to make use of such 2D
+    hardware acceleration.
+
+    \target Animation
+    \section1 Animation
+
+    It is important to keep in mind the fact that with Qt Quick 2 every time
+    a node in the scene graph is marked dirty the entire window will need to be
+    rendered again. There is no partial update mechanimism that will only
+    update the regions of the window that are dirty. This means that any
+    animation that is running will be forcing a full repaint of the window and
+    with \RENDERER this can cause heavy CPU load.
+
+    \target Transforms
+    \section1 Transforms
+
+    When rendering the scene graph with the OpenGL renderer transformations
+    come with no performance penality. This is not the case with \RENDERER.
+    Translation operations do not come with performance penalties but scaling
+    and rotation transformations should be avoided when possible.
+
+    \target Hidden Items
+    \section1 Hidden Items
+
+    \RENDERER will paint all items that are not hidden explicitly with either
+    the visibility property or an opacity of 0. Without OpenGL there is no
+    depth buffer to check for items completely obscured by opaque items, so
+    everything will be painted even if it is unnecessary.
+
+    \target Pixel Fill Budget
+    \section1 Pixel Fill Budget
+
+    When developing an application that will be using \RENDERER it is important
+    to keep in mind your pixel fill budget, or the the amount of pixels you
+    can push to the screen in the time needed for your target framerate.  For
+    example if your goal is to render your application at 60 frames per second
+    then you have about 16 milliseconds render to the framebuffer before
+    needing flush the pixels to screen.  Depending on your hardware's
+    performance you will only be able to handle a finite amount of pixel write
+    operations before the 16 milliseconds expires.  The interface you design
+    should take into consideration that each item that is added subtracts from
+    your pixel fill budget.
+
+    \RENDERER uses the painters algorithm to paint each item in the scene
+    back-to-front.  If you have an interface that stacks many items on top of
+    each other keep in mind that each layer is painted completely, not just the
+    parts that are visible.  It can be very easy to waste your pixel fill
+    budget with too many over-paints.
+
+*/
diff --git a/src/src.pro b/src/src.pro
index 49e04edcca..6e300dc9bf 100644
--- a/src/src.pro
+++ b/src/src.pro
@@ -1,2 +1,4 @@
 TEMPLATE = subdirs
-SUBDIRS += plugins
+SUBDIRS += \
+    plugins \
+    doc