summaryrefslogtreecommitdiffstats
path: root/src/doc
diff options
context:
space:
mode:
authorTopi Reinio <topi.reinio@qt.io>2018-02-07 13:21:09 +0100
committerTopi Reiniƶ <topi.reinio@qt.io>2018-02-09 12:07:25 +0000
commitc8964b8f1cf56718a189b0f57bad446cec30a8b8 (patch)
tree221f917586c8c50f862361cc7c41e0865499e4ef /src/doc
parentc8a48a9a28889598cb2a06fc8d5deb9b803509ca (diff)
Doc: Divide documentation into submodules
QDoc in Qt 5.11 will use Clang (libclang) to parse C++ documentation. In order to do that, Clang needs to have the include paths available when parsing source; qmake provides that information to QDoc but only when the documentation project is located under the correct module (source) path. By having dedicated doc projects for Qt 3D Core, Render, Input, etc. the number of documentation warnings is signicantly reduced. A top-level 'Qt 3D' project is still kept, and contains the landing page, overview, examples, and top-level 'C++ classes' and 'QML types' pages that list all types documented across all Qt 3D submodules. Change-Id: Id5936de36f31c2a8764a64e1e9d7ae0d10e8ab14 Reviewed-by: Martin Smith <martin.smith@qt.io>
Diffstat (limited to 'src/doc')
-rw-r--r--src/doc/qt3d-config.qdocconf36
-rw-r--r--src/doc/qt3d.qdocconf91
-rw-r--r--src/doc/src/levelofdetailloader.qdoc57
-rw-r--r--src/doc/src/qcircularbuffer.qdoc1590
-rw-r--r--src/doc/src/qmlextracontrollers.qdoc170
-rw-r--r--src/doc/src/qmlextramaterials.qdoc568
-rw-r--r--src/doc/src/qt3d-module.qdoc38
-rw-r--r--src/doc/src/qt3danimation-module.qdoc228
-rw-r--r--src/doc/src/qt3dextras-module.qdoc128
-rw-r--r--src/doc/src/qt3dinput-module.qdoc75
-rw-r--r--src/doc/src/qt3dlogic-module.qdoc75
-rw-r--r--src/doc/src/qt3drender-framegraph.qdoc518
-rw-r--r--src/doc/src/qt3drender-geometry.qdoc154
-rw-r--r--src/doc/src/qt3drender-module.qdoc100
-rw-r--r--src/doc/src/qt3drender-protips.qdoc130
-rw-r--r--src/doc/src/qt3dscene2d-module.qdoc94
16 files changed, 58 insertions, 3994 deletions
diff --git a/src/doc/qt3d-config.qdocconf b/src/doc/qt3d-config.qdocconf
new file mode 100644
index 000000000..b5f1fad8f
--- /dev/null
+++ b/src/doc/qt3d-config.qdocconf
@@ -0,0 +1,36 @@
+examplesinstallpath = qt3d
+
+# Dependencies to Qt documentation
+depends += qtcore qtgui qtqml qtquick qtdoc qmake
+
+# Exclude private header files from the documentation build
+excludefiles += "*_p.h"
+
+examples.fileextensions += "*.fraq *.geom *.vert"
+examples.imageextensions += "*.png"
+
+macro.TODO = " "
+
+Cpp.ignoretokens += QT3DINPUTSHARED_EXPORT \
+ QT3DCORESHARED_EXPORT \
+ QT3DLOGIC_PRIVATE_EXPORT \
+ QT3DLOGICSHARED_EXPORT \
+ QT3DRENDERSHARED_EXPORT \
+ QT3DRENDERSHARED_PRIVATE_EXPORT \
+ QT3DQUICKSHARED_PRIVATE_EXPORT \
+ QT3DEXTRASSHARED_EXPORT \
+ QT3DANIMATIONSHARED_EXPORT \
+ QT3DQUICKSCENE2DSHARED_EXPORT
+
+Cpp.ignoredirectives += Q_DECLARE_LOGGING_CATEGORY
+
+manifestmeta.highlighted.names = \
+ "Qt3D/Qt 3D: Advanced custom material QML Example" \
+ "Qt3D/Qt 3D: Audio Visualizer Example" \
+ "Qt3D/Qt 3D: Planets QML Example"
+
+manifestmeta.thumbnail.names += "Qt3D/Qt 3D: Deferred Renderer C++ Example"
+
+navigation.landingpage = "Qt 3D"
+navigation.cppclassespage = "Qt 3D C++ Classes"
+navigation.qmltypespage = "Qt 3D QML Types"
diff --git a/src/doc/qt3d.qdocconf b/src/doc/qt3d.qdocconf
index 7da047ced..b397f1837 100644
--- a/src/doc/qt3d.qdocconf
+++ b/src/doc/qt3d.qdocconf
@@ -1,17 +1,10 @@
include($QT_INSTALL_DOCS/global/qt-module-defaults.qdocconf)
+include(qt3d-config.qdocconf)
project = Qt3D
description = Qt 3D Reference Documentation
version = $QT_VERSION
-examplesinstallpath = qt3d
-
-indexes += $QT_INSTALL_DOCS/qtcore/qtcore.index \
- $QT_INSTALL_DOCS/qtgui/qtgui.index \
- $QT_INSTALL_DOCS/qtqml/qtqml.index \
- $QT_INSTALL_DOCS/qtquick/qtquick.index \
- $QT_INSTALL_DOCS/qmake/qmake.index
-
qhp.projects = Qt3D
qhp.Qt3D.file = qt3d.qhp
@@ -24,87 +17,33 @@ qhp.Qt3D.filterAttributes = qt3d $QT_VERSION qtrefdoc
qhp.Qt3D.customFilters.Qt.name = Qt3D $QT_VERSION
qhp.Qt3D.customFilters.Qt.filterAttributes = qt3d $QT_VERSION
-qhp.Qt3D.subprojects = classes qmltypes
+qhp.Qt3D.subprojects = classes qmltypes examples
qhp.Qt3D.subprojects.classes.title = C++ Classes
qhp.Qt3D.subprojects.classes.indexTitle = Qt 3D C++ Classes
-qhp.Qt3D.subprojects.classes.selectors = class fake:headerfile
+qhp.Qt3D.subprojects.classes.selectors = class doc:headerfile
qhp.Qt3D.subprojects.classes.sortPages = true
qhp.Qt3D.subprojects.qmltypes.title = QML Types
qhp.Qt3D.subprojects.qmltypes.indexTitle = Qt 3D QML Types
-qhp.Qt3D.subprojects.qmltypes.selectors = qmlclass
+qhp.Qt3D.subprojects.qmltypes.selectors = qmltype
qhp.Qt3D.subprojects.qmltypes.sortPages = true
-tagfile = qt3d.tags
-
-depends += qtcore qtgui qtqml qtquick qtdoc
+qhp.Qt3D.subprojects.examples.title = Examples
+qhp.Qt3D.subprojects.examples.indexTitle = Qt 3D Examples
+qhp.Qt3D.subprojects.examples.selectors = doc:example
+qhp.Qt3D.subprojects.examples.sortPages = true
-headerdirs += . \
- ../render \
- ../core \
- ../logic \
- ../plugins \
- ../quick3d/quick3d \
- ../input \
- ../extras \
- ../animation \
- ../quick3d/quick3dscene2d
+# dependencies to other Qt 3D modules
+depends += qt3dcore qt3drender qt3dlogic qt3dinput \
+ qt3dextras qt3danimation qt3dscene2d
-# Exclude private header files from the documentation build
-excludefiles += "*_p.h"
+tagfile = qt3d.tags
-sourcedirs += . \
- ../render \
- ../core \
- ../logic \
- ../plugins \
- ../quick3d/quick3d \
- ../input \
- ../extras \
- ../animation \
- ../quick3d/quick3dscene2d
+headerdirs += src
+sourcedirs += src
exampledirs += ../../examples/qt3d \
snippets
-examples.fileextensions += "*.fraq *.geom *.vert"
-examples.imageextensions += "*.png"
-
-excludedirs += \
- ../plugins/renderplugins
-
-macro.TODO = " "
-imagedirs += images \
- ../../examples/qt3d/shadow-map-qml/doc/images \
- ../../examples/qt3d/basicshapes-cpp/doc/images \
- ../../examples/qt3d/planets-qml/doc/images \
- ../../examples/qt3d/wireframe/doc/images \
- ../../examples/qt3d/audio-visualizer-qml/doc/images \
- ../../examples/qt3d/simplecustommaterial/doc/images \
- ../../examples/qt3d/scene2d/doc/images \
- ../../examples/qt3d/advancedcustommaterial/doc/images
-
-Cpp.ignoretokens += QT3DINPUTSHARED_EXPORT \
- QT3DCORESHARED_EXPORT \
- QT3DLOGIC_PRIVATE_EXPORT \
- QT3DLOGICSHARED_EXPORT \
- QT3DRENDERSHARED_EXPORT \
- QT3DRENDERSHARED_PRIVATE_EXPORT \
- QT3DQUICKSHARED_PRIVATE_EXPORT \
- QT3DEXTRASSHARED_EXPORT \
- QT3DANIMATIONSHARED_EXPORT \
- QT3DQUICKSCENE2DSHARED_EXPORT
-
-Cpp.ignoredirectives += Q_DECLARE_LOGGING_CATEGORY
-
-manifestmeta.highlighted.names = \
- "Qt3D/Qt 3D: Advanced custom material QML Example" \
- "Qt3D/Qt 3D: Audio Visualizer Example" \
- "Qt3D/Qt 3D: Planets QML Example"
-
-manifestmeta.thumbnail.names += "Qt3D/Qt 3D: Deferred Renderer C++ Example"
-
-navigation.landingpage = "Qt 3D"
-navigation.cppclassespage = "Qt 3D C++ Classes"
-navigation.qmltypespage = "Qt 3D QML Types"
+imagedirs += images
diff --git a/src/doc/src/levelofdetailloader.qdoc b/src/doc/src/levelofdetailloader.qdoc
deleted file mode 100644
index 6294e4735..000000000
--- a/src/doc/src/levelofdetailloader.qdoc
+++ /dev/null
@@ -1,57 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \qmltype LevelOfDetailLoader
- \inqmlmodule Qt3D.Render
- \inherits Entity
- \since 5.9
- \brief An entity loader that changes depending on distance to camera or screen size
-
- A LevelOfDetailLoader will load the entity matching the \l LevelOfDetail::currentIndex.
- The source is selected from the \l sources property.
-
- \sa LevelOfDetail
-*/
-
-/*!
- \qmlproperty list<string> LevelOfDetailLoader::sources
-
- The list of sources (array of strings) to load from.
-*/
diff --git a/src/doc/src/qcircularbuffer.qdoc b/src/doc/src/qcircularbuffer.qdoc
deleted file mode 100644
index e313a7375..000000000
--- a/src/doc/src/qcircularbuffer.qdoc
+++ /dev/null
@@ -1,1590 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/* !\internal
- \class Qt3DCore::QCircularBuffer
- \inmodule Qt3DCore
- \brief A template class providing a dynamic circular array.
-
- \ingroup tools
- \ingroup shared
-
- \reentrant
-
- QCircularBuffer\<T\> is one of Qt's generic \l{container classes}. It
- stores its items in adjacent memory locations and provides fast
- index-based access.
-
- QCircularBuffer\<T\> provides similar functionality as QVector\<T\> and QList\<T\>,
- but behaves differently when adding items to a full QCircularBuffer. Whereas
- QVector\<T\> and QList\<T\> will both grow to accommodate the new items,
- QCircularBuffer\<T\> will overwrite the oldest items. This provides circular
- behavior to the container, and also means that it can maintain a flat memory
- profile.
-
- QCircularBuffer\<T\> also offers performance gains over the other container classes when
- doing lots of appending or prepending to the buffer, such as in data logging
- applications. This is because appending (or prepending) an item does not require any
- extra memory to be allocated, unlike, for example, QVector\<T\> or QList\<T\>.
- Appending and prepending items to a QCircularBuffer\<T\> is an O(1) operation.
-
- As with QVector\<T\>, items in QCircularBuffer\<T\> occupy adjacent positions in memory.
- However, the items may not be located in order in a single array. At times, the internal
- indices used to store the positions of the first and last items may wrap around as the
- QCircularBuffer\<T\> is modified. If the index of the last item is greater than the
- index of the first item, then the buffer is said to be non-linearized.
-
- Here's an example of a QCircularBuffer that stores integers and a QCircularBuffer
- that stores QString values:
-
- \snippet code/src_core_qcircularbuffer.cpp 0
-
- The above examples create QCircularBuffer objects with a capacity of 0. The capacity
- is the number of items that can be stored in a QCircularBuffer. The size of a
- QCircularBuffer object is the number of items that actually are stored in it. Here's
- an example of creating a QCircularBuffer with a capacity for 200 elements and a size of 0:
-
- \snippet code/src_core_qcircularbuffer.cpp 1
-
- By default the QCircularBuffer is empty. If you want to create a circular buffer with
- unused capacity, pass a size argument to the constructor.
-
- \snippet code/src_core_qcircularbuffer.cpp 2
-
- If you wish to fill a subset of the QCircularBuffer with a default value, then you
- should also pass a size argument to the constructor. The following example creates
- a QCircularBuffer with a capacity for 200 QString items, and initializes the first 50
- of them to the value "Qt":
-
- \snippet code/src_core_qcircularbuffer.cpp 3
-
- You can also call fill() at any time to fill the QCircularBuffer with a value.
-
- QCircularBuffer uses 0-based indexes, just like C++ arrays. To access the
- item at a particular index position, you can use \l{operator[]()}{operator[]}. On
- non-const buffers, \l{operator[]()}{operator[]} returns a reference to the item
- that can be used on the left side of an assignment:
-
- \snippet code/src_core_qcircularbuffer.cpp 4
-
- For read-only access, an alternative syntax is to use at():
-
- \snippet code/src_core_qcircularbuffer.cpp 5
-
- at() can be faster than \l{operator[]()}{operator[]}, because it never causes
- a \l{deep copy} to occur.
-
- Another way to access the data stored in a QCircularBuffer is to call data(),
- or dataOne() and dataTwo() depending on if the buffer is linearized or not.
- See the discussion in isLinearised() for more information. The data() function
- returns an \l array_range object describing the array of items stored
- in the QCircularBuffer. You can use the pointer in the array_range to
- directly access and modify the elements stored in the circular buffer. The pointer is also
- useful if you need to pass a QCircularBuffer to a function that accepts a plain
- C++ array.
-
- If the circular buffer is non-linearized, the data() function will
- linearize it before returning. This can be an expensive operation for large buffers.
- To avoid this cost, QCircularBuffer also provides alternative methods called
- dataOne() and dataTwo() that return pointers to the two contiguous arrays used
- to represent the buffer. dataOne() returns a pointer to the earlier (or oldest)
- items, and dataTwo() returns a pointer to the later (or newer) items. The dataOne()
- and dataTwo() functions never cause the circular buffer to be linearized.
-
- If you wish to pass a C++ array to a function and that function is expensive to call,
- then you may wish to use the data() method so that you only need to call your
- expensive function once. If your function is cheap and you have a large circular
- buffer (so that linearizing it is expensive), then you may wish to use dataOne() and
- dataTwo() and call your function twice.
-
- Here is a simple example that shows the semantics of how QCircularBuffer operates:
-
- \snippet code/src_core_qcircularbuffer.cpp 6
-
- Notice how appending items to a full buffer overwrites the earliest items.
-
- If you want to find all occurrences of a particular value in a
- circular buffer, use indexOf() or lastIndexOf(). The former searches
- forward starting from a given index position, the latter searches
- backward. Both return the index of the matching item if they found
- one; otherwise, they return -1. For example:
-
- \snippet code/src_core_qcircularbuffer.cpp 7
-
- If you simply want to check whether a circular buffer contains a
- particular value, use contains(). If you want to find out how
- many times a particular value occurs in the circular buffer, use count().
-
- QCircularBuffer provides these basic functions to add, move, and remove
- items: insert(), replace(), remove(), prepend(), append(). The insert() and
- remove() functions can be slow (\l{linear time}) for large circular buffers,
- because they require moving many items in the circular buffer by one or more positions
- in memory. The implementation does however take care to minimize the number of
- items that need to be moved. In the extreme worst case for insert() and remove(),
- half of the items will be moved in memory. QCircularBuffer also takes care
- to move items around using the best method available for the type being stored.
- If your type is movable, then it is best to tell Qt about this by using the
- Q_DECLARE_TYPEINFO() macro. In such cases memory moves are performed using
- memmove() rather than calling the copy constructor for each item. If you want
- a container class that always provides fast insertion/removal in the middle,
- use QList or QLinkedList instead.
-
- Unlike plain C++ arrays, QCircularBuffers can be resized at any time by
- calling resize() or setCapacity(). The resize() function can only allocate
- items up to the number specified by capacity(). If you wish to alter the
- capacity of the CircularBuffer, then use setCapacity(). This can be slow as
- new memory needs to be allocated. It is most common to specify the capacity
- of the circular buffer in the constructor or immediately after construction,
- and then simply keep appending to the buffer. If you wish to reclaim any
- unused memory from the circular buffer, then call squeeze(). This is
- equivalent to calling \l {setCapacity()}{setCapacity}( size() ).
-
- Note that using non-const operators and functions can cause
- QCircularBuffer to do a deep copy of the data. This is due to
- \l{implicit sharing}.
-
- QCircularBuffer's value type must be an \l{assignable data type}. This
- covers most data types that are commonly used, but the compiler
- won't let you, for example, store a QWidget as a value; instead,
- store a QWidget *. Some functions have additional requirements;
- for example, indexOf() and lastIndexOf() expect the value type to
- support \c operator==(). These requirements are documented on a
- per-function basis.
-
- QCircularBuffer provides \l{STL-Style Iterators} (\l {const_iterator}
- and \l {iterator}). In practice, these are rarely used,
- because you can use indexes into the buffer.
-
- QCircularBuffer does \e not support inserting, prepending, appending, or
- replacing with references to its own values. Doing so will cause your
- application to abort with an error message.
-
- \sa iterator, const_iterator, QVector, QList, QLinkedList
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer()
-
- Constructs an empty circular buffer with zero capacity.
-
- \sa resize(), setCapacity()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity)
-
- Constructs an empty circular buffer with an initial capacity of \a capacity
- elements.
-
- \sa resize(), setCapacity()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity, const T &value)
-
- Constructs a circular buffer with an initial capacity and size of
- \a capacity elements.
-
- The elements are initialized to \a value.
-
- \sa resize(), setCapacity(), fill()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(int capacity, int size, const T &value)
-
- Constructs a circular buffer with an initial capacity of \a capacity
- elements and initial size of \a size elements.
-
- The first \a size elements are initialized to \a value.
-
- \sa resize(), setCapacity(), fill()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::QCircularBuffer(const QCircularBuffer<T> &other)
-
- Constructs a copy of \a other.
-
- This operation takes \l{constant time}, because QCircularBuffer is
- \l{implicitly shared}. This makes returning a QCircularBuffer from a
- function very fast. If a shared instance is modified, it will be
- copied (copy-on-write), and that takes \l{linear time}.
-
- \sa operator=()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::~QCircularBuffer()
-
- Destroys the circular buffer.
-*/
-
-/* \fn QCircularBuffer &Qt3DCore::QCircularBuffer::operator=(const QCircularBuffer<T> &other)
-
- Assigns \a other to this circular buffer and returns a reference to this
- circular buffer.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::begin()
-
- Returns an \l{STL-Style iterators}{STL-style iterator} pointing to the first item in
- the circular buffer.
-
- \sa constBegin(), end()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::begin() const
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::constBegin() const
-
- Returns a const \l{STL-Style Iterators}{STL-style iterator} pointing to the first item in
- the circular buffer.
-
- \sa begin(), constEnd()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::end()
-
- Returns an \l {STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
- after the last item in the circular buffer.
-
- \sa begin(), constEnd()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::end() const
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::constEnd() const
-
- Returns a const \l{STL-Style Iterators} {STL-style iterator} pointing to the imaginary item
- after the last item in the circular buffer.
-
- \sa constBegin(), end()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::erase(const_iterator pos)
-
- Removes the item pointed to by the iterator \a pos from the
- circular buffer, and returns an iterator to the next item in the circular
- buffer (which may be end()).
-
- \sa insert(), remove()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::erase(const_iterator begin, const_iterator end)
-
- \overload
-
- Removes all the items from \a begin up to (but not including) \a
- end. Returns an iterator to the same item that \a end referred to
- before the call.
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::push_back(const T &value)
-
- This function is provided for STL compatibility. It is equivalent
- to append(\a value).
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::push_front(const T &value)
-
- This function is provided for STL compatibility. It is equivalent
- to prepend(\a value).
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::pop_back()
-
- This function is provided for STL compatibility. It is equivalent
- to erase(end() - 1).
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::pop_front()
-
- This function is provided for STL compatibility. It is equivalent
- to erase(begin()).
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::empty() const
-
- This function is provided for STL compatibility. It is equivalent
- to isEmpty(), returning true if the circular buffer is empty; otherwise
- returns false.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::reference Qt3DCore::QCircularBuffer::front()
-
- This function is provided for STL compatibility. It is equivalent
- to first().
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_reference Qt3DCore::QCircularBuffer::front() const
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::reference Qt3DCore::QCircularBuffer::back()
-
- This function is provided for STL compatibility. It is equivalent
- to last().
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_reference Qt3DCore::QCircularBuffer::back() const
-
- \overload
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::refCount() const
-
- Returns the number of shallow copies that exist of this circular buffer.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::append(const T &value)
-
- Inserts \a value at the end of the circular buffer. If the circular buffer
- is full, then the oldest element is overwritten.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 8
-
- This operation is very fast, because QCircularBuffer never allocates
- memory in this function.
-
- \sa operator<<(), operator+=(), prepend(), insert()
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::at(int i) const
-
- Returns the item at index position \a i in the circular buffer.
-
- \a i must be a valid index position in the circular buffer
- (i.e., 0 <= \a i < size()).
-
- \sa value(), operator[]()
-*/
-
-/* \fn T &Qt3DCore::QCircularBuffer::operator[](int i)
-
- Returns the item at index position \a i as a modifiable reference.
-
- \a i must be a valid index position in the circular buffer (i.e., 0 <= \a i
- < size()).
-
- Note that using non-const operators can cause QCircularBuffer to do a deep
- copy.
-
- \sa at(), value()
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::operator[](int i) const
-
- \overload
-
- Same as at(\a i).
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::capacity() const
-
- Returns the maximum number of elements that can be stored in
- the circular buffer.
-
- \sa setCapacity(), size()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::clear()
-
- Removes all elements from the circular buffer so that the size is
- zero. The capacity is unchanged.
-
- \sa isEmpty()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::contains(const T &value) const
-
- Returns true if the circular buffer contains an occurrence of \a value;
- otherwise returns false.
-
- This function requires the value type to have an implementation of
- \c operator==().
-
- \sa indexOf(), count()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::count(const T &value) const
-
- Returns the number of occurrences of \a value in the circular buffer.
-
- This function requires the value type to have an implementation of
- \c operator==().
-
- \sa contains(), indexOf()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::count() const
-
- \overload
-
- Same as size().
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::data()
-
- Returns an \l array_range describing the internal array of data. If
- the circular buffer is non-linearized, then this function causes it to be
- linearized. If the cost of linearisation is too high for your use case, then
- you should consider using the dataOne() and dataTwo() functions instead.
-
- If the circular buffer is empty then the pointer and array size returned
- will both be 0.
-
- \sa constData(), dataOne(), dataTwo(), isLinearised()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::data() const
-
- \overload
-
- If the circular buffer is non-linearized then the pointer and array size
- returned will both be 0 since linearising the circular buffer would break
- constness.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constData() const
-
- Returns a \l const_array_range describing the internal array of
- data.
-
- If the circular buffer is non-linearized then the pointer and array size
- returned will both be 0 since linearising the circular buffer would break
- constness.
-
- If the circular buffer is empty then the pointer and array size returned
- will both be 0.
-
- \sa data(), constDataOne(), constDataTwo(), isLinearised()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::dataOne()
-
- Returns an \l array_range describing the first internal array of
- contiguous data. If the circular buffer is linearized, then this function is
- equivalent to calling data(). If the circular buffer is non-linearized then
- the returned array range will describe a subset of the data contained in the
- circular buffer. This subset will consist of the earliest (lowest index) items
- in the buffer. To obtain an \l array_range for the remainder of the data, use
- the dataTwo() function.
-
- If the circular buffer is empty, then the pointer and array size returned
- will both be 0.
-
- \sa constDataOne(), dataTwo(), data(), isLinearised()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::dataOne() const
-
- \overload
-
- Unlike data(), this function always returns a valid \l const_array_range
- (unless the circular buffer is empty).
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constDataOne() const
-
- Returns a \l const_array_range describing the first internal array of
- contiguous data. If the circular buffer is linearized, then this function is
- equivalent to calling constData(). If the circular buffer is non-linearized, then
- the returned array range will describe a subset of the data contained in the
- circular buffer. This subset will consist of the earliest (lowest index) items
- in the buffer. To obtain a \l const_array_range for the remainder of the data,
- use the constDataTwo() function.
-
- If the circular buffer is empty, then the pointer and array size returned
- will both be 0.
-
- \sa dataOne(), constDataTwo(), constData(), isLinearised()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::array_range Qt3DCore::QCircularBuffer::dataTwo()
-
- Returns an \l array_range describing the first internal array of
- contiguous data. If the circular buffer is linearized, then the pointer and array size
- returned will both be 0 since all the data will be contained in the array
- described by calling the dataOne() function.
-
- \sa dataOne(), constDataTwo(), data(), isLinearised()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::dataTwo() const
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_array_range Qt3DCore::QCircularBuffer::constDataTwo() const
-
- Returns a \l const_array_range describing the first internal array of
- contiguous data. If the circular buffer is linearized, then the pointer and array size
- returned will both be 0 since all the data will be contained in the array
- described by calling the dataOne() function.
-
- \sa constDataOne(), dataTwo(), constData(), isLinearised()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::endsWith(const T &value) const
-
- Returns \c true if this circular buffer is not empty and its last
- item is equal to \a value; otherwise returns \c false.
-
- \sa isEmpty(), last(), startsWith()
-*/
-
-/* \fn QCircularBuffer<T>& Qt3DCore::QCircularBuffer::fill(const T &value, int size = -1)
-
- Assigns \a value to all items in the circular buffer. If \a size is
- different from -1 (the default), the circular buffer is resized to size \a
- size beforehand (size must be less than or equal to the capacity).
-
- This function also linearizes the circular buffer.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 14
-
- \sa resize()
-*/
-
-/* \fn T &Qt3DCore::QCircularBuffer::first()
-
- Returns a reference to the first item in the circular buffer. This
- function assumes that the circular buffer isn't empty.
-
- \sa last(), isEmpty()
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::first() const
-
- \overload
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::freeSize() const
-
- Returns the number of items that can be added to the circular buffer
- without causing the earliest item to be overwritten. It is equivalent
- to (capacity() - size()).
-
- \sa sizeAvailable(), capacity(), isEmpty(), isFull(), size()
-*/
-
-/* \fn static QCircularBuffer<T> Qt3DCore::QCircularBuffer::fromList(const QList<T>& list)
-
- Returns a QCircularBuffer object with the data contained in \a list. The
- capacity and size of the circular buffer will be equal to the size of
- \a list.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 18
-
- \sa fromVector(), toList(), toVector()
-*/
-
-/* \fn static QCircularBuffer<T> Qt3DCore::QCircularBuffer::fromVector(const QVector<T>& vector)
-
- Returns a QCircularBuffer object with the data contained in \a vector. The
- capacity and size of the circular buffer will be equal to the size of
- \a vector.
-
- \sa fromList(), toVector(), toList()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::indexOf(const T &value, int from = 0) const
-
- Returns the index position of the first occurrence of \a value in
- the circular buffer, searching forward from index position \a from.
- Returns -1 if no item matched.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 15
-
- This function requires the value type to have an implementation of
- \c operator==().
-
- \sa lastIndexOf(), contains()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::insert(int i, const T &value)
-
- Inserts \a value at index position \a i in the circular buffer.
- If \a i is 0, the value is prepended to the circular buffer. If \a i
- is size(), the value is appended to the circular buffer. The capacity
- of the circular buffer is not changed.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 11
-
- Using this function is equivalent to calling insert(i, 1, value). See the
- discussion there for more information.
-
- Items at indexes \a i and higher are shifted along by one. If the circular
- buffer is full then the earliest item will be overwritten. Note that this
- has the non-obvious behavior that calling \c {insert(0, value)} on a circular
- buffer that is already full will effectively do nothing since the newly
- prepended item will immediately be overwritten by the highest item as it
- is shifted along one position.
-
- For large circular buffers, this operation can be slow (\l{linear time}),
- because it requires moving all the items at indexes \a i and
- above (or all items below index i depending upon where in the circular buffer
- the new item is inserted) by one position in memory. If you
- want a container class that provides a fast insert() function, use
- QLinkedList instead.
-
- If the capacity() is zero, then nothing will be inserted.
-
- \sa append(), prepend(), remove()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::insert(int i, int count, const T &value)
-
- \overload
-
- Inserts \a value at index position \a i in the circular buffer.
- If \a i is 0, the value is prepended to the circular buffer. If \a i
- is size(), the value is appended to the circular buffer. The capacity
- of the circular buffer is not changed.
-
- Items at indexes \a i and higher are shifted along by one. If the circular
- buffer has freeSize() < \a count, then the earliest items will be overwritten.
-
- The actual number of items that get inserted may not always be equal to
- \a count since this function preserves the capacity of the circular buffer,
- and since items at indexes i and higher are shifted along by one.
- The actual number of items inserted is min(\a count, \a i + freeSize()).
-
- For the same reasons, the number of items that get overwritten at the
- start of the circular buffer is min(\a i, max(0, \a count - freeSize())).
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 12
-
- For large circular buffers, this operation can be slow (\l{linear time}),
- because it requires moving all the items at indexes \a i and
- above (or all items below index i depending upon where in the circular buffer
- the new item is inserted) in memory. If you want a container class that
- provides a fast insert() function, use QLinkedList instead.
-
- If the capacity() is zero, then nothing will be inserted.
-
- \sa append(), prepend(), remove()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::insert(const_iterator before, int count, const T &value)
-
- \overload
-
- Inserts up to \a count items with value \a value in front of the item
- pointed to by the iterator \a before in the circular buffer. Returns an
- iterator pointing at the first of the inserted items.
-
- \sa append(), prepend(), remove()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::insert(const_iterator before, const T &value)
-
- \overload
-
- Inserts \a value in front of the item pointed to by the iterator \a before.
- Returns an iterator pointing at the inserted item.
-
- \sa append(), prepend(), remove()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::isEmpty() const
-
- Returns true if the circular buffer has size 0; otherwise returns false.
-
- \sa capacity(), resize(), setCapacity(), size()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::isFull() const
-
- Returns true if the circular buffer is full ie if size() == capacity(); otherwise returns false.
-
- \sa capacity(), resize(), setCapacity(), size()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::isLinearised() const
-
- Returns \c true if the circular buffer is linearized; otherwise returns
- \c false.
-
- A circular buffer is said to be linearized if the position of the first
- item in the internal array occurs before the position of the last item. A
- little more explanation is provided for clarification.
-
- Internally, QCircularBuffer stores the items in a plain C++ array.
- Additionally, the positions in the array of the first and last items of
- the circular buffer are also stored (along with the capacity and size).
-
- Imagine a circular buffer of capacity 6 created and populated with the
- following code:
-
- \snippet code/src_core_qcircularbuffer.cpp 19
-
- After executing the above code, the internal state of the circular buffer
- would look like this:
-
- \img circularbuffer-1.png
-
- As you can see, the internal array has been populated from the beginning.
- The first item is located as position 0 in the array and the last item
- is located at position 4 in the array. The circular buffer is linearized
- because the last item occurs later in the array than the first item.
-
- If we now append another item to the circular buffer with:
-
- \snippet code/src_core_qcircularbuffer.cpp 20
-
- the internal representation then becomes:
-
- \img circularbuffer-2.png
-
- The circular buffer is still linearized, but it is now full. Appending
- further items will cause the oldest item to be overwritten. For example,
-
- \snippet code/src_core_qcircularbuffer.cpp 21
-
- causes the internal representation to become:
-
- \img circularbuffer-3.png
-
- We see that the oldest item (1) has been overwritten by the newest item
- (7), and that the first and last indexes have been adjusted accordingly.
- The circular buffer is now said to be non-linearized because the position
- of the last item is before the position of the first item.
-
- The circular buffer can always be linearized by calling the linearise()
- function. This can be an expensive operation (\l{linear time}) for large
- circular buffers since new memory has to be allocated, the items copied across,
- and the original memory deallocated.
-
- If you need to directly access the items stored in a circular buffer,
- (perhaps for a plain C++ function call) then you can use the data()
- function. If the circular buffer is non-linearized, then the data()
- function will linearize it for you before returning an \l array_range
- describing the array.
-
- To prevent the cost of the linearisation process, you can instead
- call the dataOne() and dataTwo() functions to obtain the two arrays
- used to represent a non-linearized circular buffer. After running the
- above sample code, calling the dataOne() function would return an
- \l array_range object describing the values 2-6, and the dataTwo() function
- would return an \l array_range object describing the value 7. Sometimes,
- accessing the items via the two arrays described by dataOne() and dataTwo(),
- can be quicker than calling data() and having the circular buffer
- linearized. The dataOne() and dataTwo() functions do not trigger a
- linearization.
-
- \sa linearise(), data(), dataOne(), dataTwo()
-*/
-
-/* \fn T &Qt3DCore::QCircularBuffer::last()
-
- Returns a reference to the last item in the circular buffer. This
- function assumes that the circular buffer isn't empty.
-
- \sa first(), isEmpty()
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::last() const
-
- \overload
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::lastIndexOf(const T &value, int from = -1) const
-
- Returns the index position of the last occurrence of the value \a
- value in the circular buffer, searching backward from index position \a
- from. If \a from is -1 (the default), the search starts at the
- last item. Returns -1 if no item is matched.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 16
-
- This function requires the value type to have an implementation of
- \c operator==().
-
- \sa indexOf()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::linearise()
-
- Linearizes the internal representation of the circular buffer such that
- all items are stored in a single contiguous array.
-
- This function can be expensive for large circular buffers (\l{linear time}).
-
- \sa isLinearised()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::prepend(const T &value)
-
- Inserts \a value at the beginning of the circular buffer. If the circular buffer
- is full, then the highest index item is overwritten.
-
- Example:
- \snippet code/src_core_qcircularbuffer.cpp 10
-
- This operation is very fast, because QCircularBuffer never allocates
- memory in this function.
-
- \sa operator<<(), operator+=(), append(), insert()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::remove(int i)
-
- Removes the element at index position \a i.
-
- \sa insert(), replace(), fill()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::remove(int i, int count)
-
- \overload
-
- Removes \a count elements from the middle of the circular buffer,
- starting at index position \a i.
-
- \sa insert(), replace(), fill()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::replace(int i, const T &value)
-
- Replaces the item at index position \a i with \a value.
-
- \a i must be a valid index position in the circular buffer (i.e., 0 <= \a
- i < size()).
-
- \sa operator[](), remove()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::reserve(int capacity)
-
- Sets the capacity of the circular buffer to \a capacity. It is a synonym for
- setCapacity().
-
- \sa setCapacity()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::resize(int size)
-
- Changes the size of the circular buffer to \a size which must be > 0 and
- <= capacity(). If \a size is less than the old size, then the highest indexed
- items are removed. If \a size is greater than the old size, then new items
- with a \l{default-constructed value} are appended to the end of the circular
- buffer.
-
- \sa size(), insert(), remove(), capacity(), setCapacity()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::setCapacity(int capacity)
-
- Sets the capacity of the circular buffer to \a capacity.
-
- \sa reserve(), capacity()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::size() const
-
- Returns the number of items in the circular buffer.
-
- \sa sizeAvailable(), capacity(), resize()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::sizeAvailable() const
-
- Returns the number of items that can be added to the circular buffer
- without causing the earliest item to be overwritten. It is equivalent
- to (capacity() - size()).
-
- \sa capacity(), isEmpty(), isFull(), size(), freeSize()
-*/
-
-/* \fn void Qt3DCore::QCircularBuffer::squeeze()
-
- Releases any unused memory from the circular buffer. It is equivalent
- to calling setCapacity(size()).
-
- \sa setCapacity(), size(), resize(), sizeAvailable()
-*/
-
-/* \fn bool Qt3DCore::QCircularBuffer::startsWith(const T &value) const
-
- Returns \c true if the circular buffer is not empty and its first
- item is equal to \a value; otherwise returns \c false.
-
- \sa isEmpty(), first(), endsWith()
-*/
-
-/* \fn QList<T> Qt3DCore::QCircularBuffer::toList() const
-
- Returns a QList object with the data contained in this QCircularBuffer.
-
- Example:
-
- \snippet code/src_core_qcircularbuffer.cpp 17
-
- \sa fromList(), toVector()
-*/
-
-/* \fn QVector<T> Qt3DCore::QCircularBuffer::toVector() const
-
- Returns a QVector object with the data contained in this QCircularBuffer.
-
- \sa fromVector(), toList()
-*/
-
-/* \fn T Qt3DCore::QCircularBuffer::value(int i) const
-
- Returns the value at index position \a i in the circular buffer.
-
- If the index \a i is out of bounds, the function returns
- a \l{default-constructed value}. If you are certain that
- \a i is within bounds, you can use at() instead, which is slightly
- faster.
-
- \sa at(), operator[]()
-*/
-
-/* \fn T Qt3DCore::QCircularBuffer::value(int i, const T &defaultValue) const
-
- \overload
-
- If the index \a i is out of bounds, the function returns
- \a defaultValue.
-*/
-
-/* \fn bool Qt3DCore::operator==(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if the circular buffer \a lhs is equal to \a rhs; otherwise
- returns \c false.
-
- Two circular buffers are considered equal if they contain the same values
- in the same order and have the same capacity.
-
- This function requires the value type to have an implementation
- of \c operator==().
-
- \sa operator!=()
-*/
-
-/* \fn bool Qt3DCore::operator!=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if the circular buffer \a lhs is not equal to \a rhs; otherwise
- returns \c false.
-
- Two circular buffers are considered equal if they contain the same values
- in the same order and have the same capacity.
-
- This function requires the value type to have an implementation
- of \c operator==().
-
- \sa operator==()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const T &other)
-
- Appends the item \a other to this circular buffer and returns a
- reference to this circular buffer.
-
- \sa operator+(), operator<<(), append()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QCircularBuffer<T>& other)
-
- \overload
-
- Appends the items of the \a other circular buffer to this circular
- buffer and returns a reference to this circular buffer.
-
- \sa operator+(), operator<<(), append()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QVector<T>& other)
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator+=(const QList<T>& other)
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const T &other)
-
- Appends the item \a other to this circular buffer and returns a
- reference to this circular buffer.
-
- \sa operator+(), operator+=(), append()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QCircularBuffer<T>& other)
-
- \overload
-
- Appends the items of the \a other circular buffer to this circular
- buffer and returns a reference to this circular buffer.
-
- \sa operator+(), operator+=(), append()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QVector<T>& other)
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T>& Qt3DCore::QCircularBuffer::operator<<(const QList<T>& other)
-
- \overload
-*/
-
-/* \fn Qt3DCore::QCircularBuffer<T> Qt3DCore::operator+(const QCircularBuffer<T>& lhs, const QCircularBuffer<T>& rhs)
- \relates Qt3DCore::QCircularBuffer
-
- Returns a circular buffer object with capacity of lhs.size() + rhs.size() containing
- the items from \a lhs followed by the items from \a rhs.
-
- \sa {QCircularBuffer::}{operator+=()}
-*/
-
-/* \fn void Qt3DCore::swap(QCircularBuffer<T> &lhs, QCircularBuffer<T> &rhs)
-
- Swaps the contents of the circular buffer \a lhs with the contents of \a rhs.
-*/
-
-/* \fn bool Qt3DCore::operator<(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if \a lhs is lexographically less than \a rhs. This is equivalent to calling
- \c{return std::lexicographical_compare(lhs.begin(), lhs.end(), rhs.begin(), rhs.end())}.
-*/
-
-/* \fn bool Qt3DCore::operator>(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if \a rhs is lexographically less than \a lhs.
-*/
-
-/* \fn bool Qt3DCore::operator>=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if \a lhs is lexographically less than or equal to \a rhs.
-*/
-
-/* \fn bool Qt3DCore::operator<=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs)
-
- Returns \c true if \a lhs is lexographically less than or equal to \a rhs.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::Iterator
-
- Qt-style synonym for \l iterator.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::ConstIterator
-
- Qt-style synonym for \l const_iterator.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_pointer
-
- Typedef for const T *. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_reference
-
- Typedef for T &. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::difference_type
-
- Typedef for ptrdiff_t. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::pointer
-
- Typedef for T *. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::reference
-
- Typedef for T &. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::size_type
-
- Typedef for int. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::value_type
-
- Typedef for T. Provided for STL compatibility.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::array_range
-
- Typedef for QPair<T*,int>. The first element is a pointer to the
- first element of an array of T. The second element is the number
- of elements in the array.
-
- \sa data(), dataOne(), dataTwo()
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_array_range
-
- Typedef for QPair<const T*,int>. The first element is a pointer to the
- first element of an array of const T. The second element is the number
- of elements in the array.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::ArrayRange
-
- Qt-style synonym for \l array_range.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::ConstArrayRange
-
- Qt-style synonym for \l const_array_range.
-*/
-
-
-/* \class Qt3DCore::QCircularBuffer::iterator
- \inmodule Qt3DCore
- \brief The Qt3DCore::QCircularBuffer::iterator class provides an STL-style non-const iterator for QCircularBuffer.
-
- QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
- Iterators}.
-
- \sa begin(), end(), const_iterator
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::iterator::iterator_category
-
- A synonym for \e {std::random_access_iterator_tag} indicating
- this iterator is a random access iterator.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::iterator::difference_type
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::iterator::value_type
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::iterator::pointer
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::iterator::reference
-
- \internal
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator::iterator()
-
- Constructs an uninitialized iterator.
-
- Functions like operator*() and operator++() should not be called
- on an uninitialized iterator. Use operator=() to assign a value
- to it before using it.
-
- \sa begin(), end()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator::iterator(QCircularBuffer<T> *buffer, int index)
-
- \internal
-*/
-
-/* \fn T &Qt3DCore::QCircularBuffer::iterator::operator*() const
-
- Returns a modifiable reference to the current item.
-
- You can change the value of an item by using operator*() on the
- left side of an assignment.
-
- \sa operator->()
-*/
-
-/* \fn T *Qt3DCore::QCircularBuffer::iterator::operator->() const
-
- Returns a pointer to the current item.
-
- \sa operator*()
-*/
-
-/* \fn T &Qt3DCore::QCircularBuffer::iterator::operator[](int j) const
-
- Returns a modifiable reference to the item at position *this +
- \a{j}.
-
- This function is provided to make QCircularBuffer iterators behave like C++
- pointers.
-
- \sa operator+()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator==(const iterator &other) const
-
- Returns \c true if \a other points to the same item as this
- iterator; otherwise returns \c false.
-
- \sa operator!=()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator!=(const iterator &other) const
-
- Returns \c true if \a other points to a different item than this
- iterator; otherwise returns \c false.
-
- \sa operator==()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator<(const iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs before
- the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator<=(const iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs before
- or at the same position as the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator>(const iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs after
- the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::iterator::operator>=(const iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs after
- or at the same position as the item pointed to by the \a other iterator.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator++()
-
- The prefix ++ operator (\c{++it}) advances the iterator to the
- next item in the circular buffer and returns an iterator to the new current
- item.
-
- Calling this function on end() leads to undefined results.
-
- \sa operator--()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator++(int)
-
- \overload
-
- The postfix ++ operator (\c{it++}) advances the iterator to the
- next item in the circular buffer and returns an iterator to the previously
- current item.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator--()
-
- The prefix -- operator (\c{--it}) makes the preceding item
- the current item, and returns an iterator to the new current item.
-
- Calling this function on begin() leads to undefined results.
-
- \sa operator++()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator--(int)
-
- \overload
-
- The postfix -- operator (\c{it--}) makes the preceding item
- the current item, and returns an iterator to the previously current item.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator+=(int j)
-
- Advances the iterator by \a j items. (If \a j is negative, the
- iterator goes backward.)
-
- \sa operator-=(), operator+()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator &Qt3DCore::QCircularBuffer::iterator::operator-=(int j)
-
- Makes the iterator go back by \a j items. (If \a j is negative,
- the iterator goes forward.)
-
- \sa operator+=(), operator-()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator+(int j) const
-
- Returns an iterator to the item at \a j positions forward from
- this iterator. (If \a j is negative, the iterator goes backward.)
-
- \sa operator-(), operator+=()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::iterator Qt3DCore::QCircularBuffer::iterator::operator-(int j) const
-
- Returns an iterator to the item at \a j positions backward from
- this iterator. (If \a j is negative, the iterator goes forward.)
-
- \sa operator+(), operator-=()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::iterator::operator-(iterator other) const
-
- Returns the number of items between the item pointed to by \a
- other and the item pointed to by this iterator.
-*/
-
-
-/* \class Qt3DCore::QCircularBuffer::const_iterator
- \inmodule Qt3DCore
- \brief The Qt3DCore::QCircularBuffer::const_iterator class provides an STL-style const iterator for QCircularBuffer.
-
- QCircularBuffer provides both \l{STL-Style Iterators} and \l{Java-Style
- Iterators}.
-
- \sa constBegin(), constEnd(), iterator
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_iterator::iterator_category
-
- A synonym for \e {std::random_access_iterator_tag} indicating
- this iterator is a random access iterator.
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_iterator::difference_type
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_iterator::value_type
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_iterator::pointer
-
- \internal
-*/
-
-/* \typedef Qt3DCore::QCircularBuffer::const_iterator::reference
-
- \internal
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator::const_iterator()
-
- Constructs an uninitialized const iterator.
-
- Functions like operator*() and operator++() should not be called
- on an uninitialized iterator. Use operator=() to assign a value
- to it before using it.
-
- \sa begin(), end()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator::const_iterator(const iterator &other)
-
- \internal
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::const_iterator::operator*() const
-
- Returns a const reference to the current item.
-
- \sa operator->()
-*/
-
-/* \fn const T *Qt3DCore::QCircularBuffer::const_iterator::operator->() const
-
- Returns a pointer to the current item.
-
- \sa operator*()
-*/
-
-/* \fn const T &Qt3DCore::QCircularBuffer::const_iterator::operator[](int j) const
-
- Returns a const reference to the item at position *this +
- \a{j}.
-
- This function is provided to make QCircularBuffer iterators behave like C++
- pointers.
-
- \sa operator+()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator==(const const_iterator &other) const
-
- Returns \c true if \a other points to the same item as this
- iterator; otherwise returns \c false.
-
- \sa operator!=()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator!=(const const_iterator &other) const
-
- Returns \c true if \a other points to a different item than this
- iterator; otherwise returns \c false.
-
- \sa operator==()
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator<(const const_iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs before
- the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator<=(const const_iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs before,
- or at the same position as the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator>(const const_iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs after
- the item pointed to by the \a other iterator.
-*/
-
-/*
- \fn bool Qt3DCore::QCircularBuffer::const_iterator::operator>=(const const_iterator& other) const
-
- Returns \c true if the item pointed to by this iterator occurs after,
- or at the same position as the item pointed to by the \a other iterator.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator++()
-
- The prefix ++ operator (\c{++it}) advances the iterator to the
- next item in the circular buffer and returns an iterator to the new current
- item.
-
- Calling this function on constEnd() leads to undefined results.
-
- \sa operator--()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator++(int)
-
- \overload
-
- The postfix ++ operator (\c{it++}) advances the iterator to the
- next item in the circular buffer and returns an iterator to the previously
- current item.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator--()
-
- The prefix -- operator (\c{--it}) makes the preceding item the
- current and returns an iterator to the new current item.
-
- Calling this function on constBegin() leads to undefined results.
-
- \sa operator++()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator--(int)
-
- \overload
-
- The postfix -- operator (\c{it--}) makes the preceding item the
- current and returns an iterator to the previously current item.
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator+=(int j)
-
- Advances the iterator by \a j items. (If \a j is negative, the
- iterator goes backward.)
-
- \sa operator-=(), operator+()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator &Qt3DCore::QCircularBuffer::const_iterator::operator-=(int j)
-
- Makes the iterator go back by \a j items. (If \a j is negative,
- the iterator goes forward.)
-
- \sa operator+=(), operator-()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator+(int j) const
-
- Returns an iterator to the item at \a j positions forward from
- this iterator. (If \a j is negative, the iterator goes backward.)
-
- \sa operator-(), operator+=()
-*/
-
-/* \fn Qt3DCore::QCircularBuffer::const_iterator Qt3DCore::QCircularBuffer::const_iterator::operator-(int j) const
-
- Returns an iterator to the item at \a j positions backward from
- this iterator. (If \a j is negative, the iterator goes forward.)
-
- \sa operator+(), operator-=()
-*/
-
-/* \fn int Qt3DCore::QCircularBuffer::const_iterator::operator-(const_iterator other) const
-
- Returns the number of items between the item pointed to by \a
- other and the item pointed to by this iterator.
-*/
diff --git a/src/doc/src/qmlextracontrollers.qdoc b/src/doc/src/qmlextracontrollers.qdoc
deleted file mode 100644
index 737d0f823..000000000
--- a/src/doc/src/qmlextracontrollers.qdoc
+++ /dev/null
@@ -1,170 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \qmltype FirstPersonCameraController
- \inqmlmodule Qt3D.Extras
- \brief The FirstPersonCameraController allows controlling the scene camera
- from the first person perspective.
- \since 5.7
- \inherits Qt3D.Core::Entity
-
- The FirstPersonCameraController allows controlling the scene camera from the first person
- perspective.
-
- The controls are:
- \table
- \header
- \li Input
- \li Action
- \row
- \li Left mouse button
- \li While the left mouse button is pressed, mouse movement along x-axis pans the camera and
- movement along y-axis tilts it.
- \row
- \li Shift key
- \li Turns the fine motion control active while pressed. Makes mouse pan and tilt less
- sensitive.
- \row
- \li Arrow keys
- \li Move the camera horizontally relative to camera viewport.
- \row
- \li Page up and page down keys
- \li Move the camera vertically relative to camera viewport.
- \endtable
-*/
-/*!
- \qmlproperty Camera FirstPersonCameraController::camera
-
- Holds the currently controlled camera.
-*/
-/*!
- \qmlproperty real FirstPersonCameraController::linearSpeed
-
- Holds the current linear speed of the camera controller. Linear speed determines the
- movement speed of the camera.
-*/
-/*!
- \qmlproperty real FirstPersonCameraController::lookSpeed
-
- Holds the current look speed of the camera controller. The look speed determines the turn rate
- of the camera pan and tilt.
-*/
-/*!
- \qmlproperty real FirstPersonCameraController::acceleration
-
- Holds the current acceleration.
- Specifies the rate at which the camera linear speed increases when a key is held.
- If the acceleration is negative, the linear speed stays constant.
- Defaults to -1.0.
-*/
-/*!
- \qmlproperty real FirstPersonCameraController::deceleration
-
- Specifies the rate at which the camera linear speed decreases when a key is released.
- If the deceleration is negative, the linear speed stays constant.
- Defaults to -1.0.
-*/
-
-/*!
- \qmltype OrbitCameraController
- \inqmlmodule Qt3D.Extras
- \brief The OrbitCameraController class allows controlling the scene camera along orbital path.
- \since 5.7
- \inherits Qt3D.Core::Entity
-
- The OrbitCameraController class allows controlling the scene camera along orbital path.
-
- The controls are:
- \table
- \header
- \li Input
- \li Action
- \row
- \li Left mouse button
- \li While the left mouse button is pressed, mouse movement along x-axis moves the camera
- left and right and movement along y-axis moves it up and down.
- \row
- \li Right mouse button
- \li While the right mouse button is pressed, mouse movement along x-axis pans the camera
- around the camera view center and movement along y-axis tilts it around the camera
- view center.
- \row
- \li Both left and right mouse button
- \li While both the left and the right mouse button are pressed, mouse movement along y-axis
- zooms the camera in and out without changing the view center.
- \row
- \li Arrow keys
- \li Move the camera vertically and horizontally relative to camera viewport.
- \row
- \li Page up and page down keys
- \li Move the camera forwards and backwards.
- \row
- \li Shift key
- \li Changes the behavior of the up and down arrow keys to zoom the camera in and out
- without changing the view center. The other movement keys are disabled.
- \row
- \li Alt key
- \li Changes the behovior of the arrow keys to pan and tilt the camera around the view
- center. Disables the page up and page down keys.
- \endtable
-*/
-/*!
- \qmlproperty Camera OrbitCameraController::camera
-
- Holds the currently controlled camera.
-*/
-/*!
- \qmlproperty real OrbitCameraController::linearSpeed
-
- Holds the current linear speed of the camera controller. Linear speed determines the
- movement speed of the camera.
-*/
-/*!
- \qmlproperty real OrbitCameraController::lookSpeed
-
- Holds the current look speed of the camera controller. The look speed determines the turn rate
- of the camera pan and tilt.
-*/
-/*!
- \qmlproperty real OrbitCameraController::zoomLimit
-
- Holds the current zoom-in limit. The zoom-in limit determines how close to the view center
- the camera can be zoomed.
-*/
diff --git a/src/doc/src/qmlextramaterials.qdoc b/src/doc/src/qmlextramaterials.qdoc
deleted file mode 100644
index 48f1a2326..000000000
--- a/src/doc/src/qmlextramaterials.qdoc
+++ /dev/null
@@ -1,568 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \qmltype DiffuseMapMaterial
- \inqmlmodule Qt3D.Extras
- \brief The DiffuseMapMaterial provides a default implementation of the phong lighting effect
- where the diffuse light component is read from a texture map.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The specular lighting effect is based on the combination of 3 lighting components ambient,
- diffuse and specular. The relative strengths of these components are controlled by means of
- their reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color DiffuseMapMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty color DiffuseMapMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty real DiffuseMapMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real DiffuseMapMaterial::textureScale
-
- Holds the current texture scale. It is applied as a multiplier to texture
- coordinates at render time. Defaults to 1.0.
-*/
-/*!
- \qmlproperty TextureImage DiffuseMapMaterial::diffuse
-
- Holds the current texture used as the diffuse map.
-
- By default, the diffuse texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-
-/*!
- \qmltype DiffuseSpecularMapMaterial
- \inqmlmodule Qt3D.Extras
- \brief The DiffuseSpecularMapMaterial provides a default implementation of the phong lighting
- effect where the diffuse and specular light components are read from texture maps.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The specular lighting effect is based on the combination of 3 lighting components ambient,
- diffuse and specular. The relative strengths of these components are controlled by means of
- their reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color DiffuseSpecularMapMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty TextureImage DiffuseSpecularMapMaterial::diffuse
-
- Holds the current diffuse map texture.
-
- By default, the diffuse texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty TextureImage DiffuseSpecularMapMaterial::specular
-
- Holds the current specular map texture.
-
- By default, the specular texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty real DiffuseSpecularMapMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real DiffuseSpecularMapMaterial::textureScale
-
- Holds the current texture scale. It is applied as a multiplier to texture
- coordinates at render time. Defaults to 1.0.
-*/
-
-/*!
- \qmltype GoochMaterial
- \inqmlmodule Qt3D.Extras
- \brief The GoochMaterial provides a material that implements the Gooch
- shading model, popular in CAD and CAM applications.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The Gooch lighting model uses both color and brightness to help show the
- curvature of 3D surfaces. This is often better than models such as Phong
- that rely purely upon changes in brightness. In situations such as in CAD
- and CAM applications where photorealism is not a goal, the Gooch shading
- model in conjunction with some kind of silhouette edge inking is a popular
- solution.
-
- The Gooch lighting model is explained fully in the \l{original Gooch
- paper}. The Gooch model mixes a diffuse object color with a user-provided
- cool color and warm color to produce the end points of a color ramp that is
- used to shade the object based upon the cosine of the angle between the
- vector from the fragment to the light source and the fragment's normal
- vector. Optionally, a specular highlight can be added on top. The relative
- contributions to the cool and warm colors by the diffuse color are
- controlled by the alpha and beta properties respecitvely.
-
- This material uses an effect with a single render pass approach and
- performs per fragment lighting. Techniques are provided for OpenGL 2,
- OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color GoochMaterial::diffuse
-
- Holds the current diffuse color.
-*/
-/*!
- \qmlproperty color GoochMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty color GoochMaterial::coolColor
-
- Holds the current coolColor color.
-*/
-/*!
- \qmlproperty color GoochMaterial::warmColor
-
- Holds the current warmColor color.
-*/
-/*!
- \qmlproperty real GoochMaterial::alpha
-
- Holds the current alpha value. The start point of the color ramp
- used by the Gooch shader is calculated as {c = cool + alpha * diffuse}.
-*/
-/*!
- \qmlproperty real GoochMaterial::beta
-
- Holds the current beta value. The start point of the color ramp
- used by the Gooch shader is calculated as {c = warm + beta * diffuse}.
-*/
-/*!
- \qmlproperty real GoochMaterial::shininess
-
- Holds the current shininess value. Higher values of shininess result in
- a smaller and brighter highlight.
-*/
-
-/*!
- \qmltype NormalDiffuseMapAlphaMaterial
- \inqmlmodule Qt3D.Extras
- \brief The NormalDiffuseMapAlphaMaterial provides a specialization of NormalDiffuseMapMaterial
- with alpha coverage and a depth test performed in the rendering pass.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The specular lighting effect is based on the combination of 3 lighting components ambient,
- diffuse and specular. The relative strengths of these components are controlled by means of
- their reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color NormalDiffuseMapAlphaMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseMapAlphaMaterial::diffuse
-
- Holds the current diffuse map texture.
-
- By default, the diffuse texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty color NormalDiffuseMapAlphaMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseMapAlphaMaterial::normal
-
- Holds the current normal map texture.
-
- By default, the normal texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty real NormalDiffuseMapAlphaMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real NormalDiffuseMapAlphaMaterial::textureScale
-
- Holds the current texture scale. It is applied as a multiplier to texture
- coordinates at render time. Defaults to 1.0.
-*/
-
-/*!
- \qmltype NormalDiffuseMapMaterial
- \inqmlmodule Qt3D.Extras
- \brief The NormalDiffuseMapMaterial provides a default implementation of the phong lighting
- and bump effect where the diffuse light component is read from a texture map and the normals of
- the mesh being rendered from a normal texture map.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The specular lighting effect is based on the combination of 3 lighting components ambient,
- diffuse and specular. The relative strengths of these components are controlled by means of
- their reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color NormalDiffuseMapMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseMapMaterial::diffuse
-
- Holds the current diffuse map texture.
-
- By default, the diffuse texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty color NormalDiffuseMapMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseMapMaterial::normal
-
- Holds the current normal map texture.
-
- By default, the normal texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty real NormalDiffuseMapMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real NormalDiffuseMapMaterial::textureScale
-
- Holds the current texture scale. It is applied as a multiplier to texture
- coordinates at render time. Defaults to 1.0.
-*/
-
-/*!
- \qmltype NormalDiffuseSpecularMapMaterial
- \inqmlmodule Qt3D.Extras
- \brief The NormalDiffuseSpecularMapMaterial provides a default implementation of the phong
- lighting and bump effect where the diffuse and specular light components are read from texture
- maps and the normals of the mesh being rendered from a normal texture map.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The specular lighting effect is based on the combination of 3 lighting components ambient,
- diffuse and specular. The relative strengths of these components are controlled by means of
- their reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color NormalDiffuseSpecularMapMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::diffuse
-
- Holds the current diffuse map texture.
-
- By default, the diffuse texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::specular
-
- Holds the current specular map texture.
-
- By default, the specular texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Linear mipmap with mipmapping enabled
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty TextureImage NormalDiffuseSpecularMapMaterial::normal
-
- Holds the current normal map texture.
-
- By default, the normal texture has the following properties:
-
- \list
- \li Linear minification and magnification filters
- \li Repeat wrap mode
- \li Maximum anisotropy of 16.0
- \endlist
-*/
-/*!
- \qmlproperty real NormalDiffuseSpecularMapMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real NormalDiffuseSpecularMapMaterial::textureScale
-
- Holds the current texture scale. It is applied as a multiplier to texture
- coordinates at render time. Defaults to 1.0.
-*/
-
-/*!
- \qmltype PerVertexColorMaterial
- \inqmlmodule Qt3D.Extras
- \brief The PerVertexColorMaterial class provides a default implementation for rendering the
- color properties set for each vertex.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- This lighting effect is based on the combination of 2 lighting components ambient and diffuse.
- Ambient is set by the vertex color.
- Diffuse takes in account the normal distribution of each vertex.
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rough surface reflections with the lights
- \endlist
-
- This material uses an effect with a single render pass approach and forms fragment lighting.
- Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-
-/*!
- \qmltype PhongAlphaMaterial
- \inqmlmodule Qt3D.Extras
- \brief The PhongAlphaMaterial class provides a default implementation of
- the phong lighting effect with alpha.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The phong lighting effect is based on the combination of 3 lighting components ambient, diffuse
- and specular. The relative strengths of these components are controlled by means of their
- reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \li Alpha is the transparency of the surface between 0 (fully transparent) and 1 (opaque).
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color PhongAlphaMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty color PhongAlphaMaterial::diffuse
-
- Holds the current diffuse color.
-*/
-/*!
- \qmlproperty color PhongAlphaMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty real PhongAlphaMaterial::shininess
-
- Holds the current shininess.
-*/
-/*!
- \qmlproperty real PhongAlphaMaterial::alpha
-
- Holds the alpha component of the object which varies between 0 and 1.
-
- The default value is 0.5.
-*/
-
-/*!
- \qmltype PhongMaterial
- \inqmlmodule Qt3D.Extras
- \brief The PhongMaterial class provides a default implementation of the phong lighting effect.
- \since 5.7
- \inherits Qt3D.Render::Material
-
- The phong lighting effect is based on the combination of 3 lighting components ambient, diffuse
- and specular. The relative strengths of these components are controlled by means of their
- reflectivity coefficients which are modelled as RGB triplets:
-
- \list
- \li Ambient is the color that is emitted by an object without any other light source.
- \li Diffuse is the color that is emitted for rought surface reflections with the lights.
- \li Specular is the color emitted for shiny surface reflections with the lights.
- \li The shininess of a surface is controlled by a float property.
- \endlist
-
- This material uses an effect with a single render pass approach and performs per fragment
- lighting. Techniques are provided for OpenGL 2, OpenGL 3 or above as well as OpenGL ES 2.
-*/
-/*!
- \qmlproperty color PhongMaterial::ambient
-
- Holds the current ambient color.
-*/
-/*!
- \qmlproperty color PhongMaterial::diffuse
-
- Holds the current diffuse color.
-*/
-/*!
- \qmlproperty color PhongMaterial::specular
-
- Holds the current specular color.
-*/
-/*!
- \qmlproperty real PhongMaterial::shininess
-
- Holds the current shininess.
-*/
diff --git a/src/doc/src/qt3d-module.qdoc b/src/doc/src/qt3d-module.qdoc
index 86a17342e..c7d589c2a 100644
--- a/src/doc/src/qt3d-module.qdoc
+++ b/src/doc/src/qt3d-module.qdoc
@@ -38,19 +38,6 @@
****************************************************************************/
/*!
- \module Qt3DCore
- \title Qt 3D Core C++ Classes
- \brief The Qt 3D module contains functionality to support near-realtime simulation systems.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3dcore
-
- The Qt 3D module provides the foundations and core types used for near-realtime
- simulations built on the Qt 3D framework.
-*/
-
-/*!
\page qt3d-cpp.html
\title Qt 3D C++ Classes
\brief The Qt 3D module contains functionality to support near-realtime simulation systems.
@@ -86,38 +73,27 @@
*/
/*!
- \namespace Qt3DCore
- \inmodule Qt3DCore
- \ingroup qt3d-namespaces
-
- \brief Contains classes that are the foundation for Qt 3D simulation
- framework, as well as classes that provide the ability to render using the
- Qt 3D framework.
-*/
-
-/*!
- \qmlmodule Qt3D.Core 2.0
+ \page qt3d-qml.html
\title Qt 3D QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides core Qt 3D QML types.
+ \brief QML Types for the Qt 3D module.
- To import and use the module's QML types, use the following statement:
+ The Qt 3D core QML types are imported with
\badcode
import Qt3D.Core 2.0
\endcode
- For collision detection, renderer, and input-related QML types, use the
- following import statements:
+ Other modules import functionality for collision detection, rendering, input,
+ and animation. The complete list of Qt 3D import statements:
\badcode
+ import Qt3D.Core 2.0
import Qt3D.Render 2.0
import Qt3D.Input 2.0
import Qt3D.Logic 2.0
import Qt3D.Extras 2.0
import Qt3D.Animation 2.9
+ import Qt3D.Scene2D 2.9
\endcode
\section1 QML Types
diff --git a/src/doc/src/qt3danimation-module.qdoc b/src/doc/src/qt3danimation-module.qdoc
deleted file mode 100644
index ed3406aa4..000000000
--- a/src/doc/src/qt3danimation-module.qdoc
+++ /dev/null
@@ -1,228 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd.
-** Copyright (C) 2017 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DAnimation
- \title Qt 3D Animation C++ Classes
-
- \brief The Qt 3D Animation modules provides a set of prebuilt elements to help
- you get started with Qt 3D.
-
- This module is still in tech preview. This means it is unstable, likely to
- change and provided as a convenience only.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3danimation
-
- \code
- #include <Qt3DAnimation>
- \endcode
-
- To link against the corresponding C++ library, add the following to your qmake project file:
-
- \badcode
- QT += 3danimation
- \endcode
-
- Classes, types, and functions are declared under the \l [Qt3DAnimation]{Qt3DAnimation} namespace.
-
- \section1 Overview
-
- The Qt 3D Animation module adds support for specifying and using animations
- that can be applied to the properties of objects in your simulation.
- Initially this module supports key frame based animations. That is,
- properties have values 'keyed' at certain times and when played back the
- property values are calculated by interpolating between the known values
- within the key frames. All of the animation evaluation within the Qt 3D
- Animation module takes place on the Qt 3D threadpool. This allows the
- animations to run smoothly and to scale up to high throughput.
-
- \section2 Animation Data
-
- Key frame animation data can either be created programmatically via the Qt
- 3D Animation APIs such as Qt3DAnimation::QKeyFrameData or it can come from
- digital content creation (DCC) tools such as Blender, Maya or 3D Studio
- Max. Qt 3D provides an example export script for animation data for
- Blender. The format consumed by Qt 3D Animation at present is a simple JSON
- based format. This allows both developers and artists to easily work with
- animation data. More formats optimised for runtime consumption will be
- added later.
-
- The key frame animation data can be loaded from file using the
- Qt3DAnimation::QAnimationClipLoader class. To specify animation data
- programmatically use the Qt3DAnimation::QAnimationClip class.
-
- By default, the key frame data is specified using cubic bezier curves. This
- allows smooth animations to be created from a small number of key frame
- data points. Other interpolation types will be added later.
-
- \section2 Playing Animations
-
- In addition to the animation data containing the key frames, Qt 3D
- Animation also provides APIs for playing the animations and mapping the
- resulting property values onto properties of objects in your simulation.
- There are currently two ways of playing the animations:
-
- \list
- \li Qt3DAnimation::QClipAnimator
- \li Qt3DAnimation::QBlendedClipAnimator
- \endlist
-
- Both of these are implemented as subclasses of Qt3DCore::QComponent meaning
- that objects of these types can be aggregated by Qt3DCore::QEntity objects
- to add animation capabilities to your simulated entities.
-
- \section2 Simple Animation Playback
-
- The Qt3DAnimation::QClipAnimator class allows the playback of a single
- Qt3DAnimation::QAbstractAnimationClip at a time. To add an animation to an
- entity, simply add an instance of the Qt3DAnimation::QClipAnimator class to
- your entity's \c components property.
-
- The Qt 3D Animation module takes a slightly different approach to
- QPropertyAnimation and AbstractAnimation. With those animation frameworks,
- the animation specifies both the animation values \e {and} the target
- objects and properties. The animation components in Qt 3D separate these
- two orthogonal concepts. For example, the Qt3DAnimation::QClipAnimator
- component has a \c clip property for specifying the animation data
- (Qt3DAnimation::QAnimationClip or Qt3DAnimation::QAnimationClipLoader).
-
- This allows calculation of the animated values, but more information is
- needed in order to map these values onto properties of objects. This is
- accomplished with the a Qt3DAnimation::QChannelMapper which contains a list
- of Qt3DAnimation::QChannelMapping objects. A Qt3DAnimation::QChannelMapping
- is used to map a specific channel from an animation clip onto a named
- property of a target object. By separating the animation data and property
- mappings like this, the same animation can be applied to many objects
- without needing to have multiple copies of the animation data or objects.
- It also allows animation data to easily be retargeted to other objects.
-
- \section2 Blended Animation Playback
-
- The Qt3DAnimation::QBlendedClipAnimator component allows to go beyond what
- is possible with Qt3DAnimation::QClipAnimator by blending several animation
- clips together before applying the property changes to the target
- properties. The animator component still takes a channel mapper just like
- the standard Qt3DAnimation::QClipAnimator component. However, instead of
- specifying a single animation clip, it is necessary to set the \c blendTree
- property to point to the root node of a \e {blend tree}.
-
- A blend tree is a data structure representing how animation clips get
- aggregated or blended together as the function of properties on the blend
- tree nodes. The currently supported set of blend tree nodes are:
-
- \list
- \li Qt3DAnimation::QClipBlendValue
- \li Qt3DAnimation::QLerpClipBlend
- \li Qt3DAnimation::QAdditiveClipBlend
- \endlist
-
- The source animation clip inputs are specified as leaf nodes in the blend
- tree using instances of the Qt3DAnimation::QClipBlendValue class. These
- animation clips can be combined in a large number of ways. For now the Qt3D
- Animation module provides linear interpolation (LERP) and additive blend
- operations. More blend node types will be added over time. These are
- expected to include at least a generalised LERP node and a barycentric LERP
- node.
-
- As an example consider the following blend tree:
-
- \badcode
- Clip0----
- |
- Lerp Node----
- | |
- Clip1---- Additive Node
- |
- Clip2----
- \endcode
-
- Let's assume that \c Clip0 represents a walk animation cycle with a
- duration of 3 seconds and that \c Clip1 is a run animation cycle with a
- duration of 2 seconds. These are both inputs (and dependencies) of the \c
- Lerp blend node. The result of evaluating the \c Lerp node depends upon the
- \c blendFactor property of the \c Lerp node. This could be bound to the
- speed of a humanoid character entity for example. As the speed of the
- character increases the animation gradually cross-fades from the walk
- animation in \c Clip0 to the run animation in \c Clip1.
-
- Furthermore, let's assume that \c Clip2 represents some variation animation
- that can be added on (waving arms or shaking head for e.g.). The amount of
- this additive clip that is added can be controlled by the \c additiveFactor
- property on the \c Additive blend node.
-
- When evaluating a blend tree, normalized time (or phase) is used so that
- clips of different durations can be blended together without problems. For
- example, even though the walk and run animation clips are of different
- lengths, as long as they are created by the animator such that the
- foot-falls line up at the same phase these can be nicely interpolated.
-
- The implication of this is that the duration of the blended clip is
- actually a function of the blend factors of the nodes in the tree.
- Considering only the \c Lerp node in the above example, when the blend
- factor of the \c Lerp node is 0, only the walk animation in Clip0 is used
- resulting in a duration of 3 seconds. With a blend factor of 1 the
- resulting duration will be 2 seconds. For intermediate blend factors, the
- duration will be linearly interpolated between 3 and 2 seconds.
-
- By definining your own blend trees, you have complete control over how to
- combine your collection of input animation clips. The blend tree can be
- configured by the properties on the blend nodes. Note also that the
- properties on the blend nodes themselves are just standard properties, so
- these could in turn be driven by other animations if desired.
-
- \section1 Reference
- \list
- \li \l {Qt 3D Animation C++ Classes}
- \li \l {Qt 3D Examples}
- \endlist
- */
-
-/*!
- \namespace Qt3DAnimation
- \inmodule Qt3DAnimation
- \ingroup qt3d-namespaces
-
- \brief Contains classes from the Qt3DAnimation module.
-*/
-
-/*!
- \qmlmodule Qt3D.Animation 2.9
- \title Qt 3D Qt3DAnimation QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides Qt 3D QML types for the animation module.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Animation 2.9
- \endcode
-*/
diff --git a/src/doc/src/qt3dextras-module.qdoc b/src/doc/src/qt3dextras-module.qdoc
deleted file mode 100644
index b9a7cc28a..000000000
--- a/src/doc/src/qt3dextras-module.qdoc
+++ /dev/null
@@ -1,128 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DExtras
- \title Qt 3D Extras C++ Classes
-
- \brief The Qt 3D Extras modules provides a set of prebuilt elements to help
- you get started with Qt 3D.
-
- This module is still in tech preview. This means it is unstable, likely to
- change and provided as a convenience only.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3dextras
-
- \code
- #include <Qt3DExtras>
- \endcode
-
- To link against the corresponding C++ library, add the following to your qmake project file:
-
- \badcode
- QT += 3dextras
- \endcode
-
- Classes, types, and functions are declared under the \l [Qt3DExtras]{Qt3DExtras} namespace.
-
- \section1 Overview
-
- \section2 Materials
-
- \annotatedlist qt3d-extras-materials
-
- \section2 Meshes and Geometries
-
- \annotatedlist qt3d-extras-geometries
-
- \section2 Camera Controllers
-
- \annotatedlist qt3d-extras-cameracontrollers
-
- \section2 Entities
-
- \list
- \li Qt3DExtras::QSkyboxEntity
- \endlist
-
- \section2 FrameGraphs
-
- \list
- \li Qt3DExtras::QForwardRenderer
- \endlist
-
- \section2 Window
-
- \list
- \li Qt3DExtras::Qt3DWindow
- \endlist
-
- \note The Quick3DExtras module also specifies a Qt3DExtras::Quick::Qt3DQuickWindow.
-
- \section1 Reference
- \list
- \li \l {Qt 3D Extras C++ Classes}
- \li \l {Qt 3D Examples}
- \endlist
- */
-
-/*!
- \namespace Qt3DExtras
- \inmodule Qt3DExtras
- \ingroup qt3d-namespaces
-
- \brief Contains classes from the Qt3DExtras module.
-*/
-
-/*!
- \qmlmodule Qt3D.Extras 2.0
- \title Qt 3D Extras QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides Qt 3D QML types for the extras module.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Extras 2.0
- \endcode
-*/
diff --git a/src/doc/src/qt3dinput-module.qdoc b/src/doc/src/qt3dinput-module.qdoc
deleted file mode 100644
index b14380e3a..000000000
--- a/src/doc/src/qt3dinput-module.qdoc
+++ /dev/null
@@ -1,75 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DInput
- \title Qt 3D Input C++ Classes
- \brief The Qt 3D Input module provides classes for handling user input in
- applications using Qt3D.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3dinput
-
- To use classes from this module, add this directive into the C++ files:
-
- \code
- #include <Qt3DInput>
- \endcode
-
- To link against the corresponding C++ libraries, add the following to your qmake project file:
-
- \badcode
- QT += 3dinput
- \endcode
-*/
-
-/*!
- \namespace Qt3DInput
- \inmodule Qt3DInput
- \ingroup qt3d-namespaces
-
- \brief Contains classes that enable user input.
-*/
-
-/*!
- \qmlmodule Qt3D.Input 2.0
- \title Qt 3D Input QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides QML types for Qt 3D user input.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Input 2.0
- \endcode
-
- \section1 QML Types
-*/
-
diff --git a/src/doc/src/qt3dlogic-module.qdoc b/src/doc/src/qt3dlogic-module.qdoc
deleted file mode 100644
index 826ac1e4f..000000000
--- a/src/doc/src/qt3dlogic-module.qdoc
+++ /dev/null
@@ -1,75 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 The Qt Company Ltd.
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the documentation of the Qt Toolkit.
-**
-** $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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Free Documentation License Usage
-** Alternatively, this file may be used under the terms of the GNU Free
-** Documentation License version 1.3 as published by the Free Software
-** Foundation and appearing in the file included in the packaging of
-** this file. Please review the following information to ensure
-** the GNU Free Documentation License version 1.3 requirements
-** will be met: https://www.gnu.org/licenses/fdl-1.3.html.
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DLogic
- \title Qt 3D Logic C++ Classes
- \brief The Qt 3D Logic module enables synchronizing frames with the Qt 3D
- backend.
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3dlogic
-
- To use classes from this module, add this directive into the C++ files:
-
- \code
- #include <Qt3DLogic>
- \endcode
-
- To link against the corresponding C++ libraries, add the following to your qmake project file:
-
- \badcode
- QT += 3dLogic
- \endcode
-
-*/
-
-/*!
- \namespace Qt3DLogic
- \inmodule Qt3DLogic
- \ingroup qt3d-namespaces
-
- \brief Contains classes that enable frame synchronization.
-*/
-
-/*!
- \qmlmodule Qt3D.Logic 2.0
- \title Qt 3D Logic QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides QML types to synchronize frames with the 3D backend.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Logic 2.0
- \endcode
-
- \section1 QML Types
-*/
-
diff --git a/src/doc/src/qt3drender-framegraph.qdoc b/src/doc/src/qt3drender-framegraph.qdoc
deleted file mode 100644
index 44b1cbe89..000000000
--- a/src/doc/src/qt3drender-framegraph.qdoc
+++ /dev/null
@@ -1,518 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page qt3drender-framegraph.html
- \title Qt 3D Render Framegraph
-
- \brief A framegraph is the data structure that controls how a scene is
- rendered.
-
- The Qt 3D Render aspect allows for the rendering algorithm to be entirely
- data-driven. The controlling data structure is known as the \e framegraph.
- Similar to how the Qt 3D ECS (entity component system) allows you to define
- a so-called Scenegraph by building a scene from a tree of Entities and
- Components, the framegraph is also a tree structure but one used for a
- different purpose. Namely, controlling \e how the scene is rendered.
-
- Over the course of rendering a single frame, a 3D renderer will likely
- change state many times. The number and nature of these state changes
- depends upon not only which materials (shaders, mesh geometry, textures and
- uniform variables) are found within the scene, but also upon which high
- level rendering scheme you are using.
-
- For example, using a traditional simple \e{forward rendering} scheme is
- very different to using a \e{deferred rendering} approach. Other features
- such as reflections, shadows, multiple viewports, and early z-fill passes
- all change which states a renderer needs to set over the course of a frame
- and when those state changes need to occur.
-
- As a comparison, the \l {Qt Quick Scene Graph}{Qt Quick 2
- scenegraph renderer} responsible for drawing Qt Quick 2 scenes is
- hard-wired in C++ to do things like batching of primitives and rendering
- opaque items followed by rendering of transparent items. In the case of Qt
- Quick 2 that is perfectly fine as that covers all of the requirements. As
- you can see from some of the examples listed above, such a hard-wired
- renderer is not likely to be flexible enough for generic 3D scenes given
- the multitude of rendering methods available. Or if a renderer could be
- made flexible enough to cover all such cases, its performance would likely
- suffer from being too general. To make matters worse, more rendering
- methods are being researched all of the time. We therefore needed an
- approach that is \e {both flexible and extensible} whilst being simple to
- use and maintain. Enter the framegraph!
-
- Each node in the framegraph defines a part of the configuration the
- renderer will use to render the scene. The position of a node in the
- framegraph tree determines when and where the subtree rooted at that node
- will be the active configuration in the rendering pipeline. As we will see
- later, the renderer traverses this tree in order to build up the state
- needed for your rendering algorithm at each point in the frame.
-
- Obviously if you just want to render a simple cube onscreen you may think
- this is overkill. However, as soon as you want to start doing slightly more
- complex scenes this comes in handy. For the common cases, Qt 3D provides
- some example framegraphs that are ready to use out of the box.
-
- We will demonstrate the flexibility of the framegraph concept by presenting a few
- examples and the resulting framegraphs.
-
- Please note that unlike the Scenegraph which is composed of Entities and
- Components, the framegraph is only composed of nested nodes which are all
- subclasses of Qt3DRender::QFrameGraphNode. This is because the framegraph nodes
- are not simulated objects in our virtual world, but rather supporting
- information.
-
- We will soon see how to
- construct our first simple framegraph but before that we will introduce
- the framegraph nodes available to you. Also as with the Scenegraph tree,
- the QML and C++ APIs are a 1 to 1 match so you can favor the one you like
- best. For the sake of readability and conciseness, the QML API was chosen
- for this article.
-
- \omit
- TODO: Add list of framegraph node types
- \endomit
-
- The beauty of the framegraph is that combining these simple node types, it
- is possible to configure the renderer to suit your specific needs without
- touching any hairy, low-level C/C++ rendering code at all.
-
- \section1 FrameGraph Rules
-
- In order to construct a correctly functioning framegraph tree,
- you should know a few rules about how it is traversed and how to feed it to
- the Qt 3D renderer.
-
- \section2 Setting the Framegraph
-
- The FrameGraph tree should be assigned to the activeFrameGraph property of
- a QRenderSettings component, itself being a component of the root entity in
- the Qt 3D scene. This is what makes it the active framegraph for the
- renderer. Of course, since this is a QML property binding, the active
- framegraph (or parts of it) can be changed on the fly at runtime. For
- example, if you want to use different rendering approaches for indoor and
- outdoor scenes or to enable or disable some special effect.
-
- \badcode
- Entity {
- id: sceneRoot
- components: RenderSettings {
- activeFrameGraph: ... // FrameGraph tree
- }
- }
- \endcode
-
- \note activeFrameGraph is the default property of the FrameGraph component
- in QML.
-
- \badcode
- Entity {
- id: sceneRoot
- components: RenderSettings {
- ... // FrameGraph tree
- }
- }
- \endcode
-
- \section2 How the Framegraph Is Used
-
- \list
- \li The Qt 3D renderer performs a \e{depth first traversal} of the
- framegraph tree. Note that, because the traversal is depth first,
- the \e {order in which you define nodes is important}.
- \li When the renderer reaches a leaf node of the framegraph, it
- collects together all of the state specified by the path from the
- leaf node to the root node. This defines the state used to render
- a section of the frame. If you are interested in the internals of
- Qt 3D, this collection of state is called a \e RenderView.
- \li Given the configuration contained in a RenderView, the renderer
- collects together all of the Entities in the Scenegraph to be
- rendered, and from them builds a set of \e RenderCommands and
- associates them with the RenderView.
- \li The combination of RenderView and set of RenderCommands is passed
- over for submission to OpenGL.
- \li When this is repeated for each leaf node in the framegraph, the
- frame is complete and the renderer calls
- QOpenGLContext::swapBuffers() to display the frame.
- \endlist
-
- At its heart, the framegraph is a data-driven method for configuring the
- Qt 3D renderer. Due to its data-driven nature, we can change configuration
- at runtime, allow non-C++ developers or designers to change the structure
- of a frame, and try out new rendering approaches without having to write
- thousands of lines of boiler plate code.
-
-
- \section1 Framegraph Examples
-
- Now that you know the rules to abide by when writing a framegraph tree, we
- will go over a few examples and break them down.
-
- \section2 A Simple Forward Renderer
-
- Forward rendering is when you use OpenGL in its traditional manner and
- render directly to the backbuffer one object at a time shading each one as
- we go. This is opposed to \l {Deferred Renderer}{deferred rendering} where
- we render to an intermediate \e G-buffer. Here is a simple FrameGraph that
- can be used for forward rendering:
-
- \badcode
- Viewport {
- rect: Qt.rect(0.0, 0.0, 1.0, 1.0)
- property alias camera: cameraSelector.camera
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
-
- CameraSelector {
- id: cameraSelector
- }
- }
- }
- \endcode
-
- As you can see, this tree has a single leaf and is composed of 3 nodes in
- total as shown in the following diagram.
-
- \image simple-framegraph.png
-
- Using the rules defined \l {Framegraph Rules}{above}, this framegraph tree yields a single
- RenderView with the following configuration:
-
- \list
- \li Leaf Node -> RenderView
- \list
- \li Viewport that fills the entire screen (uses normalized
- coordinates to make it easy to support nested viewports)
- \li Color and Depth buffers are set to be cleared
- \li Camera specified in the exposed camera property
- \endlist
- \endlist
-
- Several different FrameGraph trees can produce the same rendering result.
- As long as the state collected from leaf to root is the same, the result
- will also be the same. It is best to put state that remains constant longest
- nearer to the root of the framegraph as this will result in fewer leaf
- nodes, and hence, fewer RenderViews overall.
-
- \badcode
- Viewport {
- rect: Qt.rect(0.0, 0.0, 1.0, 1.0)
- property alias camera: cameraSelector.camera
-
- CameraSelector {
- id: cameraSelector
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
- }
- }
- }
- \endcode
-
- \badcode
- CameraSelector {
- Viewport {
- rect: Qt.rect(0.0, 0.0, 1.0, 1.0)
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
- }
- }
- }
- \endcode
-
- \section2 A Multi Viewport FrameGraph
-
- Let us move on to a slightly more complex example that renders a Scenegraph
- from the point of view of 4 virtual cameras into the 4 quadrants of the
- window. This is a common configuration for 3D CAD or modelling tools or
- could be adjusted to help with rendering a rear-view mirror in a car racing
- game or a CCTV camera display.
-
- \image multiviewport.png
-
- \badcode
- Viewport {
- id: mainViewport
- rect: Qt.rect(0, 0, 1, 1)
- property alias Camera: cameraSelectorTopLeftViewport.camera
- property alias Camera: cameraSelectorTopRightViewport.camera
- property alias Camera: cameraSelectorBottomLeftViewport.camera
- property alias Camera: cameraSelectorBottomRightViewport.camera
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
- }
-
- Viewport {
- id: topLeftViewport
- rect: Qt.rect(0, 0, 0.5, 0.5)
- CameraSelector { id: cameraSelectorTopLeftViewport }
- }
-
- Viewport {
- id: topRightViewport
- rect: Qt.rect(0.5, 0, 0.5, 0.5)
- CameraSelector { id: cameraSelectorTopRightViewport }
- }
-
- Viewport {
- id: bottomLeftViewport
- rect: Qt.rect(0, 0.5, 0.5, 0.5)
- CameraSelector { id: cameraSelectorBottomLeftViewport }
- }
-
- Viewport {
- id: bottomRightViewport
- rect: Qt.rect(0.5, 0.5, 0.5, 0.5)
- CameraSelector { id: cameraSelectorBottomRightViewport }
- }
- }
- \endcode
-
- This tree is a bit more complex with 5 leaves. Following the same rules as
- before we construct 5 RenderView objects from the FrameGraph. The following
- diagrams show the construction for the first two RenderViews. The remaining
- RenderViews are very similar to the second diagram just with the other
- sub-trees.
-
- \image multiviewport-1.png
-
- \image multiviewport-2.png
-
- In full, the RenderViews created are:
-
- \list
- \li RenderView (1)
- \list
- \li Fullscreen viewport defined
- \li Color and Depth buffers are set to be cleared
- \endlist
-
- \li RenderView (2)
- \list
- \li Fullscreen viewport defined
- \li Sub viewport defined (rendering viewport will be scaled relative to its parent)
- \li CameraSelector specified
- \endlist
-
- \li RenderView (3)
- \list
- \li Fullscreen viewport defined
- \li Sub viewport defined (rendering viewport will be scaled relative to its parent)
- \li CameraSelector specified
- \endlist
-
- \li RenderView (4)
- \list
- \li Fullscreen viewport defined
- \li Sub viewport defined (rendering viewport will be scaled relative to its parent)
- \li CameraSelector specified
- \endlist
-
- \li RenderView (5)
- \list
- \li Fullscreen viewport defined
- \li Sub viewport defined (rendering viewport will be scaled relative to its parent)
- \li CameraSelector specified
- \endlist
- \endlist
-
- However, in this case the \e {order is important}. If the ClearBuffers node
- were to be the last instead of the first, this would result in a black
- screen for the simple reason that everything would be cleared right after
- having been so carefully rendered. For a similar reason, it could not be
- used as the root of the FrameGraph as that would result in a call to clear
- the whole screen for each of our viewports.
-
- Although the declaration order of the FrameGraph is important, Qt 3D is able
- to process each RenderView in parallel as each RenderView is independent of
- the others for the purposes of generating a set of RenderCommands to be
- submitted whilst the RenderView's state is in effect.
-
- Qt 3D uses a task-based approach to parallelism which naturally scales up
- with the number of available cores. This is shown in the following diagram
- for the previous example.
-
- \image framegraph-parallel-build.png
-
- The RenderCommands for the RenderViews can be generated in parallel across
- many cores, and as long as we take care to submit the RenderViews in the
- correct order on the dedicated OpenGL submission thread, the resulting
- scene will be rendered correctly.
-
- \section2 Deferred Renderer
-
- When it comes to rendering, deferred rendering is a different beast in
- terms of renderer configuration compared to forward rendering. Instead of
- drawing each mesh and applying a shader effect to shade it, deferred
- rendering adopts a \e {two render pass} method.
-
- First all the meshes in the scene are drawn using the same shader that will
- output, usually for each fragment, at least four values:
-
- \list
- \li World normal vector
- \li Color (or some other material properties)
- \li Depth
- \li World position vector
- \endlist
-
- Each of these values will be stored in a texture. The normal, color, depth,
- and position textures form what is called the G-Buffer. Nothing is drawn
- onscreen during the first pass, but rather drawn into the G-Buffer ready
- for later use.
-
- Once all the meshes have been drawn, the G-Buffer is filled with all the
- meshes that can currently be seen by the camera. The second render pass is
- then used to render the scene to the back buffer with the final color
- shading by reading the normal, color, and position values from the G-buffer
- textures and outputting a color onto a full screen quad.
-
- The advantage of that technique is that the heavy computing power required
- for complex effects is only used during the second pass only on the
- elements that are actually being seen by the camera. The first pass does
- not cost much processing power as every mesh is being drawn with a simple
- shader. Deferred rendering, therefore, decouples shading and lighting from
- the number of objects in a scene and instead couples it to the resolution
- of the screen (and G-Buffer). This is a technique that has been used in
- many games due to the ability to use large numbers of dynamic lights at
- the expense of additional GPU memory usage.
-
- \badcode
- Viewport {
- rect: Qt.rect(0.0, 0.0, 1.0, 1.0)
-
- property alias gBuffer: gBufferTargetSelector.target
- property alias camera: sceneCameraSelector.camera
-
- LayerFilter {
- layers: "scene"
-
- RenderTargetSelector {
- id: gBufferTargetSelector
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
-
- RenderPassFilter {
- id: geometryPass
- includes: Annotation { name: "pass"; value: "geometry" }
-
- CameraSelector {
- id: sceneCameraSelector
- }
- }
- }
- }
- }
-
- LayerFilter {
- layers: "screenQuad"
-
- ClearBuffers {
- buffers: ClearBuffers.ColorDepthBuffer
-
- RenderPassFilter {
- id: finalPass
- includes: Annotation { name: "pass"; value: "final" }
- }
- }
- }
- }
- \endcode
-
- Graphically, the resulting framegraph looks like:
-
- \image deferred-framegraph.png
-
- And the resulting RenderViews are:
-
- \list
- \li RenderView (1)
- \list
- \li Define a viewport that fills the whole screen
- \li Select all Entities that have a Layer component matching
- \c "scene"
- \li Set the \c gBuffer as the active render target
- \li Clear the color and depth on the currently bound render target
- (the \c gBuffer)
- \li Select only Entities in the scene that have a Material and
- Technique matching the annotations in the RenderPassFilter
- \li Specify which camera should be used
- \endlist
-
- \li RenderView (2)
- \list
- \li Define a viewport that fills the whole screen
- \li Select all Entities that have a Layer component matching
- \c "screenQuad"
- \li Clear the color and depth buffers on the currently bound
- framebuffer (the screen)
- \li Select only Entities in the scene that have a Material and
- Technique matching the annotations in the RenderPassFilter
- \endlist
- \endlist
-
- \section1 Other Benefits of the framegraph
-
- Since the FrameGraph tree is entirely data-driven and can be modified dynamically at runtime, you can:
-
- \list
- \li Have different framegraph trees for different platforms and
- hardware and select the most appropriate at runtime
- \li Easily add and enable visual debugging in a scene
- \li Use different FrameGraph trees depending on the nature of what
- you need to render for a particular region of the scene
- \li Implement a new rendering technique without having to
- modify Qt 3D's internals
- \endlist
-
- \section1 Conclusion
-
- We have introduced the FrameGraph and the node types that compose it. We
- then went on to discuss a few examples to illustrate the framegraph
- building rules and how the Qt 3D engine uses the framegraph behind the
- scenes. By now you should have a pretty good overview of the FrameGraph and
- how it can be used (perhaps to add an \l {early z-fill pass} to a
- forward renderer). Also you should always keep in mind that the FrameGraph
- is a tool for you to use so that you are not tied down to the provided
- renderer and materials that Qt 3D provides out of the box.
-*/
diff --git a/src/doc/src/qt3drender-geometry.qdoc b/src/doc/src/qt3drender-geometry.qdoc
deleted file mode 100644
index 03e84b1d7..000000000
--- a/src/doc/src/qt3drender-geometry.qdoc
+++ /dev/null
@@ -1,154 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page qt3drender-geometry.html
- \title Qt 3D Render Geometry
-
- \brief Presents the classes provided by the Qt 3D Render aspect to specify
- data to the renderer, typically containing geometry.
-
- Qt 3D Render provides a generic way of storing geometry data and specifying
- how it should be read by the renderer.
-
- \list
- \li \l {Buffer}
- \li \l {Attribute}
- \li \l {Geometry}
- \li \l {GeometryRenderer}
- \endlist
-
- \section2 Buffer
-
- The Qt3DRender::QBuffer class stores the raw data. This acts purely as an
- array of memory. In most cases a Qt3DRender::QBuffer will be used
- indirectly by being referenced by one or more Qt3DRender::QAttributes.
- However there are times when a QBuffer may be used directly as the value
- property of a QParameter when dealing with Uniform Buffer Objects (UBO) or
- Shader Storage Buffer Objects (SSBO).
-
- \code
- Buffer {
- id: vertexBuffer
- type: Buffer.VertexBuffer
- data: buildVertexBufferData()
- }
- \endcode
-
- \section2 Attribute
-
- Qt3DRender::QAttribute specifies how data contained in the referenced
- buffer should be extracted and passed to an input of a vertex shader. It
- references a Qt3DRender::QBuffer and can specify the layout of the
- attributes by definining the vertex size, the data type, the stride between
- two vertices and a starting offset. The type of the attribute will also
- define whether it is to be used as a vertex buffer or as an index buffer.
- This allows you complete flexibility of how you structure your data in
- buffers. It is possible to use separate buffers for each vertex attribute,
- an interleaved buffer containing data for all attributes or a combination
- of separate and interleaved buffers.
-
- \code
- Attribute {
- attributeType: Attribute.VertexAttribute
- vertexBaseType: Attribute.Float
- vertexSize: 3
- byteOffset: 0
- byteStride: 9 * 4
- count: 4
- name: defaultPositionAttributeName()
- buffer: vertexBuffer
- }
- \endcode
-
- \section2 Geometry
-
- A Qt3DRender::QGeometry aggregates various attributes to form a piece of
- geometry. Usually a proper geometry will provide an attribute for vertex
- positions, an attribute for vertex normals and an attribute for texture
- coordinates. If you want your geometry to also work with normal mapped
- materials it will need to provide a consistent set of vertex tangent
- vectors too.
-
- \code
- Geometry {
- Attribute {
- attributeType: Attribute.VertexAttribute
- vertexBaseType: Attribute.Float
- vertexSize: 3
- byteOffset: 0
- byteStride: 9 * 4
- count: 4
- name: defaultPositionAttributeName()
- buffer: vertexBuffer
- }
-
- Attribute {
- attributeType: Attribute.VertexAttribute
- vertexBaseType: Attribute.Float
- vertexSize: 3
- byteOffset: 3 * 4
- byteStride: 9 * 4
- count: 4
- name: defaultNormalAttributeName()
- buffer: vertexBuffer
- }
- \endcode
-
- \section2 GeometryRenderer
-
- Qt3DRender::QGeometryRenderer is a QComponent which when aggregated by a
- QEntity allows to draw the Qt3DRender::QGeometry it references. It provides
- properties to control the draw call such as the number of instances to be
- drawn, the starting instance, the type of
- Qt3DRender::QGeometryRenderer::PrimitiveType to be used, etc. A
- Qt3DRender::QGeometryRenderer is translated into a draw call to the
- underlying graphics API.
-
- \code
- GeometryRenderer {
- instanceCount: 1
- indexOffset: 0
- firstInstance: 0
- primitiveType: GeometryRenderer.Triangles
- geometry: Geometry { ... }
- }
- \endcode
-
- */
diff --git a/src/doc/src/qt3drender-module.qdoc b/src/doc/src/qt3drender-module.qdoc
deleted file mode 100644
index 6599c2e11..000000000
--- a/src/doc/src/qt3drender-module.qdoc
+++ /dev/null
@@ -1,100 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DRender
- \title Qt 3D Render C++ Classes
- \brief The Qt 3D Render module contains functionality to support 2D and 3D
- rendering using Qt 3D.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3drender
-
- The Qt 3D Render module provides an aspect, components, and other supporting types necessary
- to implement 2D and 3D rendering as part of the Qt 3D framework.
-
- To use classes from this module, add this directive into the C++ files:
-
- \code
- #include <Qt3DRender>
- \endcode
-
- To link against the corresponding C++ library, add the following to your qmake project file:
-
- \badcode
- QT += 3drender
- \endcode
-
- Classes, types, and functions are declared under the \l [Qt3DRender]{Qt3DRender} namespace.
-
- \section1 Overview
-
- The Qt 3D Render aspect offers support for data-driven configuration as described
- in \l {Qt 3D Render Framegraph}.
-
- \section1 Reference
- \list
- \li \l {Qt 3D Render C++ Classes}
- \li \l {Qt 3D Examples}
- \endlist
-*/
-
-/*!
- \namespace Qt3DRender
- \inmodule Qt3DRender
- \ingroup qt3d-namespaces
-
- \brief Contains classes that enable 2D and 3D rendering.
-*/
-
-/*!
- \qmlmodule Qt3D.Render 2.0
- \title Qt 3D Render QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides Qt 3D QML types for rendering.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Render 2.0
- \endcode
-*/
diff --git a/src/doc/src/qt3drender-protips.qdoc b/src/doc/src/qt3drender-protips.qdoc
deleted file mode 100644
index c78f3d598..000000000
--- a/src/doc/src/qt3drender-protips.qdoc
+++ /dev/null
@@ -1,130 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2016 Klaralvdalens Datakonsult AB (KDAB).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \page qt3drender-protips.html
- \title Qt 3D Render Pro Tips
-
- \brief This sections tries to make you aware of various pitfalls inherent
- to 3D rendering and ways to prevent them.
-
- To render even the simplest shapes, Qt 3D needs to perform various
- operations through several stages. If anything goes wrong at any of these
- stages you may end up, in the best cases with something different than what
- you expected, in the worst cases with a black screen.
-
- \list
- \li \l {Technique Selection}
- \li \l {Order Matters}
- \li \l {Blending}
- \li \l {Useful Tools}
- \endlist
-
- \section2 Technique Selection
-
- Qt 3D provides a technique selection mechanism allowing you to provide
- shaders for various rendering APIs and versions of these APIs.
-
- In order to avoid unnecessary waste of your time, you should make sure
- that your technique's API filter data is correct for the platform you are
- targeting.
-
- \section2 Order Matters
-
- The order of the draw calls performed by the renderer is not necessarily
- the same as the order of the entities in the scene.
-
- The renderer tries to optimize calls that are sent to the graphics API.
- It orders draw calls based on the material/shader being used, the render
- states that are defined for a given material, their depth, the parameters
- shared in common between two materials, etc.
-
- If your rendering depends on a specific draw order you should then have
- a few options:
-
- \list
-
- \li Filtering with a Qt3DRender::QLayer component and
- Qt3DRender::QLayerFilter in the FrameGraph
-
- \li RenderPass or Technique filtering using Qt3DRender::QRenderPassFilter
- or Qt3DRender::QTechniqueFilter in the FrameGraph
-
- \endlist
-
- \section2 Blending
-
- Mastering blending with proper arguments and functions is an art in
- itself. Therefore obtaining the proper visual result is often hit and
- miss.
-
- \l {http://www.andersriggelsen.dk/glblendfunc.php}{Anders Riggelsen's
- online visualizer} may help you find out which arguments and functions
- work for you.
-
- \section3 Blending with Scene3D
-
- When rendering a Qt 3D scene through a Qt Quick scene with the Scene3D
- element you should be aware that you might have to adjust the blending
- arguments of your render state to obtain a sensible rendering. This is
- because of the way Qt 3D first renders a scene into an offscreen texture
- which is then blended in with the rest of the Qt Quick scene.
-
- Sensible values are often Qt3DRender::QBlendEquationArguments::Zero for
- the source alpha and Qt3DRender::QBlendEquationArguments::One for the
- destination alpha.
-
- \section2 Useful Tools
-
- Given the rather limited of troubleshooting given by Qt 3D in its first
- versions it sometimes helps to have tools to capture OpenGL draw calls and
- get more clues about what's happening
-
- \list
- \li \l {https://github.com/apitrace/apitrace}{apitrace}
- \li \l {https://github.com/ValveSoftware/vogl}{vogl}
- \endlist
-
- These tools allow you to gather traces of all the OpenGL calls being made
- by a Qt 3D application. Having a look at a generated trace file may help
- you verify that draw calls are being made, textures correctly uploaded,
- uniforms set with proper values, ...
-
- There are plans for Qt 3D tooling in later releases.
- */
diff --git a/src/doc/src/qt3dscene2d-module.qdoc b/src/doc/src/qt3dscene2d-module.qdoc
deleted file mode 100644
index a389a8ed0..000000000
--- a/src/doc/src/qt3dscene2d-module.qdoc
+++ /dev/null
@@ -1,94 +0,0 @@
-/****************************************************************************
-**
-** Copyright (C) 2017 The Qt Company Ltd and/or its subsidiary(-ies).
-** Contact: https://www.qt.io/licensing/
-**
-** This file is part of the Qt3D module of the Qt Toolkit.
-**
-** $QT_BEGIN_LICENSE:LGPL$
-** 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 The Qt Company. For licensing terms
-** and conditions see https://www.qt.io/terms-conditions. For further
-** information use the contact form at https://www.qt.io/contact-us.
-**
-** GNU Lesser General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU Lesser
-** General Public License version 3 as published by the Free Software
-** Foundation and appearing in the file LICENSE.LGPL3 included in the
-** packaging of this file. Please review the following information to
-** ensure the GNU Lesser General Public License version 3 requirements
-** will be met: https://www.gnu.org/licenses/lgpl-3.0.html.
-**
-** GNU General Public License Usage
-** Alternatively, this file may be used under the terms of the GNU
-** General Public License version 2.0 or (at your option) the GNU General
-** Public license version 3 or any later version approved by the KDE Free
-** Qt Foundation. The licenses are as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL2 and LICENSE.GPL3
-** included in the packaging of this file. Please review the following
-** information to ensure the GNU General Public License requirements will
-** be met: https://www.gnu.org/licenses/gpl-2.0.html and
-** https://www.gnu.org/licenses/gpl-3.0.html.
-**
-** $QT_END_LICENSE$
-**
-****************************************************************************/
-
-/*!
- \module Qt3DScene2D
- \title Qt 3D Scene2D C++ Classes
-
- \brief The Qt 3D Scene2D module provides a way to render Quick2 qml content
- to a Qt 3D texture.
-
- This module is still in tech preview. This means it is unstable, likely to
- change and provided as a convenience only.
-
- \ingroup modules
- \ingroup qt3d-modules
- \qtvariable 3dquickscene2d
-
- \code
- #include <Qt3DQuickScene2D>
- \endcode
-
- To link against the corresponding C++ library, add the following to your qmake project file:
-
- \badcode
- QT += 3dquickscene2d
- \endcode
-
- Classes, types, and functions are declared under the \l [Qt3DScene2D]{Qt3DScene2D} namespace.
-
- \section1 Overview
-
- \section2 Scene2D
-
- \list
- \li Qt3DRender::Quick::QScene2D
- \endlist
-
- \section1 Reference
- \list
- \li \l {Qt 3D Extras C++ Classes}
- \li \l {Qt 3D Examples}
- \endlist
- */
-
-/*!
- \qmlmodule Qt3D.Scene2D 2.9
- \title Qt 3D Scene2D QML Types
- \ingroup qmlmodules
- \ingroup qt3d-qmlmodules
-
- \brief Provides Qt 3D QML types for the scene2d module.
-
- To import and use the module's QML types, use the following statement:
-
- \badcode
- import Qt3D.Scene2D 2.9
- \endcode
-*/