Struct Ray

#[repr(C)]
pub struct Ray {
    pub position: Vec3,
    pub direction: Vec3,
}

A position and a direction indicating a ray through space! This is a great tool for intersection testing with geometrical shapes. https://stereokit.net/Pages/StereoKit/Ray.html

Examples

use stereokit_rust::{maths::{Vec3, Matrix, Ray}, model::Model, system::Lines,
    mesh::Mesh, material::Material, util::named_colors};

let point = Mesh::sphere();
let mut material_point =Material::unlit();
let model = Model::from_file("center.glb", None).unwrap().copy();
let cube = Mesh::cube();
let mut material_cube =Material::ui_box();
material_cube.color_tint(named_colors::GOLD)
             .border_size(0.05);

let center = Vec3::new(0.0, -2.5, -2.5);
let bounds = model.get_bounds();
let transform = Matrix::t_r(center, [0.0, 220.0, 0.0]);
let transform_cube = Matrix::t_s( bounds.center, bounds.dimensions) * transform;
let inv = transform.get_inverse();

let ray_x = Ray::new(Vec3{x:4.0, y: 0.0, z:  -2.5}, Vec3::NEG_X);
let inv_ray_x = inv.transform_ray(ray_x);
let inv_contact_x = bounds.intersect(inv_ray_x).expect("should be a point of contact");
let contact_x = transform.transform_point(inv_contact_x);
let transform_point_x = Matrix::t_s(contact_x, Vec3::ONE * 0.3);

filename_scr = "screenshots/ray.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
    model.draw(token, transform, None, None);
    cube.draw(token, &material_cube, transform_cube, None, None);
    Lines::add_ray(token, ray_x, 1.5, named_colors::WHITE, None, 0.2);
    point.draw(token, &material_point, transform_point_x, Some(named_colors::RED.into()), None );
);

Fields

position: Vec3

The position or origin point of the Ray.

direction: Vec3

The direction the ray is facing, typically does not require being a unit vector, or normalized direction.

Implementations

impl Ray

pub const ZERO: Self

Ray Zero is the default

pub fn new<V: Into<Vec3>>(pos: V, dir: V) -> Self

Basic initialization constructor! Just copies the parameters into the fields. https://stereokit.net/Pages/StereoKit/Ray/Ray.html

• position - The position or origin point of the Ray.
• direction - The direction the ray is facing, typically does not require being a unit vector, or normalized direction.

Examples

use stereokit_rust::maths::{Vec3, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);
let ray_b = Ray {position: Vec3::ZERO, direction: Vec3::ONE};

assert_eq!(ray, ray_b);

pub fn from_to<V: Into<Vec3>>(a: V, b: V) -> Ray

A convenience function that creates a ray from point a, towards point b. Resulting direction is not normalized. https://stereokit.net/Pages/StereoKit/Ray/FromTo.html

• a - Ray starting point.
• b - Location the ray is pointing towards.

Returns a ray from point a to point b. Not normalized.

Examples

use stereokit_rust::maths::{Vec3, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);
let ray_b = Ray::from_to( Vec3::ZERO, Vec3::ONE);

assert_eq!(ray, ray_b);

pub fn get_at(&self, percent: f32) -> Vec3

Gets a point along the ray! This is basically just position + direction*percent. If Ray.direction is normalized, then percent is functionally distance, and can be used to find the point a certain distance out along the ray. https://stereokit.net/Pages/StereoKit/Ray/At.html

• percent - How far along the ray should we get the point at? This is in multiples of self.direction’s magnitude. If self.direction is normalized, this is functionally the distance.

Returns the point at position + direction*percent

Examples

use stereokit_rust::maths::{Vec3, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);

assert_eq!(ray.get_at(3.0), Vec3::ONE * 3.0);

pub fn closest<V: Into<Vec3>>(&self, to: V) -> Vec3

Calculates the point on the Ray that’s closest to the given point! This will be clamped if the point is behind the ray’s origin. https://stereokit.net/Pages/StereoKit/Ray/Closest.html

• to - Any point in the same coordinate space as the Ray.

Returns the point on the ray that’s closest to the given point. see also ray_point_closest

Examples

use stereokit_rust::maths::{Vec3, Plane, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);

assert_eq!(ray.closest(Vec3::Z), Vec3::ONE / 3.0);

pub fn intersect_plane(&self, plane: Plane) -> Option<Vec3>

Checks the intersection of this ray with a plane! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• plane - Any plane you want to intersect with.

Returns intersection point if there’s an intersection information or None if there’s no intersection see also plane_ray_intersect same as Plane::intersect

Examples

use stereokit_rust::maths::{Vec3, Plane, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);
let plane = Plane::new(Vec3::NEG_Y, 2.5);

