Ray

Ray — A ray emitted from an origin in a given direction

Functions

Types and Values

Includes

#include <graphene.h>

Description

graphene_ray_t is a structure representing a ray emitted by an origin, identified by a point in 3D space, in a given direction, identified by a vector with 3 components.

A common use of graphene_ray_t is ray-casting to find which objects in a 3D scene are under the coordinates of the pointer.

Functions

graphene_ray_alloc ()

graphene_ray_t *
graphene_ray_alloc (void);

Allocates a new graphene_ray_t structure.

The contents of the returned structure are undefined.

[constructor]

Returns

the newly allocated graphene_ray_t. Use graphene_ray_free() to free the resources allocated by this function.

[transfer full]

Since: 1.4


graphene_ray_free ()

void
graphene_ray_free (graphene_ray_t *r);

Frees the resources allocated by graphene_ray_alloc().

Parameters

Since: 1.4


graphene_ray_init ()

graphene_ray_t *
graphene_ray_init (graphene_ray_t *r,
                   const graphene_point3d_t *origin,
                   const graphene_vec3_t *direction);

Initializes the given graphene_ray_t using the given origin and direction values.

Parameters

r

the graphene_ray_t to initialize

 

origin

the origin of the ray.

[nullable]

direction

the direction vector.

[nullable]

Returns

the initialized ray.

[transfer none]

Since: 1.4


graphene_ray_init_from_ray ()

graphene_ray_t *
graphene_ray_init_from_ray (graphene_ray_t *r,
                            const graphene_ray_t *src);

Initializes the given graphene_ray_t using the origin and direction values of another graphene_ray_t.

Parameters

r

the graphene_ray_t to initialize

 

src

a graphene_ray_t

 

Returns

the initialized ray.

[transfer none]

Since: 1.4


graphene_ray_init_from_vec3 ()

graphene_ray_t *
graphene_ray_init_from_vec3 (graphene_ray_t *r,
                             const graphene_vec3_t *origin,
                             const graphene_vec3_t *direction);

Initializes the given graphene_ray_t using the given vectors.

Parameters

r

the graphene_ray_t to initialize

 

origin

a graphene_vec3_t.

[nullable]

direction

a graphene_vec3_t.

[nullable]

Returns

the initialized ray.

[transfer none]

Since: 1.4


graphene_ray_get_origin ()

void
graphene_ray_get_origin (const graphene_ray_t *r,
                         graphene_point3d_t *origin);

Retrieves the origin of the given graphene_ray_t.

Parameters

r

a graphene_ray_t

 

origin

return location for the origin.

[out caller-allocates]

Since: 1.4


graphene_ray_get_direction ()

void
graphene_ray_get_direction (const graphene_ray_t *r,
                            graphene_vec3_t *direction);

Retrieves the direction of the given graphene_ray_t.

Parameters

r

a graphene_ray_t

 

direction

return location for the direction.

[out caller-allocates]

Since: 1.4


graphene_ray_get_position_at ()

void
graphene_ray_get_position_at (const graphene_ray_t *r,
                              float t,
                              graphene_point3d_t *position);

Retrieves the coordinates of a point at the distance t along the given graphene_ray_t.

Parameters

r

a graphene_ray_t

 

t

the distance along the ray

 

position

return location for the position.

[out caller-allocates]

Since: 1.4


graphene_ray_get_distance_to_point ()

float
graphene_ray_get_distance_to_point (const graphene_ray_t *r,
                                    const graphene_point3d_t *p);

Computes the distance of the closest approach between the given graphene_ray_t r and the point p .

The closest approach to a ray from a point is the distance between the point and the projection of the point on the ray itself.

Parameters

Returns

the distance of the point

Since: 1.4


graphene_ray_get_distance_to_plane ()

float
graphene_ray_get_distance_to_plane (const graphene_ray_t *r,
                                    const graphene_plane_t *p);

Computes the distance of the origin of the given graphene_ray_t from the given plane.

