Open 3D Engine EMotionFX Gem API Reference 23.10.0
O3DE is an open-source, fully-featured, high-fidelity, modular 3D engine for building games and simulations, available to every industry.
MCore::Ray Class Reference

#include <Ray.h>

Public Member Functions

MCORE_INLINE Ray ()
 
MCORE_INLINE Ray (const AZ::Vector3 &org, const AZ::Vector3 &endPoint)
 
MCORE_INLINE Ray (const AZ::Vector3 &org, const AZ::Vector3 &endPoint, const AZ::Vector3 &dir)
 
MCORE_INLINE void Set (const AZ::Vector3 &org, const AZ::Vector3 &endPoint)
 
MCORE_INLINE void SetOrigin (const AZ::Vector3 &org)
 
MCORE_INLINE void SetDest (const AZ::Vector3 &dest)
 
MCORE_INLINE const AZ::Vector3 & GetOrigin () const
 
MCORE_INLINE const AZ::Vector3 & GetDest () const
 
MCORE_INLINE const AZ::Vector3 & GetDirection () const
 
bool Intersects (const BoundingSphere &s, AZ::Vector3 *intersectA=nullptr, AZ::Vector3 *intersectB=nullptr) const
 
bool Intersects (const PlaneEq &p, AZ::Vector3 *intersect=nullptr) const
 
bool Intersects (const AZ::Vector3 &p1, const AZ::Vector3 &p2, const AZ::Vector3 &p3, AZ::Vector3 *intersect=nullptr, float *baryU=nullptr, float *baryV=nullptr) const
 
bool Intersects (const AABB &b, AZ::Vector3 *intersectA=nullptr, AZ::Vector3 *intersectB=nullptr) const
 
MCORE_INLINE float Length () const
 

Detailed Description

The Ray template/class. A ray is normally an infinite line, starting at a given point (the origin) and heading into a given direction. However, this template does not represent an infinite line, but a finite line, since that will be a lot more useful. This means we have an origin, which is the starting point and a destination, which is the end point. This automatically gives us a direction vector too. So basically we now have a finite ray, which is just a 3D line. We can use rays mainly to perform intersection tests. This class provides you with methods to calculate interection information between the ray and bounding spheres, axis aligned bounding boxes, triangles and planes. More intersection tests might be added in a later stage. Or they have already been added, but this documentation should be updated :) Example fields where rays are (often) used are: collision and hit detection, raytracing images, global illumination, lightmap generation, pathtracing, real-time volumetric effects, lensflares, etc.

Constructor & Destructor Documentation

◆ Ray() [1/3]

MCORE_INLINE MCore::Ray::Ray ( )
inline

Default constructor. Does NOT initialize any members. So this would not be a valid ray.

◆ Ray() [2/3]

MCORE_INLINE MCore::Ray::Ray ( const AZ::Vector3 &  org,
const AZ::Vector3 &  endPoint 
)
inline

Constructor which sets the start and end point of the ray.

Parameters
orgThe origin of the ray.
endPointThe end (destination) point of the ray.

◆ Ray() [3/3]

MCORE_INLINE MCore::Ray::Ray ( const AZ::Vector3 &  org,
const AZ::Vector3 &  endPoint,
const AZ::Vector3 &  dir 
)
inline

Constructor which sets the origin, destination point and direction.

Parameters
orgThe origin of the ray, so where it starts.
endPointThe destination point of the ray, so where it should end.
dirThe normalized direction vector of the ray, which should be (endPoint - startPoint).Normalize()

Member Function Documentation

◆ GetDest()

MCORE_INLINE const AZ::Vector3 & MCore::Ray::GetDest ( ) const
inline

Get the destination of the ray.

Returns
The destination point of the ray, so where it ends.

◆ GetDirection()

MCORE_INLINE const AZ::Vector3 & MCore::Ray::GetDirection ( ) const
inline

Get the direction of the ray.

Returns
The normalized direction vector of the ray, so the direction its heading to.

◆ GetOrigin()

MCORE_INLINE const AZ::Vector3 & MCore::Ray::GetOrigin ( ) const
inline

Get the origin of the ray.

Returns
The origin of the ray, so where it starts.

◆ Intersects() [1/4]

bool MCore::Ray::Intersects ( const AABB b,
AZ::Vector3 *  intersectA = nullptr,
AZ::Vector3 *  intersectB = nullptr 
) const