assert_eq!(ray.intersect_plane(plane), Some(Vec3::ONE * 2.5));

pub fn intersect_sphere(&self, sphere: Sphere) -> Option<Vec3>

Checks the intersection of this ray with a sphere! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• sphere - Any sphere you want to intersect with.

Returns the closest intersection point to the ray origin if there’s an intersection information or None if there’s no intersection see also sphere_ray_intersect same as Sphere::intersect

Examples

use stereokit_rust::maths::{Vec3, Sphere, Ray};

let ray = Ray::new(Vec3::ZERO, Vec3::ONE);
let sphere = Sphere::new(Vec3::Y, 0.5);

assert_eq!(ray.intersect_sphere(sphere), Some(Vec3::ONE * 0.5));

pub fn intersect_bounds(&self, bounds: Bounds) -> Option<Vec3>

Checks the intersection of this ray with a bounding box! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• bounds - Any bounds you want to intersect with.

Returns the closest intersection point to the ray origin if there’s an intersection information or None if there’s no intersection see also bounds_ray_intersect same as Bounds::intersect

Examples

use stereokit_rust::maths::{Vec3, Bounds, Matrix, Ray};

// A cube of 1 meter per side at this position, aligned with x y and z axis.
let box_transform = Matrix::t([10.0, 1.0, 2.0]);
let box_bounds = Bounds::bounds_centered([1.0,1.0,1.0]);

let inv = box_transform.get_inverse();
let ray1 = inv.transform_ray(Ray::new([10.2, 1.3, 2.4],[0.0, 1.0, 0.0]));
let ray2 = inv.transform_ray(Ray::new([10.9, 1.8, 2.6],[0.0, 0.0, 1.0]));
let ray3 = inv.transform_ray(Ray::new([10.5, 2.0, 2.7],[1.0, 0.0, 1.0]));

assert!(ray1.intersect_bounds(box_bounds).is_some(),  "should be a point of contact");
assert_eq!(ray2.intersect_bounds(box_bounds), None);
assert_eq!(ray3.intersect_bounds(box_bounds), None);

// We want the contact point for ray1
let contact_point = box_bounds.intersect(ray1)
        .expect ("There should be a point of contact");

let contact_point = box_transform.transform_point(contact_point);
assert_eq!(contact_point,  [10.2, 1.3, 2.4 ].into());

pub fn intersect_mesh( &self, mesh: &Mesh, cull: Option<Cull>, ) -> Option<(Vec3, VindT)>

Checks the intersection point of this ray and a Mesh with collision data stored on the CPU. A mesh without collision data will always return false. Ray must be in model space, intersection point will be in model space too. You can use the inverse of the mesh’s world transform matrix to bring the ray into model space, see the example in the docs! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• mesh - A mesh containing collision data on the CPU. You can check this with mesh.get_keep_data().
• cull - If None has default value of Cull::Back.

Returns a tuple with

• The intersection point of the ray and the mesh, if an intersection occurs. This is in model space, and must be transformed back into world space later.
• The indice of the mesh where the intersection occurs.

see also mesh_ray_intersect Ray::intersect_mesh_to_ptr same as Mesh::intersect

Examples

use stereokit_rust::{maths::{Vec3, Matrix, Quat, Ray}, system::Lines,
    util::{named_colors}, mesh::Mesh, material::{Material, Cull}};

// Create Meshes
let cube = Mesh::generate_cube(Vec3::ONE * 0.8, None);
let sphere = Mesh::generate_sphere(1.0, Some(4));

let material = Material::pbr().copy();
let transform = Matrix::r(Quat::from_angles(40.0, 50.0, 20.0));
let inv = transform.get_inverse();

let ray = Ray::new([-3.0, 2.0, 0.5 ], [3.0, -2.0, -0.25]);
let inv_ray = inv.transform_ray(ray);

let (contact_sphere, ind_sphere) = inv_ray.intersect_mesh( &sphere, Some(Cull::Front))
    .expect("Ray should touch sphere");
let (contact_cube, ind_cube) = inv_ray.intersect_mesh( &cube, Some(Cull::Back))
    .expect("Ray should touch cube");
assert_eq!(ind_sphere, 672);
assert_eq!(ind_cube, 9);

let transform_contact_sphere = Matrix::t_s(
    transform.transform_point(contact_sphere), Vec3::ONE * 0.1);
let transform_contact_cube = Matrix::t_s(
    transform.transform_point(contact_cube), Vec3::ONE * 0.1);

