aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
authorAndy Nichols <andy.nichols@digia.com>2014-09-12 14:29:57 +0200
committerAndy Nichols <andy.nichols@digia.com>2014-11-18 13:39:15 +0200
commit88690a7c78dc19fb43f3936aa56cd45f18b8e2dd (patch)
treea55a2f22b2c017867a341bc4d0b9b3ed62825042 /src
parent9dcb3e901a179f9211e5431ec966fb0b7de01429 (diff)
Doc: Add some basic documentation
Change-Id: Id6f986bc5d46912355f42e6ae8d72fe2738c2c19 Reviewed-by: Laszlo Agocs <laszlo.agocs@theqtcompany.com>
Diffstat (limited to 'src')
-rw-r--r--src/doc/config/qtquick2drenderer.qdocconf54
-rw-r--r--src/doc/doc.pro9
-rw-r--r--src/doc/src/qtquick2drenderer-index.qdoc49
-rw-r--r--src/doc/src/qtquick2drenderer-installation-guide.qdoc127
-rw-r--r--src/doc/src/qtquick2drenderer-limitations.qdoc58
-rw-r--r--src/doc/src/qtquick2drenderer-performance.qdoc85
-rw-r--r--src/src.pro4
7 files changed, 385 insertions, 1 deletions
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