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