filename_scr = "screenshots/intersect_meshes.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
    cube.draw(token, &material, transform, Some(named_colors::CYAN.into()), None);
    sphere.draw(token, &material, transform, Some(named_colors::BLUE.into()), None);
    Lines::add_ray(token, ray, 2.2, named_colors::WHITE, None, 0.02);
    sphere.draw(token, &material, transform_contact_cube,
                Some(named_colors::YELLOW.into()), None );
    sphere.draw(token, &material, transform_contact_sphere,
                Some(named_colors::RED.into()), None );
);

pub fn intersect_mesh_to_ptr( &self, mesh: &Mesh, cull: Option<Cull>, out_model_space_at: *mut Ray, out_start_inds: *mut u32, ) -> bool

Checks the intersection point of this ray and a Mesh with collision data stored on the CPU. A mesh without collision data will always return false. Ray must be in model space, intersection point will be in model space too. You can use the inverse of the mesh’s world transform matrix to bring the ray into model space, see the example in the docs! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• mesh - A mesh containing collision data on the CPU. You can check this with mesh.get_keep_data()
• out_model_space_at - The intersection point and surface direction of the ray and the mesh, if an intersection occurs. This is in model space, and must be transformed back into world space later. Direction is not guaranteed to be normalized, especially if your own model->world transform contains scale/skew in it.
• out_start_inds - The index of the first index of the triangle that was hit
• cull - How should intersection work with respect to the direction the triangles are facing? Should we skip triangles that are facing away from the ray, or don’t skip anything? A good default would be Cull.Back. If None has default value of Cull::Back.

Returns true if an intersection occurs, false otherwise! see also mesh_ray_intersect Ray::intersect_mesh same as Mesh::intersect_to_ptr

Examples

use stereokit_rust::{maths::{Vec3, Matrix, Quat, Ray}, system::Lines,
    util::{named_colors}, mesh::Mesh, material::{Material, Cull}};

// Create Meshes
let cube = Mesh::generate_cube(Vec3::ONE * 0.8, None);
let sphere = Mesh::generate_sphere(1.0, Some(4));

let material = Material::pbr().copy();
let transform = Matrix::r(Quat::from_angles(40.0, 50.0, 20.0));
let inv = transform.get_inverse();

let ray = Ray::new([-3.0, 2.0, 0.5 ], [3.0, -2.0, -0.25]);
let inv_ray = inv.transform_ray(ray);

let (mut contact_sphere_ray, mut ind_sphere) = (Ray::default(), 0u32);
assert!(inv_ray.intersect_mesh_to_ptr(
            &sphere, Some(Cull::Front),
            &mut contact_sphere_ray, &mut ind_sphere)
    ,"Ray should touch sphere");

let (mut contact_cube_ray, mut ind_cube) = (Ray::default(), 0u32);
assert!( inv_ray.intersect_mesh_to_ptr(
            &cube, Some(Cull::Back),
            &mut contact_cube_ray, &mut ind_cube)
    ,"Ray should touch cube");

assert_eq!(ind_sphere, 672);
assert_eq!(ind_cube, 9);

assert_eq!(transform.transform_ray(contact_sphere_ray),
        Ray { position:  Vec3 { x: 0.36746234, y: -0.244975, z: 0.21937825 },
              direction: Vec3 { x: 0.58682406, y: -0.6427875, z: 0.49240398 }});
assert_eq!(transform.transform_ray(contact_cube_ray),
        Ray { position:  Vec3 { x: -0.39531866, y: 0.26354572, z: 0.2829433 },
              direction: Vec3 { x: -0.77243483, y: -0.2620026, z: 0.57853174 } });

pub fn intersect_model(&self, model: &Model, cull: Option<Cull>) -> Option<Vec3>

Checks the intersection point of this ray and the Solid flagged Meshes in the Model’s visual nodes. Ray must be in model space, intersection point will be in model space too. You can use the inverse of the mesh’s world transform matrix to bring the ray into model space, see the example in the docs! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• model - Any Model that may or may not contain Solid flagged nodes, and Meshes with collision data.
• cull - If None has default value of Cull::Back.

Returns the intersection point of the ray and the model, if an intersection occurs. This is in model space, and must be transformed back into world space later. see also model_ray_intersect Ray::intersect_model_to_ptr same as Model::intersect

Examples

use stereokit_rust::{maths::{Vec3, Matrix, Ray}, model::Model, system::Lines,
    mesh::Mesh, material::{Material, Cull}, util::named_colors};

let model = Model::from_file("center.glb", None).unwrap().copy();
let transform = Matrix::t_r([0.0,-2.25,-2.00], [0.0, 140.0, 0.0]);

let inv_ray = Ray::new([1.0, 2.0, -3.0], [-1.5, 2.0, 3.0]);