If the ray does not intersect the plane, this function returns INFINITY.

Parameters

Returns

the distance of the origin of the ray from the plane

Since: 1.4


graphene_ray_get_closest_point_to_point ()

void
graphene_ray_get_closest_point_to_point
                               (const graphene_ray_t *r,
                                const graphene_point3d_t *p,
                                graphene_point3d_t *res);

Computes the point on the given graphene_ray_t that is closest to the given point p .

Parameters

r

a graphene_ray_t

 

p

a graphene_point3d_t

 

res

return location for the closest point3d.

[out caller-allocates]

Since: 1.4


graphene_ray_equal ()

bool
graphene_ray_equal (const graphene_ray_t *a,
                    const graphene_ray_t *b);

Checks whether the two given graphene_ray_t are equal.

Parameters

Returns

true if the given rays are equal

Since: 1.4


graphene_ray_intersect_sphere ()

graphene_ray_intersection_kind_t
graphene_ray_intersect_sphere (const graphene_ray_t *r,
                               const graphene_sphere_t *s,
                               float *t_out);

Intersects the given graphene_ray_t r with the given graphene_sphere_t s .

Parameters

r

a graphene_ray_t

 

s

a graphene_sphere_t

 

t_out

the distance of the point on the ray that intersects the sphere.

[out]

Returns

the type of intersection

Since: 1.10


graphene_ray_intersects_sphere ()

bool
graphene_ray_intersects_sphere (const graphene_ray_t *r,
                                const graphene_sphere_t *s);

Checks if the given graphene_ray_t r intersects the given graphene_sphere_t s .

See also: graphene_ray_intersect_sphere()

Parameters

Returns

true if the ray intersects the sphere

Since: 1.10


graphene_ray_intersect_box ()

graphene_ray_intersection_kind_t
graphene_ray_intersect_box (const graphene_ray_t *r,
                            const graphene_box_t *b,
                            float *t_out);

Intersects the given graphene_ray_t r with the given graphene_box_t b .

Parameters

r

a graphene_ray_t

 

b

a graphene_box_t

 

t_out

the distance of the point on the ray that intersects the box.

[out]

Returns

the type of intersection

Since: 1.10


graphene_ray_intersects_box ()

bool
graphene_ray_intersects_box (const graphene_ray_t *r,
                             const graphene_box_t *b);

Checks whether the given graphene_ray_t r intersects the given graphene_box_t b .

See also: graphene_ray_intersect_box()

Parameters

Returns

true if the ray intersects the box

Since: 1.10


graphene_ray_intersect_triangle ()

graphene_ray_intersection_kind_t
graphene_ray_intersect_triangle (const graphene_ray_t *r,
                                 const graphene_triangle_t *t,
                                 float *t_out);

Intersects the given graphene_ray_t r with the given graphene_triangle_t t .

Parameters

r

a graphene_ray_t

 

t

a graphene_triangle_t

 

t_out

the distance of the point on the ray that intersects the triangle.

[out]

Returns

the type of intersection

Since: 1.10


graphene_ray_intersects_triangle ()

bool
graphene_ray_intersects_triangle (const graphene_ray_t *r,
                                  const graphene_triangle_t *t);

Checks whether the given graphene_ray_t r intersects the given graphene_triangle_t b .

See also: graphene_ray_intersect_triangle()

Parameters

Returns

true if the ray intersects the triangle

Since: 1.10

Types and Values

graphene_ray_t

typedef struct {
} graphene_ray_t;

A ray emitted from an origin in a given direction.

The contents of the graphene_ray_t structure are private, and should not be modified directly.

Since: 1.4


enum graphene_ray_intersection_kind_t

The type of intersection.

Members

GRAPHENE_RAY_INTERSECTION_KIND_NONE

No intersection

 

GRAPHENE_RAY_INTERSECTION_KIND_ENTER

The ray is entering the intersected object

 

GRAPHENE_RAY_INTERSECTION_KIND_LEAVE

The ray is leaving the intersected object

 

Since: 1.10