QRay3D Class

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

 Header: #include 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 ), floatdistance = 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).

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.

QVector3D QRay3D::origin() const

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

QVector3D QRay3D::point(floatt) 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().

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]

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.

void QRay3D::setDirection(const QVector3D &direction)

Sets the direction vector of this ray to direction.

void QRay3D::setOrigin(const QVector3D &value)

Sets the origin point of this ray to value.

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

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

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

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

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

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

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

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