diff options
Diffstat (limited to 'src/doc/src')
| -rw-r--r-- | src/doc/src/externalresources.qdoc | 45 | ||||
| -rw-r--r-- | src/doc/src/qcircularbuffer.qdoc | 1588 | ||||
| -rw-r--r-- | src/doc/src/qt3d-examples.qdoc | 41 | ||||
| -rw-r--r-- | src/doc/src/qt3d-index.qdoc | 111 | ||||
| -rw-r--r-- | src/doc/src/qt3d-module.qdoc | 130 | ||||
| -rw-r--r-- | src/doc/src/qt3d-overview.qdoc | 381 | ||||
| -rw-r--r-- | src/doc/src/qt3dcollision-module.qdoc | 74 | ||||
| -rw-r--r-- | src/doc/src/qt3dinput-module.qdoc | 75 | ||||
| -rw-r--r-- | src/doc/src/qt3dlogic-module.qdoc | 75 | ||||
| -rw-r--r-- | src/doc/src/qt3drender-framegraph.qdoc | 513 | ||||
| -rw-r--r-- | src/doc/src/qt3drender-module.qdoc | 96 |
11 files changed, 3129 insertions, 0 deletions
diff --git a/src/doc/src/externalresources.qdoc b/src/doc/src/externalresources.qdoc new file mode 100644 index 000000000..8ddce9d47 --- /dev/null +++ b/src/doc/src/externalresources.qdoc @@ -0,0 +1,45 @@ +/**************************************************************************** +** +** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \externalpage http://en.wikipedia.org/wiki/Z-buffering + \title early z-fill pass +*/ + +/*! + \externalpage http://www.cs.northwestern.edu/~ago820/SIG98/abstract.html + \title original Gooch paper +*/ diff --git a/src/doc/src/qcircularbuffer.qdoc b/src/doc/src/qcircularbuffer.qdoc new file mode 100644 index 000000000..080eeab98 --- /dev/null +++ b/src/doc/src/qcircularbuffer.qdoc @@ -0,0 +1,1588 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \class Qt3D::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 a Qt3D::QCircularBuffer::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 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 {Qt3D::QCircularBuffer::}{const_iterator}) + and \l {Qt3D::QCircularBuffer::}{iterator}). In practice, these are rarely used, + because you can use indexes into the QCircularBuffer. + + 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 Qt3D::QCircularBuffer::iterator, Qt3D::QCircularBuffer::const_iterator, + QVector, QList, QLinkedList +*/ + +/*! \fn Qt3D::QCircularBuffer::QCircularBuffer() + + Constructs an empty circular buffer with zero capacity. + + \sa resize(), setCapacity() +*/ + +/*! \fn Qt3D::QCircularBuffer::QCircularBuffer(int capacity) + + Constructs an empty circular buffer with an initial capacity of \a capacity + elements. + + \sa resize(), setCapacity() +*/ + +/*! \fn Qt3D::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 Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::~QCircularBuffer() + + Destroys the circular buffer. +*/ + +/*! \fn QCircularBuffer &Qt3D::QCircularBuffer::operator=(const QCircularBuffer<T> &other) + + Assigns \a other to this circular buffer and returns a reference to this + circular buffer. +*/ + +/*! \fn Qt3D::QCircularBuffer::iterator Qt3D::QCircularBuffer::begin() + + Returns an \l{STL-Style iterators}{STL-style iterator} pointing to the first item in + the circular buffer. + + \sa constBegin(), end() +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::QCircularBuffer::begin() const + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::const_iterator Qt3D::QCircularBuffer::end() const + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::push_back(const T &value) + + This function is provided for STL compatibility. It is equivalent + to append(\a value). +*/ + +/*! \fn void Qt3D::QCircularBuffer::push_front(const T &value) + + This function is provided for STL compatibility. It is equivalent + to prepend(\a value). +*/ + +/*! \fn void Qt3D::QCircularBuffer::pop_back() + + This function is provided for STL compatibility. It is equivalent + to erase(end() - 1). +*/ + +/*! \fn void Qt3D::QCircularBuffer::pop_front() + + This function is provided for STL compatibility. It is equivalent + to erase(begin()). +*/ + +/*! \fn bool Qt3D::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 Qt3D::QCircularBuffer::reference Qt3D::QCircularBuffer::front() + + This function is provided for STL compatibility. It is equivalent + to first(). +*/ + +/*! \fn Qt3D::QCircularBuffer::const_reference Qt3D::QCircularBuffer::front() const + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer::reference Qt3D::QCircularBuffer::back() + + This function is provided for STL compatibility. It is equivalent + to last(). +*/ + +/*! \fn Qt3D::QCircularBuffer::const_reference Qt3D::QCircularBuffer::back() const + + \overload +*/ + +/*! \fn int Qt3D::QCircularBuffer::refCount() const + + Returns the number of shallow copies that exist of this circular buffer. +*/ + +/*! \fn Qt3D::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 &Qt3D::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 &Qt3D::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 &Qt3D::QCircularBuffer::operator[](int i) const + + \overload + + Same as at(\a i). +*/ + +/*! \fn int Qt3D::QCircularBuffer::capacity() const + + Returns the maximum number of elements that can be stored in + the circular buffer. + + \sa setCapacity(), size() +*/ + +/*! \fn void Qt3D::QCircularBuffer::clear() + + Removes all elements from the circular buffer so that the size is + zero. The capacity is unchanged. + + \sa isEmpty() +*/ + +/*! \fn bool Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::count() const + + \overload + + Same as size(). +*/ + +/*! \fn Qt3D::QCircularBuffer::array_range Qt3D::QCircularBuffer::data() + + Returns a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::const_array_range Qt3D::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 Qt3D::QCircularBuffer::const_array_range Qt3D::QCircularBuffer::constData() const + + Returns a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::array_range Qt3D::QCircularBuffer::dataOne() + + Returns a Qt3D::QCircularBuffer::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 a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::const_array_range Qt3D::QCircularBuffer::dataOne() const + + \overload + + Unlike data() this function always returns a valid Qt3D::QCircularBuffer::const_array_range + (unless the circular buffer is empty). +*/ + +/*! \fn Qt3D::QCircularBuffer::const_array_range Qt3D::QCircularBuffer::constDataOne() const + + Returns a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::array_range Qt3D::QCircularBuffer::dataTwo() + + Returns a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::const_array_range Qt3D::QCircularBuffer::dataTwo() const + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer::const_array_range Qt3D::QCircularBuffer::constDataTwo() const + + Returns a Qt3D::QCircularBuffer::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 Qt3D::QCircularBuffer::endsWith(const T &value) const + + Returns true if this circular buffer is not empty and its last + item is equal to \a value; otherwise returns false. + + \sa isEmpty(), last(), startsWith() +*/ + +/*! \fn QCircularBuffer<T>& Qt3D::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 &Qt3D::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 &Qt3D::QCircularBuffer::first() const + + \overload +*/ + +/*! \fn int Qt3D::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> Qt3D::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> Qt3D::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 Qt3D::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 Qt3D::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 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 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 Qt3D::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 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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::isEmpty() const + + Returns true if the circular buffer has size 0; otherwise returns false. + + \sa capacity(), resize(), setCapacity(), size() +*/ + +/*! \fn bool Qt3D::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 Qt3D::QCircularBuffer::isLinearised() const + + Returns true if the circular buffer is linearized; otherwise returns 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 a + Qt3D::QCircularBuffer::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 + array_range object describing the values 2-6, and the dataTwo() function + would return an 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 &Qt3D::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 &Qt3D::QCircularBuffer::last() const + + \overload +*/ + +/*! \fn int Qt3D::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 Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::remove(int i) + + Removes the element at index position \a i. + + \sa insert(), replace(), fill() +*/ + +/*! \fn void Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::reserve(int capacity) + + Sets the capacity of the circular buffer to \a capacity. It is a synonym for + setCapacity(). + + \sa setCapacity() +*/ + +/*! \fn void Qt3D::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 Qt3D::QCircularBuffer::setCapacity(int capacity) + + Sets the capacity of the circular buffer to \a capacity. + + \sa reserve(), capacity() +*/ + +/*! \fn int Qt3D::QCircularBuffer::size() const + + Returns the number of items in the circular buffer. + + \sa sizeAvailable(), capacity(), resize() +*/ + +/*! \fn int Qt3D::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 Qt3D::QCircularBuffer::squeeze() + + Releases any unused memory from the circular buffer. It is equivalent + to calling setCapacity(size()). + + \sa setCapacity(), size(), resize(), sizeAvailable() +*/ + +/*! \fn bool Qt3D::QCircularBuffer::startsWith(const T &value) const + + Returns true if the circular buffer is not empty and its first + item is equal to \a value; otherwise returns false. + + \sa isEmpty(), first(), endsWith() +*/ + +/*! \fn QList<T> Qt3D::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> Qt3D::QCircularBuffer::toVector() const + + Returns a QVector object with the data contained in this QCircularBuffer. + + \sa fromVector(), toList() +*/ + +/*! \fn T Qt3D::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 Qt3D::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 Qt3D::operator==(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns true if the circular buffer \a lhs is equal to \a rhs; otherwise + returns 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 Qt3D::operator!=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns true if the circular buffer \a lhs is not equal to \a rhs; otherwise + returns 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 Qt3D::QCircularBuffer<T>& Qt3D::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 Qt3D::QCircularBuffer<T>& Qt3D::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 Qt3D::QCircularBuffer<T>& Qt3D::QCircularBuffer::operator+=(const QVector<T>& other) + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer<T>& Qt3D::QCircularBuffer::operator+=(const QList<T>& other) + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer<T>& Qt3D::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 Qt3D::QCircularBuffer<T>& Qt3D::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 Qt3D::QCircularBuffer<T>& Qt3D::QCircularBuffer::operator<<(const QVector<T>& other) + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer<T>& Qt3D::QCircularBuffer::operator<<(const QList<T>& other) + + \overload +*/ + +/*! \fn Qt3D::QCircularBuffer<T> Qt3D::operator+(const QCircularBuffer<T>& lhs, const QCircularBuffer<T>& rhs) + + 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 Qt3D::QCircularBuffer::operator+=() +*/ + +/*! \fn void Qt3D::swap(QCircularBuffer<T> &lhs, QCircularBuffer<T> &rhs) + + Swaps the contents of the circular buffer \a lhs with the contents of \a rhs. +*/ + +/*! \fn bool Qt3D::operator<(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns 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 Qt3D::operator>(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns true if \a rhs is lexographically less than \a lhs. +*/ + +/*! \fn bool Qt3D::operator>=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns true if \a lhs is lexographically less than or equal to \a rhs. +*/ + +/*! \fn bool Qt3D::operator<=(const QCircularBuffer<T> &lhs, const QCircularBuffer<T> &rhs) + + Returns true if \a lhs is lexographically less than or equal to \a rhs. +*/ + +/*! \typedef Qt3D::QCircularBuffer::Iterator + + Qt-style synonym for Qt3D::QCircularBuffer::iterator. +*/ + +/*! \typedef Qt3D::QCircularBuffer::ConstIterator + + Qt-style synonym for Qt3D::QCircularBuffer::const_iterator. +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_pointer + + Typedef for const T *. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::difference_type + + Typedef for ptrdiff_t. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::pointer + + Typedef for T *. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::reference + + Typedef for T &. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::size_type + + Typedef for int. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::QCircularBuffer::value_type + + Typedef for T. Provided for STL compatibility. +*/ + +/*! \typedef Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::ArrayRange + + Qt-style synonym for Qt3D::QCircularBuffer::array_range. +*/ + +/*! \typedef Qt3D::QCircularBuffer::ConstArrayRange + + Qt-style synonym for Qt3D::QCircularBuffer::const_array_range. +*/ + + +/*! \class Qt3D::QCircularBuffer::iterator + \inmodule Qt3DCore + \brief The Qt3D::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 Qt3D::QCircularBuffer::begin(), Qt3D::QCircularBuffer::end(), + Qt3D::QCircularBuffer::const_iterator +*/ + +/*! \typedef Qt3D::QCircularBuffer::iterator::iterator_category + + A synonym for \e {std::random_access_iterator_tag} indicating + this iterator is a random access iterator. +*/ + +/*! \typedef Qt3D::QCircularBuffer::iterator::difference_type + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::iterator::value_type + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::iterator::pointer + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::iterator::reference + + \internal +*/ + +/*! \fn Qt3D::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 Qt3D::QCircularBuffer::begin() Qt3D::QCircularBuffer::end() +*/ + +/*! \fn Qt3D::QCircularBuffer::iterator::iterator(QCircularBuffer<T> *buffer, int index) + + \internal +*/ + +/*! \fn T &Qt3D::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 *Qt3D::QCircularBuffer::iterator::operator->() const + + Returns a pointer to the current item. + + \sa operator*() +*/ + +/*! \fn T &Qt3D::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 Qt3D::QCircularBuffer::iterator::operator==(const iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::iterator::operator!=(const iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::iterator::operator<(const iterator& other) const + + Returns true if the item pointed to by this iterator occurs before + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::iterator::operator<=(const iterator& other) const + + Returns 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 Qt3D::QCircularBuffer::iterator::operator>(const iterator& other) const + + Returns true if the item pointed to by this iterator occurs after + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::iterator::operator>=(const iterator& other) const + + Returns 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 Qt3D::QCircularBuffer::iterator &Qt3D::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 Qt3D::QCircularBuffer::end() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::iterator &Qt3D::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 Qt3D::QCircularBuffer::begin() leads to undefined results. + + \sa operator++() +*/ + +/*! \fn Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::iterator &Qt3D::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 Qt3D::QCircularBuffer::iterator &Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::QCircularBuffer::iterator Qt3D::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 Qt3D::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 Qt3D::QCircularBuffer::const_iterator + \inmodule Qt3DCore + \brief The Qt3D::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 Qt3D::QCircularBuffer::constBegin(), Qt3D::QCircularBuffer::constEnd(), + Qt3D::QCircularBuffer::iterator +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_iterator::iterator_category + + A synonym for \e {std::random_access_iterator_tag} indicating + this iterator is a random access iterator. +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_iterator::difference_type + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_iterator::value_type + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_iterator::pointer + + \internal +*/ + +/*! \typedef Qt3D::QCircularBuffer::const_iterator::reference + + \internal +*/ + +/*! \fn Qt3D::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 Qt3D::QCircularBuffer::begin() Qt3D::QCircularBuffer::end() +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator::const_iterator(const iterator &other) + + \internal +*/ + +/*! \fn const T &Qt3D::QCircularBuffer::const_iterator::operator*() const + + Returns a const reference to the current item. + + \sa operator->() +*/ + +/*! \fn const T *Qt3D::QCircularBuffer::const_iterator::operator->() const + + Returns a pointer to the current item. + + \sa operator*() +*/ + +/*! \fn const T &Qt3D::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 Qt3D::QCircularBuffer::const_iterator::operator==(const const_iterator &other) const + + Returns true if \a other points to the same item as this + iterator; otherwise returns false. + + \sa operator!=() +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::const_iterator::operator!=(const const_iterator &other) const + + Returns true if \a other points to a different item than this + iterator; otherwise returns false. + + \sa operator==() +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::const_iterator::operator<(const const_iterator& other) const + + Returns true if the item pointed to by this iterator occurs before + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::const_iterator::operator<=(const const_iterator& other) const + + Returns 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 Qt3D::QCircularBuffer::const_iterator::operator>(const const_iterator& other) const + + Returns true if the item pointed to by this iterator occurs after + the item pointed to by the \a other iterator. +*/ + +/*! + \fn bool Qt3D::QCircularBuffer::const_iterator::operator>=(const const_iterator& other) const + + Returns 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 Qt3D::QCircularBuffer::const_iterator &Qt3D::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 Qt3D::QCircularBuffer::constEnd() leads to undefined results. + + \sa operator--() +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::QCircularBuffer::const_iterator &Qt3D::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 Qt3D::QCircularBuffer::constBegin() leads to undefined results. + + \sa operator++() +*/ + +/*! \fn Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::QCircularBuffer::const_iterator &Qt3D::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 Qt3D::QCircularBuffer::const_iterator &Qt3D::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 Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::QCircularBuffer::const_iterator Qt3D::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 Qt3D::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/qt3d-examples.qdoc b/src/doc/src/qt3d-examples.qdoc new file mode 100644 index 000000000..4ba413e50 --- /dev/null +++ b/src/doc/src/qt3d-examples.qdoc @@ -0,0 +1,41 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt3d-examples.html + \ingroup all-examples + \title Qt3D Examples + \brief Examples that demonstrate 2D and 3D rendering using Qt3D. + + The following examples demonstrate 2D and 3D rendering using Qt3D. + + \section1 QML Examples + \annotatedlist qt3d-examples-qml + + \section1 C++ Examples + \annotatedlist qt3d-examples-cpp +*/ diff --git a/src/doc/src/qt3d-index.qdoc b/src/doc/src/qt3d-index.qdoc new file mode 100644 index 000000000..db8785436 --- /dev/null +++ b/src/doc/src/qt3d-index.qdoc @@ -0,0 +1,111 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt3d-index.html + \title Qt 3D + + \e Qt3D provides functionality for near-realtime simulation systems + with support for 2D and 3D rendering in both Qt C++ and Qt Quick + applications. + + The functionality in Qt3D is divided into the following C++ modules: + + \annotatedlist qt3d-modules + + Classes, types and functions are declared under the \l [CPP] {Qt3D} namespace. + + For Qt Quick applications, Qt3D provides the following QML modules: + + \annotatedlist qt3d-qmlmodules + + \section1 Getting Started + + For a C++ application that performs 2D or 3D rendering, collision + detection, and also handle user input, add the following line to its + \l qmake \c .pro file: + + \badcode + QT += 3dcore 3drender 3dinput 3dcollision 3dlogic + \endcode + + To include the definitions of the modules' classes, use the following + directives: + + \badcode + #include <Qt3DCore> + #include <Qt3DRender> + #include <Qt3DInput> + #include <Qt3DCollision> + #include <Qt3DLogic> + \endcode + + A Qt Quick application requires also additional dependencies: + + \badcode + QT += 3dcore 3drenderer 3dinput 3dcollision qml quick 3dquick + \endcode + + \section1 Overview + + The high level design and motivation for Qt3D is described in the \l {Qt3D + Overview}. The Qt3D Renderer aspect offers support for data-driven + configuration as described in \l {Qt3D Renderer Framegraph}. + + \section1 Reference + \list + \li \l {Qt3D Overview} + \li \l {Qt 3D C++ Classes} + \li \l {Qt 3D QML Types} + \li \l {Qt3D Examples} + \endlist + + \section1 Qt3D Platform Support + + In this Technology Preview Qt3D has the following support for platforms: + + \list + \li Microsoft Windows (win32) - Supported + \li Linux X11 - Supported + \li OS X - Supported although there may be some retina scaling issues + \li Android - Supported + \li Embedded Linux - Supported + \li iOS - Not supported yet (coming in Qt 5.6) + \li WinRT - Not supported yet + \li Windows CE - Compiles but not tested + \endlist +*/ diff --git a/src/doc/src/qt3d-module.qdoc b/src/doc/src/qt3d-module.qdoc new file mode 100644 index 000000000..bc9042b46 --- /dev/null +++ b/src/doc/src/qt3d-module.qdoc @@ -0,0 +1,130 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \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. + + The Qt 3D module provides the foundations and core types used for near-realtime + simulations built on the Qt 3D framework. + + \section1 Namespaces + \annotatedlist qt3d-namespaces + + \section1 Classes + + \section2 Qt 3D Core Module + \generatelist {classesbymodule Qt3DCore} + + \section2 Qt 3D Collision Module + \generatelist {classesbymodule Qt3DCollision} + + \section2 Qt 3D Input Module + \generatelist {classesbymodule Qt3DInput} + + \section2 Qt 3D Logic Module + \generatelist {classesbymodule Qt3DLogic} + + \section2 Qt 3D Render Module + \generatelist {classesbymodule Qt3DRender} +*/ + +/*! + \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 + \title Qt 3D QML Types + \ingroup qmlmodules + \ingroup qt3d-qmlmodules + + \brief Provides core Qt 3D QML types. + + To import and use the module's QML types, use the following statement: + + \badcode + import Qt3D.Core 2.0 + \endcode + + For collision detection, renderer, and input-related QML types, use the + following import statements: + + \badcode + import Qt3D.Collision 2.0 + import Qt3D.Render 2.0 + import Qt3D.Input 2.0 + import Qt3D.Logic 2.0 + \endcode + + \section1 QML Types + + \section2 Qt 3D Core Module + \generatelist {qmltypesbymodule Qt3D} + + \section2 Qt 3D Collision Module + \generatelist {qmltypesbymodule Qt3D.Collision} + + \section2 Qt 3D Input Module + \generatelist {qmltypesbymodule Qt3D.Input} + + \section2 Qt 3D Logic Module + \generatelist {qmltypesbymodule Qt3D.Logic} + + \section2 Qt 3D Render Module + \generatelist {qmltypesbymodule Qt3D.Render} + \noautolist +*/ diff --git a/src/doc/src/qt3d-overview.qdoc b/src/doc/src/qt3d-overview.qdoc new file mode 100644 index 000000000..133f6fd14 --- /dev/null +++ b/src/doc/src/qt3d-overview.qdoc @@ -0,0 +1,381 @@ +/**************************************************************************** +** +** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt3d-overview.html + \title Qt3D Overview + + \brief Qt3D provides C++ and QML APIs to incorporate 3D content into Qt + applications. + + Qt3D provides a fully configurable renderer that enables developers to + quickly implement any rendering pipeline that they need. Further, Qt3D + provides a generic framework for near-realtime simulations beyond rendering. + + Qt3D is cleanly separated into a core and any number of \e aspects that can + implement any functionality they wish. The aspects interact with + \e components and \e entities to provide some slice of functionality. + Examples of aspects include physics, audio, collision, artificial + intelligence (AI), and path finding. + + \section1 Basic 3D Features + + Qt3D is a 3D framework that enables the drawing of 3D shapes and moving + them around, as well as moving the camera. It supports the following basic + features: + + \list + \li 2D and 3D rendering for C++ and Qt Quick applications + \li Meshes + \li \l {Materials} + \li \l {Shaders} + \li \l {Shadow Mapping}{Shadow mapping} + \li Ambient occlusion + \li High dynamic range + \li Deferred rendering + \li Multitexturing + \li \l {Instanced Rendering}{Instanced rendering} + \li \l {Uniform Buffer Objects} + \endlist + + \section2 Materials + + Qt3D has a robust and very flexible material system that allows multiple + levels of customization. It caters for different rendering approaches on + different platforms or OpenGL versions, enables multiple rendering passes + with different state sets, provides mechanisms for overriding of parameters + at different levels, and allows easy switching of shaders. All this from C++ + or using QML property bindings. + + The properties of a \l Material type can easily be mapped through to uniform + variables in a GLSL shader program that is itself specified in the + referenced effect property. + + For examples of using materials, see the \l {Qt3D: Materials C++ Example} + and \l {Qt3D: Materials QML Example}. + + \section2 Shaders + + Qt3D supports all of the OpenGL programmable rendering pipeline stages: + vertex, tessellation control, tessellation evaluation, geometry, and + fragment shaders. Compute shaders are planned for a future release. + + For examples of using shaders, see the Simple Shaders QML Example, + \l {Qt3D: Tessellation Modes QML Example}, + \l {Qt3D: Shadow Map QML Example}, \l{Qt3D: Wireframe QML Example}, and + \l {Qt3D: Wave QML Example}. + + \section2 Shadow Mapping + + Shadows are not directly supported by OpenGL, but there are countless + techniques that can be employed to generate them. Shadow mapping is simple + to use for generating good-looking shadows, while having a very small + performance cost. + + Shadow mapping is typically implemented using a two pass rendering. In the + first pass, the shadow information is generated. In the second pass, the + scene is generated using a particular rendering technique, while at the + same time using the information gathered in the first pass to draw the + shadows. + + The idea behind shadow mapping is that only the closest fragments to the + light are lit. Fragments \e behind other fragments are occluded, and + therefore in shadow. + + Therefore, in the first pass, the scene is drawn from the point of view of + the light. The information that is stored is simply the distance of the + closest fragment in this \e {light space}. In OpenGL terms, this corresponds + to having a Framebuffer Object, or FBO, with a depth texture attached to it. + In fact, the \e {distance from the eye} is the definition of the depth, + and the default depth testing done by OpenGL will actually store only the + depth for the closest fragment. + + A color texture attachment is not even needed, because there is no need to + shade fragments, only to calculate their depth. + + The following image displays a scene with a self-shadowed plane and trefoil + knot: + + \image shadowmapping-qt3d.png + + The following image shows an exaggerated shadow map texture of the scene: + + \image shadowmapping-depth.png + + The image indicates the depth stored when rendering the scene from the light + point of view. Darker colors represent a shallow depth (that is, closer to + the camera). In this scene, the light is placed somewhere above the objects + in the scene, on the right side with respect to the main camera (compare + this with the first screenshot). This matches with the fact that the toy + plane is closer to the camera than the other objects. + + Once the shadow map has been generated, the second rendering pass is done. + In this second pass, rendering is done using the normal scene's camera. Any + effect can be used here, such as Phong shading. It is important that the + shadow map algorithm is applied in the fragment shader. That is, the + fragment that is closest to the light is drawn lit, whereas the other + fragments are drawn in shadow. + + The shadow map generated in the first pass provides the necessary + information about the distance of fragments to light. It then suffices to + remap the fragment in light space, thereby calculating its depth from the + light point of view, as well as where its coordinates are on the shadow map + texture. The shadow map texture can then be sampled at the given coordinates + and the fragment's depth can be compared with the result of the sampling. If + the fragment is further away, then it is in shadow; otherwise it is lit. + + For example code, see the \l {Qt3D: Shadow Map QML Example}. + + \section2 Instanced Rendering + + \e Instancing is a way of getting the GPU to draw many copies (instances) of + a base object that varies in some way for each copy. Often, in position, + orientation, color, material properties, scale, and so on. Qt3D provides an + API similar to the Qt Quick \l Repeater element. In this case, the delegate + is the base object and the model provides the per-instance data. So whereas + an entity with a \l Mesh component attached eventually gets transformed into + a call to glDrawElements, an entity with a instanced component will be + translated into a call to glDrawElementsInstanced. + + Instanced rendering is planned for a future release. + + \section2 Uniform Buffer Objects + + A Uniform Buffer Object (UBO) can be bound to OpenGL shader programs to make + large amounts of data readily available. Typical use cases for UBOs are for + sets of material or lighting parameters. + + \section1 Configurable Renderer + + To combine support for both C++ and QML APIs with having a fully + configurable renderer, the concept of a \e framegraph was introduced. While + a \e scenegraph is a data-driven description of \e what to render, a \l + {Qt3D Renderer Framegraph}{framegraph} is a data-driven description of \e + how to render it. + + A framegraph enables developers to choose between a simple forward renderer, + including a z-fill pass, or using a deferred renderer for example. It also + gives them control over when to render any transparent objects, and so on. + Since this is all configured purely from data, it is very easy to modify even + dynamically at runtime without touching any C++ code. It is possible to + extend Qt3D by creating your own framegraphs that implement custom + rendering algorithms. + + \section1 3D Extensions + + Beyond the essentials of displaying 3D content on the screen, Qt3D is + extensible and flexible enough to act as a host for following types of + extensions related to the 3D objects: + + \list + \li Physics simulation + \li Collision detection + \li 3D positional audio + \li Rigid body, skeletal, and morph target animation + \li Path finding and other AI + \li Picking + \li Particles + \li Object spawning + \endlist + + \section1 Performance + + Qt3D is designed to perform well and scale up with the number of available + CPU cores, because modern hardware improves performance by increasing the + numbers of cores rather than base clock speed. Using multiple cores works + well, because many tasks are independent of each other. For example, the + operations performed by a path finding module do not overlap strongly with + the tasks performed by a renderer, except maybe when rendering debug + information or statistics. + + \section1 Qt3D Architecture + + The main use cases of Qt3D are simulating objects in near-realtime and + rendering the state of those objects onto the screen. The Space Invaders + example contains the following objects: + + \image Space-invaders.jpg + + \list + \li The player's ground cannon + \li The ground + \li The defensive blocks + \li The enemy space invader ships + \li The enemy boss flying saucer + \li The bullets shot by the enemies and the player + \endlist + + In a traditional C++ design, these types of object would typically be + implemented as classes arranged in some kind of inheritance tree. Various + branches in the inheritance tree might add additional functionality to the + root class for features such as: + + \list + \li Accepts user input + \li Plays a sound + \li Is animated + \li Collides with other objects + \li Is drawn on screen + \endlist + + The types in the Space Invaders example can be classified against these + features. However, designing an elegant inheritance tree for even such a + simple example is not easy. + + This approach and other variations on inheritance present a number of + problems: + + \list + \li Deep and wide inheritance hierarchies are difficult to understand, + maintain and extend. + \li The inheritance taxonomy is set in stone at compile time. + \li Each level in the class inheritance tree can only classify upon a + single criteria or axis. + \li Shared functionality tends to \e {bubble up} the class hierarchy + over time. + \li It is impossible to predict what the developers will want to do. + \endlist + + Extending deep and wide inheritance trees usually requires understanding, + and agreeing with, the taxonomy used by the original author. Therefore, + Qt3D places focus on aggregation instead of inheritance as the means of + imparting functionality onto an instance of an object. Specifically, Qt3D + implements an Entity Component System (ECS). + + \section2 Using an ECS + + In an ECS, an entity represents a simulated object but by itself is devoid + of any specific behavior or characteristics. Additional behavior can be + grafted onto an entity by having the entity aggregate one or more + components. Each component is a vertical slice of behavior of an object + type. + + In the Space Invaders example, the ground is an entity with an attached + component that tells the system that the entity needs rendering and what + kind of rendering it needs. An enemy space invader ship is another entity + with attached components that cause the ship to be rendered, but also enable + it to emit sounds, be collided with, be animated, and be controlled by a + simple AI. + + The player's ground cannon entity has mostly similar components to the enemy + space invader ship, except that it does not have the AI component. In its + place, the cannon has an input component to enable the player to move it + around and to fire bullets. + + \section2 ECS Backend + + \image ecs-2.png + + The backend of Qt3D implements the \e system part of the ECS paradigm in + the form of \e aspects. An aspect implements the particular vertical slice + of the functionality provided to entities by a combination of one or more + of their aggregated components. + + For example, the renderer aspect looks for entities that have mesh, + material, and optionally transformation components. If the renderer aspect + finds such an entity, it knows how to take that data and draw something nice + from it. If an entity does not have those components, the renderer aspect + ignores it. + + Qt3D builds custom entities by aggregating components that provide + additional capabilities. The Qt3D engine uses aspects to process and + update entities with specific components. + + For example, a physics aspect looks for entities that have some kind of + collision volume component and another component that specifies other + properties needed by such simulations like mass, coefficient of friction, + and so on. An entity that emits sound has a component that specifies it is + a sound emitter, as well as specifying when and which sounds to play. + + Because ECS uses aggregation rather than inheritance, it is possible to + dynamically change how an object behaves at runtime simply by adding or + removing components. + + For example, to enable a player to suddenly run through walls after a + power-up, that entity's collision volume component can be removed + temporarily, until the power-up times out. There is no need to create a + special one-off subclass for \c PlayerWhoRunsThroughWalls. + + \section2 Qt3D ECS Implementation + + Qt3D implements ECS as a simple class hierarchy. The Qt3D base class is + Qt3D::QNode, which is a subclass of QObject. Qt3D::QNode adds to QObject the ability to + automatically communicate property changes to aspects and an ID that is + unique throughout an application. The aspects exist in additional threads + and Qt3D::QNode simplifies the data transfer between the user-facing objects and + the aspects. + + Typically, subclasses of Qt3D::QNode provide additional supporting data that is + referenced by components. For example, the QShaderProgram class specifies + the GLSL code to be used when rendering a set of entities. + + \image ecs-1.png + + Components in Qt3D are implemented by subclassing Qt3D::QComponent and adding the + data necessary for the corresponding aspect to do its work. For example, the + mesh component is used by the renderer aspect to retrieve the per-vertex + data that should be sent down the OpenGL pipeline. + + Finally, Qt3D::QEntity is simply an object that can aggregate zero or more + Qt3D::QComponent instances. + + \section1 Extending Qt3D + + Adding functionality to Qt3D, either as part of Qt or specific to your + own applications to benefit from the multi-threaded back-end consists of the + following tasks: + + \list + \li Identify and implement any necessary components and supporting data. + \li Register the components with the QML engine (only if you use the QML + API). + \li Subclass QAbstractAspect and implement the subsystem functionality. + \endlist + + \section1 Qt3D Task-Based Engine + + In Qt3D, aspects are asked in each frame for a set of \e tasks to execute + along with the \e dependencies between them. The tasks are distributed + across all the configured cores by a scheduler to improve performance. + + \section1 Qt3D's Aspects + + By default Qt3D provides the Qt3DRenderer and Qt3DInput aspects. The + components and other supporting classes provided by these aspects are + discussed in the documentation for those modules. + + Additional aspects providing more capabilities will be added in future + versions of Qt3D. diff --git a/src/doc/src/qt3dcollision-module.qdoc b/src/doc/src/qt3dcollision-module.qdoc new file mode 100644 index 000000000..6c7151128 --- /dev/null +++ b/src/doc/src/qt3dcollision-module.qdoc @@ -0,0 +1,74 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module Qt3DCollision + \title Qt3D Collision C++ Classes + \brief The Qt3D Collision module enables collision detection. + \ingroup modules + \ingroup qt3d-modules + \qtvariable 3dcollision + + To use classes from this module, add this directive into the C++ files: + + \code + #include <Qt3DCollision> + \endcode + + To link against the corresponding C++ libraries, add the following to your qmake project file: + + \badcode + QT += 3dcollision + \endcode + +*/ + +/*! + \namespace Qt3DCollision + \inmodule Qt3DCollision + \ingroup qt3d-namespaces + + \brief Contains classes that enable collision detection. +*/ + +/*! + \qmlmodule Qt3D.Collision 2.0 + \title Qt3D Collision 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.Collision 2.0 + \endcode + + \section1 QML Types +*/ + diff --git a/src/doc/src/qt3dinput-module.qdoc b/src/doc/src/qt3dinput-module.qdoc new file mode 100644 index 000000000..c46d577dd --- /dev/null +++ b/src/doc/src/qt3dinput-module.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module Qt3DInput + \title Qt3D Input C++ Classes + \brief The Qt3D 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 Qt3D Input QML Types + \ingroup qmlmodules + \ingroup qt3d-qmlmodules + + \brief Provides QML types for Qt3D 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 new file mode 100644 index 000000000..f43eb44e2 --- /dev/null +++ b/src/doc/src/qt3dlogic-module.qdoc @@ -0,0 +1,75 @@ +/**************************************************************************** +** +** Copyright (C) 2015 The Qt Company Ltd. +** Contact: http://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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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: http://www.gnu.org/copyleft/fdl.html. +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module Qt3DLogic + \title Qt3D Logic C++ Classes + \brief The Qt3D 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 Qt3D 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 new file mode 100644 index 000000000..52a4e2227 --- /dev/null +++ b/src/doc/src/qt3drender-framegraph.qdoc @@ -0,0 +1,513 @@ +/**************************************************************************** +** +** Copyright (C) 2015 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \page qt3drender-framegraph.html + \title Qt3D Render Framegraph + + \brief A framegraph is the data structure that controls how a scene is + rendered. + + The Qt3D 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 Qt3D 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 {qtquick-visualcanvas-scenegraph}{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, Qt3D 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 Qt3D::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. + + // TODO: Add list of framegraph node types + + 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 Qt3D renderer. + + \section2 Setting the Framegraph + + The FrameGraph tree should be assigned to the activeFrameGraph property of + a QFrameGraph component, itself being a component of the root entity in the + Qt3D 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: FrameGraph { + activeFrameGraph: ... // FrameGraph tree + } + } + \endcode + + \note activeFrameGraph is the default property of the FrameGraph component + in QML. + + \badcode + Entity { + id: sceneRoot + components: FrameGraph { + ... // FrameGraph tree + } + } + \endcode + + \section2 How the Framegraph Is Used + + \list + \li The Qt3D 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 + Qt3D, 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 + Qt3D 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 + + ClearBuffer { + buffers: ClearBuffer.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 + + ClearBuffer { + buffers: ClearBuffer.ColorDepthBuffer + } + } + } + \endcode + + \badcode + CameraSelector { + Viewport { + rect: Qt.rect(0.0, 0.0, 1.0, 1.0) + + ClearBuffer { + buffers: ClearBuffer.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 + + ClearBuffer { + buffers: ClearBuffer.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 ClearBuffer 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, Qt3D 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. + + Qt3D 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 + + ClearBuffer { + buffers: ClearBuffer.ColorDepthBuffer + + RenderPassFilter { + id: geometryPass + includes: Annotation { name: "pass"; value: "geometry" } + + CameraSelector { + id: sceneCameraSelector + } + } + } + } + } + + LayerFilter { + layers: "screenQuad" + + ClearBuffer { + buffers: ClearBuffer.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 Qt3D'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 Qt3D 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 Qt3D provides out of the box. +*/ diff --git a/src/doc/src/qt3drender-module.qdoc b/src/doc/src/qt3drender-module.qdoc new file mode 100644 index 000000000..aa4dac44f --- /dev/null +++ b/src/doc/src/qt3drender-module.qdoc @@ -0,0 +1,96 @@ +/**************************************************************************** +** +** Copyright (C) 2014 Klaralvdalens Datakonsult AB (KDAB). +** Contact: http://www.qt-project.org/legal +** +** This file is part of the Qt3D module of the Qt Toolkit. +** +** $QT_BEGIN_LICENSE:LGPL3$ +** 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 http://www.qt.io/terms-conditions. For further +** information use the contact form at http://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.LGPLv3 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.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 later as published by the Free +** Software Foundation and appearing in the file LICENSE.GPL included in +** the packaging of this file. Please review the following information to +** ensure the GNU General Public License version 2.0 requirements will be +** met: http://www.gnu.org/licenses/gpl-2.0.html. +** +** $QT_END_LICENSE$ +** +****************************************************************************/ + +/*! + \module Qt3DRender + \title Qt3D Render C++ Classes + \brief The Qt3D Render module contains functionality to support 2D and 3D rendering using Qt3D. + + \ingroup modules + \ingroup qt3d-modules + \qtvariable 3drender + + The Qt3D Render module provides an aspect, components, and other supporting types necessary + to implement 2D and 3D rendering as part of the Qt3D 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 Qt3D Render aspect offers support for data-driven configuration as described + in \l {Qt3D Render Framegraph}. + + \section1 Reference + \list + \li \l {Qt3D Render C++ Classes} + \li \l {Qt3D Examples} + \endlist +*/ + +/*! + \namespace Qt3DRender + \inmodule Qt3DRender + \ingroup qt3d-namespaces + + \brief Contains classes that enable 2D and 3D rendering. +*/ + +/*! + \qmlmodule Qt3D.Render 2.0 + \title Qt3D Render QML Types + \ingroup qmlmodules + \ingroup qt3d-qmlmodules + + \brief Provides Qt3D QML types for rendering. + + To import and use the module's QML types, use the following statement: + + \badcode + import Qt3D.Render 2.0 + \endcode +*/ |