From bb09fa7b64b288a68edc61c52ea8467f96eb3924 Mon Sep 17 00:00:00 2001 From: Topi Reinio Date: Tue, 17 Apr 2018 12:21:10 +0200 Subject: Revert "Doc: Divide documentation into submodules" This reverts commit c8964b8f1cf56718a189b0f57bad446cec30a8b8. QDoc now supports documentation-specific custom module headers and include headers that allow us to keep using a single documentation project that covers multiple modules. Change-Id: I84706a7149097a6b03f0f266e55d6f712a6c773e Reviewed-by: Martin Smith --- src/doc/src/levelofdetailloader.qdoc | 57 ++ src/doc/src/qcircularbuffer.qdoc | 1590 ++++++++++++++++++++++++++++++++ src/doc/src/qmlextracontrollers.qdoc | 170 ++++ src/doc/src/qmlextramaterials.qdoc | 568 ++++++++++++ src/doc/src/qt3d-module.qdoc | 35 +- src/doc/src/qt3danimation-module.qdoc | 232 +++++ src/doc/src/qt3dextras-module.qdoc | 132 +++ src/doc/src/qt3dinput-module.qdoc | 78 ++ src/doc/src/qt3dlogic-module.qdoc | 80 ++ src/doc/src/qt3drender-framegraph.qdoc | 518 +++++++++++ src/doc/src/qt3drender-geometry.qdoc | 154 ++++ src/doc/src/qt3drender-module.qdoc | 103 +++ src/doc/src/qt3drender-protips.qdoc | 130 +++ src/doc/src/qt3dscene2d-module.qdoc | 97 ++ 14 files changed, 3938 insertions(+), 6 deletions(-) create mode 100644 src/doc/src/levelofdetailloader.qdoc create mode 100644 src/doc/src/qcircularbuffer.qdoc create mode 100644 src/doc/src/qmlextracontrollers.qdoc create mode 100644 src/doc/src/qmlextramaterials.qdoc create mode 100644 src/doc/src/qt3danimation-module.qdoc create mode 100644 src/doc/src/qt3dextras-module.qdoc create mode 100644 src/doc/src/qt3dinput-module.qdoc create mode 100644 src/doc/src/qt3dlogic-module.qdoc create mode 100644 src/doc/src/qt3drender-framegraph.qdoc create mode 100644 src/doc/src/qt3drender-geometry.qdoc create mode 100644 src/doc/src/qt3drender-module.qdoc create mode 100644 src/doc/src/qt3drender-protips.qdoc create mode 100644 src/doc/src/qt3dscene2d-module.qdoc (limited to 'src/doc/src') diff --git a/src/doc/src/levelofdetailloader.qdoc b/src/doc/src/levelofdetailloader.qdoc new file mode 100644 index 000000000..6294e4735 --- /dev/null +++ b/src/doc/src/levelofdetailloader.qdoc @@ -0,0 +1,57 @@ +/**************************************************************************** +** +** 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 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 new file mode 100644 index 000000000..e313a7375 --- /dev/null +++ b/src/doc/src/qcircularbuffer.qdoc @@ -0,0 +1,1590 @@ +/**************************************************************************** +** +** 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\ is one of Qt's generic \l{container classes}. It + stores its items in adjacent memory locations and provides fast + index-based access. + + QCircularBuffer\ provides similar functionality as QVector\ and QList\, + but behaves differently when adding items to a full QCircularBuffer. Whereas + QVector\ and QList\ will both grow to accommodate the new items, + QCircularBuffer\ will overwrite the oldest items. This provides circular + behavior to the container, and also means that it can maintain a flat memory + profile. + + QCircularBuffer\ 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\ or QList\. + Appending and prepending items to a QCircularBuffer\ is an O(1) operation. + + As with QVector\, items in QCircularBuffer\ 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\ 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 &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 &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& 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 Qt3DCore::QCircularBuffer::fromList(const QList& 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 Qt3DCore::QCircularBuffer::fromVector(const QVector& 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 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 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 &lhs, const QCircularBuffer &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 &lhs, const QCircularBuffer &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& 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& Qt3DCore::QCircularBuffer::operator+=(const QCircularBuffer& 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& Qt3DCore::QCircularBuffer::operator+=(const QVector& other) + + \overload +*/ + +/* \fn Qt3DCore::QCircularBuffer& Qt3DCore::QCircularBuffer::operator+=(const QList& other) + + \overload +*/ + +/* \fn Qt3DCore::QCircularBuffer& 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& Qt3DCore::QCircularBuffer::operator<<(const QCircularBuffer& 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& Qt3DCore::QCircularBuffer::operator<<(const QVector& other) + + \overload +*/ + +/* \fn Qt3DCore::QCircularBuffer& Qt3DCore::QCircularBuffer::operator<<(const QList& other) + + \overload +*/ + +/* \fn Qt3DCore::QCircularBuffer Qt3DCore::operator+(const QCircularBuffer& lhs, const QCircularBuffer& 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 &lhs, QCircularBuffer &rhs) + + Swaps the contents of the circular buffer \a lhs with the contents of \a rhs. +*/ + +/* \fn bool Qt3DCore::operator<(const QCircularBuffer &lhs, const QCircularBuffer &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 &lhs, const QCircularBuffer &rhs) + + Returns \c true if \a rhs is lexographically less than \a lhs. +*/ + +/* \fn bool Qt3DCore::operator>=(const QCircularBuffer &lhs, const QCircularBuffer &rhs) + + Returns \c true if \a lhs is lexographically less than or equal to \a rhs. +*/ + +/* \fn bool Qt3DCore::operator<=(const QCircularBuffer &lhs, const QCircularBuffer &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. 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. 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 *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 new file mode 100644 index 000000000..737d0f823 --- /dev/null +++ b/src/doc/src/qmlextracontrollers.qdoc @@ -0,0 +1,170 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 000000000..48f1a2326 --- /dev/null +++ b/src/doc/src/qmlextramaterials.qdoc @@ -0,0 +1,568 @@ +/**************************************************************************** +** +** 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 cb08a60c0..103d84ff4 100644 --- a/src/doc/src/qt3d-module.qdoc +++ b/src/doc/src/qt3d-module.qdoc @@ -37,6 +37,19 @@ ** ****************************************************************************/ +/*! + \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 @@ -74,28 +87,38 @@ */ /*! - \page qt3d-qml.html + \namespace Qt3DCore + \inmodule Qt3DCore + \ingroup qt3d-namespaces + + \brief Contains classes that are the foundation for Qt 3D simulation + framework, as well as classes that provide the ability to render using the + Qt 3D framework. +*/ + +/*! + \qmlmodule Qt3D.Core 2.0 \title Qt 3D QML Types \brief QML Types for the Qt 3D module. \since 5.7 + \ingroup qmlmodules + \ingroup qt3d-qmlmodules - The Qt 3D core QML types are imported with + To import and use the module's QML types, use the following statement: \badcode import Qt3D.Core 2.0 \endcode - Other modules import functionality for collision detection, rendering, input, - and animation. The complete list of Qt 3D import statements: + For collision detection, renderer, and input-related QML types, use the + following 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 new file mode 100644 index 000000000..631e449e2 --- /dev/null +++ b/src/doc/src/qt3danimation-module.qdoc @@ -0,0 +1,232 @@ +/**************************************************************************** +** +** 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 + \preliminary + + \keyword Qt 3D Animation + \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 development but is available as a technology preview. + This means it is unstable, likely to change and provided as a convenience only. + + \ingroup modules + \ingroup qt3d-modules-preliminary + \qtvariable 3danimation + + \code + #include + \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 + \preliminary + + \ingroup qmlmodules + \ingroup qt3d-qmlmodules-preliminary + + \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 new file mode 100644 index 000000000..7aa042160 --- /dev/null +++ b/src/doc/src/qt3dextras-module.qdoc @@ -0,0 +1,132 @@ +/**************************************************************************** +** +** 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 + \keyword Qt 3D Extras + \preliminary + + \brief The Qt 3D Extras module provides a set of prebuilt elements to help + you get started with Qt 3D. + + This module is still in development but is available as a technology preview. + This means it is unstable, likely to change and provided as a convenience only. + + \ingroup modules + \ingroup qt3d-modules-preliminary + \qtvariable 3dextras + + \code + #include + \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 + \preliminary + + \ingroup qmlmodules + \ingroup qt3d-qmlmodules-preliminary + + \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 new file mode 100644 index 000000000..0fbe0aef1 --- /dev/null +++ b/src/doc/src/qt3dinput-module.qdoc @@ -0,0 +1,78 @@ +/**************************************************************************** +** +** 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. + \since 5.7 + + \ingroup modules + \ingroup qt3d-modules + \qtvariable 3dinput + + To use classes from this module, add this directive into the C++ files: + + \code + #include + \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 + \since 5.7 + + \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 new file mode 100644 index 000000000..8994b8bcd --- /dev/null +++ b/src/doc/src/qt3dlogic-module.qdoc @@ -0,0 +1,80 @@ +/**************************************************************************** +** +** 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 + \keyword Qt 3D Logic + \since 5.7 + + \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 + \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 + \since 5.7 + + \ingroup qmlmodules + \ingroup qt3d-qmlmodules + + \brief Provides QML types to synchronize frames with the 3D backend. + + To import and use the module's QML types, use the following statement: + + \badcode + import Qt3D.Logic 2.0 + \endcode + + \section1 QML Types +*/ + diff --git a/src/doc/src/qt3drender-framegraph.qdoc b/src/doc/src/qt3drender-framegraph.qdoc new file mode 100644 index 000000000..44b1cbe89 --- /dev/null +++ b/src/doc/src/qt3drender-framegraph.qdoc @@ -0,0 +1,518 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 000000000..03e84b1d7 --- /dev/null +++ b/src/doc/src/qt3drender-geometry.qdoc @@ -0,0 +1,154 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 000000000..fabdd4220 --- /dev/null +++ b/src/doc/src/qt3drender-module.qdoc @@ -0,0 +1,103 @@ +/**************************************************************************** +** +** 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. + \since 5.7 + + \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 + \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 + \since 5.7 + + \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 new file mode 100644 index 000000000..c78f3d598 --- /dev/null +++ b/src/doc/src/qt3drender-protips.qdoc @@ -0,0 +1,130 @@ +/**************************************************************************** +** +** 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 new file mode 100644 index 000000000..400b8b19f --- /dev/null +++ b/src/doc/src/qt3dscene2d-module.qdoc @@ -0,0 +1,97 @@ +/**************************************************************************** +** +** 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 + \keyword Qt 3D Scene2D + \preliminary + + \brief The Qt 3D Scene2D module provides a way to render Quick2 qml content + to a Qt 3D texture. + + This module is still in development but is available as a technology preview. + This means it is unstable, likely to change and provided as a convenience only. + + \ingroup modules + \ingroup qt3d-modules-preliminary + \qtvariable 3dquickscene2d + + \code + #include + \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 + \preliminary + \title Qt 3D Scene2D QML Types + \ingroup qmlmodules + \ingroup qt3d-qmlmodules-preliminary + + \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 +*/ -- cgit v1.2.3