Perform a ray/AABB (Axis Aligned Bounding Box) intersection test.

Parameters
bThe box to test with.
intersectAIf not nullptr, the closest intersection point will be stored in this vector, in case of an intersection.
intersectBIf not nullptr, the farthest intersection point will be stored in this vector, in case of an intersection.
Returns
Returns true when an intersection occured, otherwise false. If there is no intersection, 'intersectA' and 'intersectB' won't be modified.

◆ Intersects() [2/4]

bool MCore::Ray::Intersects ( const AZ::Vector3 &  p1,
const AZ::Vector3 &  p2,
const AZ::Vector3 &  p3,
AZ::Vector3 *  intersect = nullptr,
float *  baryU = nullptr,
float *  baryV = nullptr 
) const

Perform a ray/triangle intersection test.

Parameters
p1The first point of the triangle.
p2The second point of the triangle.
p3The third point of the triangle.
intersectIf not nullptr, the intersection point will be stored in here, in case of an intersection.
baryUIf not nullptr, the 'u' barycentric coordinate will be stored in here.
baryVIf not nullptr, the 'v' barycentric coordinate will be stored in here.
Returns
Returns true in case of an intersection, otherwise false. If there is no intersection, 'intersect', 'baryU' and 'baryV' will not be modified. You can calculate the uv or normal or whatsoever at the intersection point by using the baryU and baryV values.

The calculation goes like:

valueAtIntersectionPoint = (1-u-v)*A + u*B + v*C;

Where u and v are the values written in baryU and baryV and A, B and C are the three 'attributes' on the 3 points of the triangle. For example the three vertex normals or uv coordinates or colors. Where A is the attribute linked with 'p1', B the attribute linked with 'p2' and C the attribute linked with 'p3'.

To make it easy for you, we created a function caled BarycentricInterpolate() which takes the required parameters and returns the attribute value at the given barycentric coordinates for you. The usage would now be:

valueAtIntersectionPoint = BarycentricInterpolate<Vector3>(u, v, A, B, C);

Where A, B and C could be the vertex normals of the triangle for example. You can easily also calculate the intersection point yourself by using the u and v, by doing this:

intersectionPoint = BarycentricInterpolate<Vector3>(u, v, p1, p2, p3);

See also
BarycentricInterpolate

◆ Intersects() [3/4]

bool MCore::Ray::Intersects ( const BoundingSphere s,
AZ::Vector3 *  intersectA = nullptr,
AZ::Vector3 *  intersectB = nullptr 
) const

Perform a ray/sphere intersection test.

Parameters
sThe bounding sphere to test with.
intersectAIf not nullptr, the closest intersection point will be stored in this vector, in case of an intersection.
intersectBIf not nullptr, the farthest intersection point will be stored in this vector, in case of an intersection.
Returns
Returns true when an intersection occured, otherwise false. If there is no intersection, 'intersectA' and 'intersectB' won't be changed.

◆ Intersects() [4/4]

bool MCore::Ray::Intersects ( const PlaneEq p,
AZ::Vector3 *  intersect = nullptr 
) const

Perform a ray/plane intersection test.

Parameters
pThe plane to test with.
intersectIf not nullptr, the intersection point will be stored in this vector, in case of an intersection.
Returns
Returns true when an intersection occured, otherwise false. If there is no intersection, 'intersect' will not be changed.

◆ Length()

MCORE_INLINE float MCore::Ray::Length ( ) const
inline

Calculates the length of the ray.

Returns
The length of the ray.

◆ Set()

MCORE_INLINE void MCore::Ray::Set ( const AZ::Vector3 &  org,
const AZ::Vector3 &  endPoint 
)
inline

Set the origin and destination point (end point) of the ray. The direction vector will be calculated automatically.

Parameters
orgThe origin of the ray, so the start point.
endPointThe destination of the ray, so the end point.

◆ SetDest()

MCORE_INLINE void MCore::Ray::SetDest ( const AZ::Vector3 &  dest)
inline

Set the destination point of the ray.

Parameters
destThe destination of the ray.

◆ SetOrigin()

MCORE_INLINE void MCore::Ray::SetOrigin ( const AZ::Vector3 &  org)
inline

Set the origin of the ray, so the start point. The direction will automatically be updated as well.

Parameters
orgThe origin.

The documentation for this class was generated from the following file: