QRay3D Class

(Qt3DCore::QRay3D)

The QRay3D class defines a directional line in 3D space extending through an origin point. More...

Header: #include <QRay3D>
qmake: QT += 3dcore
Since: Qt 5.5

Public Functions

QRay3D()
QRay3D(const QVector3D &origin, const QVector3D &direction = QVector3D( 0.0f, 0.0f, 1.0f ), float distance = 1.0f)
~QRay3D()
bool contains(const QVector3D &point) const
bool contains(const QRay3D &ray) const
QVector3D direction() const
float distance() const
float distance(const QVector3D &point) const
QVector3D origin() const
QVector3D point(float t) const
QVector3D project(const QVector3D &vector) const
float projectedDistance(const QVector3D &point) const
void setDirection(const QVector3D &direction)
void setDistance(float distance)
void setOrigin(const QVector3D &value)
QRay3D &transform(const QMatrix4x4 &matrix)
QRay3D transformed(const QMatrix4x4 &matrix) const
bool operator!=(const QRay3D &other) const
bool operator==(const QRay3D &other) const
bool qFuzzyCompare(const Qt3DCore::QRay3D &ray1, const Qt3DCore::QRay3D &ray2)
QDataStream &operator>>(QDataStream &stream, Qt3DCore::QRay3D &ray)

Detailed Description

The QRay3D class defines a directional line in 3D space extending through an origin point.

A ray is defined by the origin() point and the direction() vector. Rays are infinite in length, extending out from origin() in both directions. If the direction() is zero length, then the behavior of the class is undefined.

A ray can be thought of as a one-dimensional co-ordinate system. If the co-ordinate is t then the origin() point is at t = 0, the point origin() + direction() is at t = 1, and the point origin() - direction() is at t = -1. The point() method can be used to obtain the position of a point within this one-dimensional co-ordinate system. The projectedDistance() method can be used to convert a point into a value in this one-dimensional co-ordinate system.

Member Function Documentation

QRay3D::QRay3D()

Construct a default ray with an origin() of (0, 0, 0), a direction() of (0, 0, 1) and a distance of 1.

QRay3D::QRay3D(const QVector3D &origin, const QVector3D &direction = QVector3D( 0.0f, 0.0f, 1.0f ), float distance = 1.0f)

Construct a ray given its defining origin, direction and distance. The direction does not need to be normalized.

To construct a ray that passes through two points, use the following:

QRay3D thruAB(pointA, pointB - pointA);

QRay3D::~QRay3D()

Destroys the instance of QRay3D.

bool QRay3D::contains(const QVector3D &point) const

Returns true if point lies on this ray; false otherwise.

bool QRay3D::contains(const QRay3D &ray) const

Returns true if ray lies on this ray; false otherwise. If true, this implies that the two rays are actually the same, but with different origin() points or an inverted direction().

QVector3D QRay3D::direction() const

Returns the direction vector of this ray. The default value is (0, 0, 1).

See also setDirection() and origin().

float QRay3D::distance() const

See also setDistance().

float QRay3D::distance(const QVector3D &point) const

Returns the minimum distance from this ray to point, or equivalently the length of a line perpendicular to this ray which passes through point. If point is on the ray, then this function will return zero.

See also point().

QVector3D QRay3D::origin() const

Returns the origin of this ray. The default value is (0, 0, 0).

See also setOrigin() and direction().

QVector3D QRay3D::point(float t) const

Returns the point on the ray defined by moving t units along the ray in the direction of the direction() vector. Note that t may be negative in which case the point returned will lie behind the origin() point with respect to the direction() vector.

The units for t are defined by direction(). The return value is precisely origin() + t * direction().

See also projectedDistance() and distance().

QVector3D QRay3D::project(const QVector3D &vector) const

Returns the projection of vector onto this ray. In the following diagram, the dotted line is the ray, and V is the vector. The return value will be the vector V':

[Missing image qray3d-project.png]

See also projectedDistance().

float QRay3D::projectedDistance(const QVector3D &point) const

Returns the number of direction() units along the ray from origin() to point. Essentially, this function computes the value t, where point = origin() + t * direction(). If point is not on the ray, then the closest point that is on the ray will be used instead.

If the return value is positive, then point lies in front of the origin() with respect to the direction() vector. If the return value is negative, then point lies behind the origin() with respect to the direction() vector.

See also point() and project().

void QRay3D::setDirection(const QVector3D &direction)

Sets the direction vector of this ray to direction.

See also direction() and setOrigin().

void QRay3D::setDistance(float distance)

See also distance().

void QRay3D::setOrigin(const QVector3D &value)

Sets the origin point of this ray to value.

See also origin() and setDirection().

QRay3D &QRay3D::transform(const QMatrix4x4 &matrix)

Transforms this ray using matrix, replacing origin() and direction() with the transformed versions.

See also transformed().

QRay3D QRay3D::transformed(const QMatrix4x4 &matrix) const

Returns a new ray that is formed by transforming origin() and direction() using matrix.

See also transform().

bool QRay3D::operator!=(const QRay3D &other) const

Returns true if this ray is not the same as other; false otherwise.

See also operator==().

bool QRay3D::operator==(const QRay3D &other) const

Returns true if this ray is the same as other; false otherwise.

See also operator!=().

Related Non-Members

bool qFuzzyCompare(const Qt3DCore::QRay3D &ray1, const Qt3DCore::QRay3D &ray2)

Returns true if ray1 and ray2 are almost equal; false otherwise.

QDataStream &Qt3DCore::operator>>(QDataStream &stream, Qt3DCore::QRay3D &ray)

Reads a 3D ray from the given stream into the given ray and returns a reference to the stream.

© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.