From 88690a7c78dc19fb43f3936aa56cd45f18b8e2dd Mon Sep 17 00:00:00 2001 From: Andy Nichols Date: Fri, 12 Sep 2014 14:29:57 +0200 Subject: Doc: Add some basic documentation Change-Id: Id6f986bc5d46912355f42e6ae8d72fe2738c2c19 Reviewed-by: Laszlo Agocs --- doc/qtquick2drenderer.qdocconf | 31 ----- doc/qtquick2drenderer_overview.qdoc | 26 ----- scenegraph-raster.pro | 7 -- src/doc/config/qtquick2drenderer.qdocconf | 54 +++++++++ src/doc/doc.pro | 9 ++ src/doc/src/qtquick2drenderer-index.qdoc | 49 ++++++++ .../src/qtquick2drenderer-installation-guide.qdoc | 127 +++++++++++++++++++++ src/doc/src/qtquick2drenderer-limitations.qdoc | 58 ++++++++++ src/doc/src/qtquick2drenderer-performance.qdoc | 85 ++++++++++++++ src/src.pro | 4 +- 10 files changed, 385 insertions(+), 65 deletions(-) delete mode 100644 doc/qtquick2drenderer.qdocconf delete mode 100644 doc/qtquick2drenderer_overview.qdoc create mode 100644 src/doc/config/qtquick2drenderer.qdocconf create mode 100644 src/doc/doc.pro create mode 100644 src/doc/src/qtquick2drenderer-index.qdoc create mode 100644 src/doc/src/qtquick2drenderer-installation-guide.qdoc create mode 100644 src/doc/src/qtquick2drenderer-limitations.qdoc create mode 100644 src/doc/src/qtquick2drenderer-performance.qdoc 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 = \ + "
\n" \ + " \n" \ + "
\n" \ + " \n" \ + "
\n" \ + "

\n" \ + " © 2014 Digia Plc and/or its\n" \ + " subsidiaries.

\n" \ + "

\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" \ + "

\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. Privacy Policy

\n" \ + "
\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 -- cgit v1.2.3