let contact_model = inv_ray.intersect_model( &model, Some(Cull::Back))
    .expect("Ray should touch model");

let ray = transform.transform_ray(inv_ray);
let transform_contact_model = Matrix::t(transform.transform_point(contact_model));
let point = Mesh::generate_sphere(0.2, Some(2));
let material = Material::pbr();

filename_scr = "screenshots/intersect_model.jpeg";
test_screenshot!( // !!!! Get a proper main loop !!!!
    model.draw(token, transform, None, None);
    Lines::add_ray(token, ray, 1.2, named_colors::WHITE, None, 0.02);
    point.draw(token, &material, transform_contact_model,
               Some(named_colors::RED.into()), None );
);

pub fn intersect_model_to_ptr( &self, model: &Model, cull: Option<Cull>, out_model_space_at: *mut Ray, ) -> bool

Checks the intersection point of this ray and the Solid flagged Meshes in the Model’s visual nodes. Ray must be in model space, intersection point will be in model space too. You can use the inverse of the mesh’s world transform matrix to bring the ray into model space, see the example in the docs! https://stereokit.net/Pages/StereoKit/Ray/Intersect.html

• model - Any Model that may or may not contain Solid flagged nodes, and Meshes with collision data.
• cull - If None has default value of Cull::Back.
• out_model_space_at - The intersection point and surface direction of the ray and the model, if an intersection occurs. This is in model space, and must be transformed back into world space later. Direction is not guaranteed to be normalized, especially if your own model->world transform contains scale/skew in it.

Returns - true if an intersection occurs, false otherwise! see also model_ray_intersect Ray::intersect_model same as Model::intersect_to_ptr

Examples

use stereokit_rust::{maths::{Vec3, Matrix, Ray}, model::Model,
    mesh::Mesh, material::{Material, Cull}, util::named_colors};

let model = Model::from_file("center.glb", None).unwrap().copy();
let transform = Matrix::t_r([0.0,-2.25,-2.00], [0.0, 140.0, 0.0]);

let inv_ray = Ray::new([1.0, 2.0, -3.0], [-1.5, 2.0, 3.0]);

let mut inv_contact_model_ray = Ray::default();
assert!(inv_ray.intersect_model_to_ptr( &model, Some(Cull::Back), &mut inv_contact_model_ray)
    ,"Ray should touch model");

let contact_model_ray = transform.transform_ray(inv_contact_model_ray);
assert_eq!(contact_model_ray,
           Ray { position:  Vec3 { x: -0.3688636, y: 1.2613544, z: -1.3526915 },
                 direction: Vec3 { x: -0.4004621, y: -0.016381653, z: 0.9161662 } });

Trait Implementations

impl Clone for Ray

fn clone(&self) -> Ray

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Ray

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Ray

fn default() -> Ray

Returns the “default value” for a type.

impl Display for Ray

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Creates a text description of the Ray, in the format of “[position:X direction:X]” https://stereokit.net/Pages/StereoKit/Ray/ToString.html

Examples

use stereokit_rust::maths::{Vec3, Ray};

let ray = Ray::new([1.1, 2.0, 3.0], [4.0, 5.0, 6.0]);
assert_eq!(format!("{}", ray),
           "[position:[x:1.1, y:2, z:3] direction:[x:4, y:5, z:6]]");

impl Mul<Matrix> for Ray

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

fn mul(self, rhs: Matrix) -> Self::Output

Examples

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);

let transformed_ray = ray * transform;
assert_eq!(transformed_ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

type Output = Ray

The resulting type after applying the * operator.

impl Mul<Ray> for Matrix

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

fn mul(self, rhs: Ray) -> Self::Output

Examples

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let transform = Matrix::t([1.0, 2.0, 3.0]);
let ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);

let transformed_ray = transform * ray;
assert_eq!(transformed_ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

type Output = Ray

The resulting type after applying the * operator.

impl MulAssign<Matrix> for Ray

Transforms a Ray by the Matrix! The position and direction are both multiplied by the matrix, accounting properly for which should include translation, and which should not. https://stereokit.net/Pages/StereoKit/Matrix/op_Multiply.html

see also matrix_transform_ray

fn mul_assign(&mut self, rhs: Matrix)

use stereokit_rust::maths::{Vec3, Matrix, Ray};

let mut ray = Ray::new([0.0, 0.0, 0.0], [1.0, 0.0, 0.0]);
let transform = Matrix::t([1.0, 2.0, 3.0]);

ray *= transform;
assert_eq!(ray, Ray::new([1.0, 2.0, 3.0], [1.0, 0.0, 0.0]));

impl PartialEq for Ray

fn eq(&self, other: &Ray) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Copy for Ray

impl StructuralPartialEq for Ray