diff options
Diffstat (limited to 'src/gui/math3d/qvectornd.cpp')
| -rw-r--r-- | src/gui/math3d/qvectornd.cpp | 426 |
1 files changed, 208 insertions, 218 deletions
diff --git a/src/gui/math3d/qvectornd.cpp b/src/gui/math3d/qvectornd.cpp index 7362694987..dcd7bdbcf8 100644 --- a/src/gui/math3d/qvectornd.cpp +++ b/src/gui/math3d/qvectornd.cpp @@ -1,42 +1,6 @@ -/**************************************************************************** -** -** Copyright (C) 2016 The Qt Company Ltd. -** Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> -** Contact: https://www.qt.io/licensing/ -** -** This file is part of the QtGui 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$ -** -****************************************************************************/ +// Copyright (C) 2016 The Qt Company Ltd. +// Copyright (C) 2020 Klarälvdalens Datakonsult AB, a KDAB Group company, info@kdab.com, author Giuseppe D'Angelo <giuseppe.dangelo@kdab.com> +// SPDX-License-Identifier: LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR GPL-3.0-only #include "qvectornd.h" #include <QtCore/qdatastream.h> @@ -56,6 +20,10 @@ QT_BEGIN_NAMESPACE \ingroup painting-3D \inmodule QtGui + Vectors are one of the main building blocks of 2D representation and + drawing. They consist of two finite floating-point coordinates, + traditionally called x and y. + The QVector2D class can also be used to represent vertices in 2D space. We therefore do not need to provide a separate vertex class. @@ -80,6 +48,7 @@ QT_BEGIN_NAMESPACE \fn QVector2D::QVector2D(float xpos, float ypos) Constructs a vector with coordinates (\a xpos, \a ypos). + Both coordinates must be finite. */ /*! @@ -146,7 +115,7 @@ QT_BEGIN_NAMESPACE /*! \fn void QVector2D::setX(float x) - Sets the x coordinate of this point to the given \a x coordinate. + Sets the x coordinate of this point to the given finite \a x coordinate. \sa x(), setY() */ @@ -154,7 +123,7 @@ QT_BEGIN_NAMESPACE /*! \fn void QVector2D::setY(float y) - Sets the y coordinate of this point to the given \a y coordinate. + Sets the y coordinate of this point to the given finite \a y coordinate. \sa y(), setX() */ @@ -200,7 +169,7 @@ QT_BEGIN_NAMESPACE Returns the normalized unit vector form of this vector. - If this vector is null, then a null vector is returned. If the length + If this vector is null, then a null vector is returned. If the length of the vector is very close to 1, then the vector will be returned as-is. Otherwise the normalized form of the vector of length 1 will be returned. @@ -210,7 +179,7 @@ QT_BEGIN_NAMESPACE /*! \fn void QVector2D::normalize() - Normalizes the currect vector in place. Nothing happens if this + Normalizes the current vector in place. Nothing happens if this vector is a null vector or the length of the vector is very close to 1. \sa length(), normalized() @@ -260,24 +229,29 @@ QT_BEGIN_NAMESPACE /*! \fn QVector2D &QVector2D::operator*=(float factor) - Multiplies this vector's coordinates by the given \a factor, and + Multiplies this vector's coordinates by the given finite \a factor and returns a reference to this vector. - \sa operator/=() + \sa operator/=(), operator*() */ /*! \fn QVector2D &QVector2D::operator*=(QVector2D vector) - Multiplies the components of this vector by the corresponding - components in \a vector. + Multiplies each component of this vector by the corresponding component of + \a vector and returns a reference to this vector. + + \note This is not a cross product of this vector with \a vector. (Its + components add up to the dot product of this vector and \a vector.) + + \sa operator/=(), operator*() */ /*! \fn QVector2D &QVector2D::operator/=(float divisor) - Divides this vector's coordinates by the given \a divisor, and - returns a reference to this vector. + Divides this vector's coordinates by the given \a divisor and returns a + reference to this vector. The \a divisor must not be either zero or NaN. \sa operator*=() */ @@ -286,10 +260,12 @@ QT_BEGIN_NAMESPACE \fn QVector2D &QVector2D::operator/=(QVector2D vector) \since 5.5 - Divides the components of this vector by the corresponding - components in \a vector. + Divides each component of this vector by the corresponding component of \a + vector and returns a reference to this vector. - \sa operator*=() + The \a vector must have no component that is either zero or NaN. + + \sa operator*=(), operator/() */ /*! @@ -312,9 +288,8 @@ QT_BEGIN_NAMESPACE This operator uses an exact floating-point comparison. */ -/*! - \fn const QVector2D operator+(QVector2D v1, QVector2D v2) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator+(QVector2D v1, QVector2D v2) Returns a QVector2D object that is the sum of the given vectors, \a v1 and \a v2; each component is added separately. @@ -322,9 +297,8 @@ QT_BEGIN_NAMESPACE \sa QVector2D::operator+=() */ -/*! - \fn const QVector2D operator-(QVector2D v1, QVector2D v2) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator-(QVector2D v1, QVector2D v2) Returns a QVector2D object that is formed by subtracting \a v2 from \a v1; each component is subtracted separately. @@ -332,67 +306,69 @@ QT_BEGIN_NAMESPACE \sa QVector2D::operator-=() */ -/*! - \fn const QVector2D operator*(float factor, QVector2D vector) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator*(float factor, QVector2D vector) - Returns a copy of the given \a vector, multiplied by the given \a factor. + Returns a copy of the given \a vector, multiplied by the given finite \a factor. \sa QVector2D::operator*=() */ -/*! - \fn const QVector2D operator*(QVector2D vector, float factor) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator*(QVector2D vector, float factor) - Returns a copy of the given \a vector, multiplied by the given \a factor. + Returns a copy of the given \a vector, multiplied by the given finite \a factor. \sa QVector2D::operator*=() */ -/*! - \fn const QVector2D operator*(QVector2D v1, QVector2D v2) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator*(QVector2D v1, QVector2D v2) + + Returns the QVector2D object formed by multiplying each component of \a v1 + by the corresponding component of \a v2. + + \note This is not a cross product of \a v1 and \a v2 in any sense. + (Its components add up to the dot product of \a v1 and \a v2.) - Multiplies the components of \a v1 by the corresponding - components in \a v2. + \sa QVector2D::operator*=() */ -/*! - \fn const QVector2D operator-(QVector2D vector) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator-(QVector2D vector) \overload - Returns a QVector2D object that is formed by changing the sign of - the components of the given \a vector. + Returns a QVector2D object that is formed by changing the sign of each + component of the given \a vector. Equivalent to \c {QVector2D(0,0) - vector}. */ -/*! - \fn const QVector2D operator/(QVector2D vector, float divisor) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator/(QVector2D vector, float divisor) - Returns the QVector2D object formed by dividing all three components of - the given \a vector by the given \a divisor. + Returns the QVector2D object formed by dividing each component of the given + \a vector by the given \a divisor. + + The \a divisor must not be either zero or NaN. \sa QVector2D::operator/=() */ -/*! - \fn const QVector2D operator/(QVector2D vector, QVector2D divisor) - \relates QVector2D +/*! //! friend + \fn const QVector2D QVector2D::operator/(QVector2D vector, QVector2D divisor) \since 5.5 - Returns the QVector2D object formed by dividing components of the given - \a vector by a respective components of the given \a divisor. + Returns the QVector2D object formed by dividing each component of the given + \a vector by the corresponding component of the given \a divisor. + + The \a divisor must have no component that is either zero or NaN. \sa QVector2D::operator/=() */ -/*! - \fn bool qFuzzyCompare(QVector2D v1, QVector2D v2) - \relates QVector2D +/*! //! friend + \fn bool QVector2D::qFuzzyCompare(QVector2D v1, QVector2D v2) Returns \c true if \a v1 and \a v2 are equal, allowing for a small fuzziness factor for floating-point comparisons; false otherwise. @@ -426,6 +402,7 @@ bool qFuzzyCompare(QVector2D v1, QVector2D v2) noexcept \fn QPoint QVector2D::toPoint() const Returns the QPoint form of this 2D vector. + Each coordinate is rounded to the nearest integer. \sa toPointF(), toVector3D() */ @@ -490,6 +467,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) float x, y; stream >> x; stream >> y; + Q_ASSERT(qIsFinite(x) && qIsFinite(y)); vector.setX(x); vector.setY(y); return stream; @@ -511,8 +489,8 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) \inmodule QtGui Vectors are one of the main building blocks of 3D representation and - drawing. They consist of three coordinates, traditionally called - x, y, and z. + drawing. They consist of three finite floating-point coordinates, + traditionally called x, y, and z. The QVector3D class can also be used to represent vertices in 3D space. We therefore do not need to provide a separate vertex class. @@ -538,6 +516,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) \fn QVector3D::QVector3D(float xpos, float ypos, float zpos) Constructs a vector with coordinates (\a xpos, \a ypos, \a zpos). + All parameters must be finite. */ /*! @@ -559,17 +538,17 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D::QVector3D(QVector2D vector) - Constructs a 3D vector from the specified 2D \a vector. The z + Constructs a 3D vector from the specified 2D \a vector. The z coordinate is set to zero. \sa toVector2D() */ /*! - QVector3D::QVector3D(QVector2D vector, float zpos) + \fn QVector3D::QVector3D(QVector2D vector, float zpos) - Constructs a 3D vector from the specified 2D \a vector. The z - coordinate is set to \a zpos. + Constructs a 3D vector from the specified 2D \a vector. The z + coordinate is set to \a zpos, which must be finite. \sa toVector2D() */ @@ -580,7 +559,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D::QVector3D(QVector4D vector) - Constructs a 3D vector from the specified 4D \a vector. The w + Constructs a 3D vector from the specified 4D \a vector. The w coordinate is dropped. \sa toVector4D() @@ -622,7 +601,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn void QVector3D::setX(float x) - Sets the x coordinate of this point to the given \a x coordinate. + Sets the x coordinate of this point to the given finite \a x coordinate. \sa x(), setY(), setZ() */ @@ -630,7 +609,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn void QVector3D::setY(float y) - Sets the y coordinate of this point to the given \a y coordinate. + Sets the y coordinate of this point to the given finite \a y coordinate. \sa y(), setX(), setZ() */ @@ -638,7 +617,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn void QVector3D::setZ(float z) - Sets the z coordinate of this point to the given \a z coordinate. + Sets the z coordinate of this point to the given finite \a z coordinate. \sa z(), setX(), setY() */ @@ -667,7 +646,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) Returns the normalized unit vector form of this vector. - If this vector is null, then a null vector is returned. If the length + If this vector is null, then a null vector is returned. If the length of the vector is very close to 1, then the vector will be returned as-is. Otherwise the normalized form of the vector of length 1 will be returned. @@ -677,7 +656,7 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn void QVector3D::normalize() - Normalizes the currect vector in place. Nothing happens if this + Normalizes the current vector in place. Nothing happens if this vector is a null vector or the length of the vector is very close to 1. \sa length(), normalized() @@ -704,42 +683,45 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D &QVector3D::operator*=(float factor) - Multiplies this vector's coordinates by the given \a factor, and + Multiplies this vector's coordinates by the given finite \a factor and returns a reference to this vector. - \sa operator/=() + \sa operator/=(), operator*() */ /*! \fn QVector3D &QVector3D::operator*=(QVector3D vector) \overload - Multiplies the components of this vector by the corresponding - components in \a vector. + Multiplies each component of this vector by the corresponding component in + \a vector and returns a reference to this vector. - Note: this is not the same as the crossProduct() of this - vector and \a vector. + Note: this is not the same as the crossProduct() of this vector and + \a vector. (Its components add up to the dot product of this vector and + \a vector.) - \sa crossProduct() + \sa crossProduct(), operator/=(), operator*() */ /*! \fn QVector3D &QVector3D::operator/=(float divisor) - Divides this vector's coordinates by the given \a divisor, and - returns a reference to this vector. + Divides this vector's coordinates by the given \a divisor, and returns a + reference to this vector. The \a divisor must not be either zero or NaN. - \sa operator*=() + \sa operator*=(), operator/() */ /*! \fn QVector3D &QVector3D::operator/=(QVector3D vector) \since 5.5 - Divides the components of this vector by the corresponding - components in \a vector. + Divides each component of this vector by the corresponding component in \a + vector and returns a reference to this vector. - \sa operator*=() + The \a vector must have no component that is either zero or NaN. + + \sa operator*=(), operator/() */ /*! @@ -751,8 +733,9 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D QVector3D::crossProduct(QVector3D v1, QVector3D v2) - Returns the cross-product of vectors \a v1 and \a v2, which corresponds - to the normal vector of a plane defined by \a v1 and \a v2. + Returns the cross-product of vectors \a v1 and \a v2, which is normal to the + plane spanned by \a v1 and \a v2. It will be zero if the two vectors are + parallel. \sa normal() */ @@ -760,8 +743,8 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D QVector3D::normal(QVector3D v1, QVector3D v2) - Returns the normal vector of a plane defined by vectors \a v1 and \a v2, - normalized to be a unit vector. + Returns the unit normal vector of a plane spanned by vectors \a v1 and \a + v2, which must not be parallel to one another. Use crossProduct() to compute the cross-product of \a v1 and \a v2 if you do not need the result to be normalized to a unit vector. @@ -772,8 +755,8 @@ QDataStream &operator>>(QDataStream &stream, QVector2D &vector) /*! \fn QVector3D QVector3D::normal(QVector3D v1, QVector3D v2, QVector3D v3) - Returns the normal vector of a plane defined by vectors - \a v2 - \a v1 and \a v3 - \a v1, normalized to be a unit vector. + Returns the unit normal vector of a plane spanned by vectors \a v2 - \a v1 + and \a v3 - \a v1, which must not be parallel to one another. Use crossProduct() to compute the cross-product of \a v2 - \a v1 and \a v3 - \a v1 if you do not need the result to be normalized to a @@ -860,7 +843,7 @@ QVector3D QVector3D::unproject(const QMatrix4x4 &modelView, const QMatrix4x4 &pr \fn float QVector3D::distanceToPlane(QVector3D plane, QVector3D normal) const Returns the distance from this vertex to a plane defined by - the vertex \a plane and a \a normal unit vector. The \a normal + the vertex \a plane and a \a normal unit vector. The \a normal parameter is assumed to have been normalized to a unit vector. The return value will be negative if the vertex is below the plane, @@ -910,9 +893,8 @@ QVector3D QVector3D::unproject(const QMatrix4x4 &modelView, const QMatrix4x4 &pr This operator uses an exact floating-point comparison. */ -/*! - \fn const QVector3D operator+(QVector3D v1, QVector3D v2) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator+(QVector3D v1, QVector3D v2) Returns a QVector3D object that is the sum of the given vectors, \a v1 and \a v2; each component is added separately. @@ -920,9 +902,8 @@ QVector3D QVector3D::unproject(const QMatrix4x4 &modelView, const QMatrix4x4 &pr \sa QVector3D::operator+=() */ -/*! - \fn const QVector3D operator-(QVector3D v1, QVector3D v2) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator-(QVector3D v1, QVector3D v2) Returns a QVector3D object that is formed by subtracting \a v2 from \a v1; each component is subtracted separately. @@ -930,70 +911,69 @@ QVector3D QVector3D::unproject(const QMatrix4x4 &modelView, const QMatrix4x4 &pr \sa QVector3D::operator-=() */ -/*! - \fn const QVector3D operator*(float factor, QVector3D vector) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator*(float factor, QVector3D vector) - Returns a copy of the given \a vector, multiplied by the given \a factor. + Returns a copy of the given \a vector, multiplied by the given finite \a factor. \sa QVector3D::operator*=() */ -/*! - \fn const QVector3D operator*(QVector3D vector, float factor) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator*(QVector3D vector, float factor) - Returns a copy of the given \a vector, multiplied by the given \a factor. + Returns a copy of the given \a vector, multiplied by the given finite \a factor. \sa QVector3D::operator*=() */ -/*! - \fn const QVector3D operator*(QVector3D v1, QVector3D v2) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator*(QVector3D v1, QVector3D v2) - Multiplies the components of \a v1 by the corresponding components in \a v2. + Returns the QVector3D object formed by multiplying each component of \a v1 + by the corresponding component of \a v2. - Note: this is not the same as the crossProduct() of \a v1 and \a v2. + \note This is not the same as the crossProduct() of \a v1 and \a v2. + (Its components add up to the dot product of \a v1 and \a v2.) \sa QVector3D::crossProduct() */ -/*! - \fn const QVector3D operator-(QVector3D vector) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator-(QVector3D vector) \overload - Returns a QVector3D object that is formed by changing the sign of - all three components of the given \a vector. + Returns a QVector3D object that is formed by changing the sign of each + component of the given \a vector. Equivalent to \c {QVector3D(0,0,0) - vector}. */ -/*! - \fn const QVector3D operator/(QVector3D vector, float divisor) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator/(QVector3D vector, float divisor) + + Returns the QVector3D object formed by dividing each component of the given + \a vector by the given \a divisor. - Returns the QVector3D object formed by dividing all three components of - the given \a vector by the given \a divisor. + The \a divisor must not be either zero or NaN. \sa QVector3D::operator/=() */ -/*! - \fn const QVector3D operator/(QVector3D vector, QVector3D divisor) - \relates QVector3D +/*! //! friend + \fn const QVector3D QVector3D::operator/(QVector3D vector, QVector3D divisor) \since 5.5 - Returns the QVector3D object formed by dividing components of the given - \a vector by a respective components of the given \a divisor. + Returns the QVector3D object formed by dividing each component of the given + \a vector by the corresponding component of the given \a divisor. + + The \a divisor must have no component that is either zero or NaN. \sa QVector3D::operator/=() */ -/*! - \fn bool qFuzzyCompare(QVector3D v1, QVector3D v2) - \relates QVector3D +/*! //! friend + \fn bool QVector3D::qFuzzyCompare(QVector3D v1, QVector3D v2) Returns \c true if \a v1 and \a v2 are equal, allowing for a small fuzziness factor for floating-point comparisons; false otherwise. @@ -1032,8 +1012,8 @@ bool qFuzzyCompare(QVector3D v1, QVector3D v2) noexcept /*! \fn QPoint QVector3D::toPoint() const - Returns the QPoint form of this 3D vector. The z coordinate - is dropped. + Returns the QPoint form of this 3D vector. The z coordinate is dropped. The + x and y coordinates are rounded to nearest integers. \sa toPointF(), toVector2D() */ @@ -1118,6 +1098,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) stream >> x; stream >> y; stream >> z; + Q_ASSERT(qIsFinite(x) && qIsFinite(y) && qIsFinite(z)); vector.setX(x); vector.setY(y); vector.setZ(z); @@ -1139,6 +1120,10 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) \ingroup painting-3D \inmodule QtGui + Vectors are one of the main building blocks of 4D affine representations of + 3D space. They consist of four finite floating-point coordinates, + traditionally called x, y, z and w. + The QVector4D class can also be used to represent vertices in 4D space. We therefore do not need to provide a separate vertex class. @@ -1163,6 +1148,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) \fn QVector4D::QVector4D(float xpos, float ypos, float zpos, float wpos) Constructs a vector with coordinates (\a xpos, \a ypos, \a zpos, \a wpos). + All parameters must be finite. */ /*! @@ -1184,7 +1170,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn QVector4D::QVector4D(QVector2D vector) - Constructs a 4D vector from the specified 2D \a vector. The z + Constructs a 4D vector from the specified 2D \a vector. The z and w coordinates are set to zero. \sa toVector2D() @@ -1193,8 +1179,9 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn QVector4D::QVector4D(QVector2D vector, float zpos, float wpos) - Constructs a 4D vector from the specified 2D \a vector. The z - and w coordinates are set to \a zpos and \a wpos respectively. + Constructs a 4D vector from the specified 2D \a vector. The z + and w coordinates are set to \a zpos and \a wpos respectively, + each of which must be finite. \sa toVector2D() */ @@ -1206,17 +1193,17 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn QVector4D::QVector4D(QVector3D vector) - Constructs a 4D vector from the specified 3D \a vector. The w + Constructs a 4D vector from the specified 3D \a vector. The w coordinate is set to zero. \sa toVector3D() */ /*! - \fn QVector4D::QVector4D(QVector3D vector) + \fn QVector4D::QVector4D(QVector3D vector, float wpos) - Constructs a 4D vector from the specified 3D \a vector. The w - coordinate is set to \a wpos. + Constructs a 4D vector from the specified 3D \a vector. The w + coordinate is set to \a wpos, which must be finite. \sa toVector3D() */ @@ -1265,7 +1252,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn void QVector4D::setX(float x) - Sets the x coordinate of this point to the given \a x coordinate. + Sets the x coordinate of this point to the given finite \a x coordinate. \sa x(), setY(), setZ(), setW() */ @@ -1273,7 +1260,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn void QVector4D::setY(float y) - Sets the y coordinate of this point to the given \a y coordinate. + Sets the y coordinate of this point to the given finite \a y coordinate. \sa y(), setX(), setZ(), setW() */ @@ -1281,7 +1268,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn void QVector4D::setZ(float z) - Sets the z coordinate of this point to the given \a z coordinate. + Sets the z coordinate of this point to the given finite \a z coordinate. \sa z(), setX(), setY(), setW() */ @@ -1289,7 +1276,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn void QVector4D::setW(float w) - Sets the w coordinate of this point to the given \a w coordinate. + Sets the w coordinate of this point to the given finite \a w coordinate. \sa w(), setX(), setY(), setZ() */ @@ -1335,7 +1322,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) Returns the normalized unit vector form of this vector. - If this vector is null, then a null vector is returned. If the length + If this vector is null, then a null vector is returned. If the length of the vector is very close to 1, then the vector will be returned as-is. Otherwise the normalized form of the vector of length 1 will be returned. @@ -1345,7 +1332,7 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn void QVector4D::normalize() - Normalizes the currect vector in place. Nothing happens if this + Normalizes the current vector in place. Nothing happens if this vector is a null vector or the length of the vector is very close to 1. \sa length(), normalized() @@ -1373,24 +1360,26 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) /*! \fn QVector4D &QVector4D::operator*=(float factor) - Multiplies this vector's coordinates by the given \a factor, and + Multiplies this vector's coordinates by the given finite \a factor, and returns a reference to this vector. - \sa operator/=() + \sa operator/=(), operator*() */ /*! \fn QVector4D &QVector4D::operator*=(QVector4D vector) - Multiplies the components of this vector by the corresponding - components in \a vector. + Multiplies each component of this vector by the corresponding component of + \a vector and returns a reference to this vector. + + \sa operator/=(), operator*() */ /*! \fn QVector4D &QVector4D::operator/=(float divisor) - Divides this vector's coordinates by the given \a divisor, and - returns a reference to this vector. + Divides this vector's coordinates by the given \a divisor, and returns a + reference to this vector. The \a divisor must not be either zero or NaN. \sa operator*=() */ @@ -1399,10 +1388,12 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) \fn QVector4D &QVector4D::operator/=(QVector4D vector) \since 5.5 - Divides the components of this vector by the corresponding - components in \a vector. + Divides each component of this vector by the corresponding component of \a + vector and returns a reference to this vector. - \sa operator*=() + The \a vector must have no component that is either zero or NaN. + + \sa operator*=(), operator/() */ /*! @@ -1425,9 +1416,8 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) This operator uses an exact floating-point comparison. */ -/*! - \fn const QVector4D operator+(QVector4D v1, QVector4D v2) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator+(QVector4D v1, QVector4D v2) Returns a QVector4D object that is the sum of the given vectors, \a v1 and \a v2; each component is added separately. @@ -1435,9 +1425,8 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) \sa QVector4D::operator+=() */ -/*! - \fn const QVector4D operator-(QVector4D v1, QVector4D v2) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator-(QVector4D v1, QVector4D v2) Returns a QVector4D object that is formed by subtracting \a v2 from \a v1; each component is subtracted separately. @@ -1445,37 +1434,36 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) \sa QVector4D::operator-=() */ -/*! - \fn const QVector4D operator*(float factor, QVector4D vector) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator*(float factor, QVector4D vector) Returns a copy of the given \a vector, multiplied by the given \a factor. \sa QVector4D::operator*=() */ -/*! - \fn const QVector4D operator*(QVector4D vector, float factor) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator*(QVector4D vector, float factor) Returns a copy of the given \a vector, multiplied by the given \a factor. \sa QVector4D::operator*=() */ -/*! - \fn const QVector4D operator*(QVector4D v1, QVector4D v2) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator*(QVector4D v1, QVector4D v2) - Returns the vector consisting of the multiplication of the - components from \a v1 and \a v2. + Returns the QVector4D object formed by multiplying each component of \a v1 + by the corresponding component of \a v2. + + \note This is not a cross product of \a v1 and \a v2 in any sense. + (Its components add up to the dot product of \a v1 and \a v2.) \sa QVector4D::operator*=() */ -/*! - \fn const QVector4D operator-(QVector4D vector) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator-(QVector4D vector) \overload Returns a QVector4D object that is formed by changing the sign of @@ -1484,30 +1472,31 @@ QDataStream &operator>>(QDataStream &stream, QVector3D &vector) Equivalent to \c {QVector4D(0,0,0,0) - vector}. */ -/*! - \fn const QVector4D operator/(QVector4D vector, float divisor) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator/(QVector4D vector, float divisor) - Returns the QVector4D object formed by dividing all four components of - the given \a vector by the given \a divisor. + Returns the QVector4D object formed by dividing each component of the given + \a vector by the given \a divisor. + + The \a divisor must not be either zero or NaN. \sa QVector4D::operator/=() */ -/*! - \fn const QVector4D operator/(QVector4D vector, QVector4D divisor) - \relates QVector4D +/*! //! friend + \fn const QVector4D QVector4D::operator/(QVector4D vector, QVector4D divisor) \since 5.5 - Returns the QVector4D object formed by dividing components of the given - \a vector by a respective components of the given \a divisor. + Returns the QVector4D object formed by dividing each component of the given + \a vector by the corresponding component of the given \a divisor. + + The \a divisor must have no component that is either zero or NaN. \sa QVector4D::operator/=() */ -/*! - \fn bool qFuzzyCompare(QVector4D v1, QVector4D v2) - \relates QVector4D +/*! //! friend + \fn bool QVector4D::qFuzzyCompare(QVector4D v1, QVector4D v2) Returns \c true if \a v1 and \a v2 are equal, allowing for a small fuzziness factor for floating-point comparisons; false otherwise. @@ -1556,7 +1545,7 @@ bool qFuzzyCompare(QVector4D v1, QVector4D v2) noexcept \fn QVector3D QVector4D::toVector3DAffine() const Returns the 3D vector form of this 4D vector, dividing the x, y, and - z coordinates by the w coordinate. Returns a null vector if w is zero. + z coordinates by the w coordinate. Returns a null vector if w is zero. \sa toVector3D(), toVector2DAffine(), toPoint() */ @@ -1566,8 +1555,8 @@ bool qFuzzyCompare(QVector4D v1, QVector4D v2) noexcept /*! \fn QPoint QVector4D::toPoint() const - Returns the QPoint form of this 4D vector. The z and w coordinates - are dropped. + Returns the QPoint form of this 4D vector. The z and w coordinates are + dropped. The x and y coordinates are rounded to nearest integers. \sa toPointF(), toVector2D() */ @@ -1638,6 +1627,7 @@ QDataStream &operator>>(QDataStream &stream, QVector4D &vector) stream >> y; stream >> z; stream >> w; + Q_ASSERT(qIsFinite(x) && qIsFinite(y) && qIsFinite(z) && qIsFinite(w)); vector.setX(x); vector.setY(y); vector.setZ(z); |