Ray: Graphene Reference Manual

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

## Functions

graphene_ray_t * | graphene_ray_alloc ()
void | graphene_ray_free ()
graphene_ray_t * | graphene_ray_init ()
graphene_ray_t * | graphene_ray_init_from_ray ()
graphene_ray_t * | graphene_ray_init_from_vec3 ()
void | graphene_ray_get_origin ()
void | graphene_ray_get_direction ()
void | graphene_ray_get_position_at ()
float | graphene_ray_get_distance_to_point ()
float | graphene_ray_get_distance_to_plane ()
void | graphene_ray_get_closest_point_to_point ()
bool | graphene_ray_equal ()
graphene_ray_intersection_kind_t | graphene_ray_intersect_sphere ()
bool | graphene_ray_intersects_sphere ()
graphene_ray_intersection_kind_t | graphene_ray_intersect_box ()
bool | graphene_ray_intersects_box ()
graphene_ray_intersection_kind_t | graphene_ray_intersect_triangle ()
bool | graphene_ray_intersects_triangle ()

## Types and Values

| graphene_ray_t
enum | graphene_ray_intersection_kind_t

## 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

r | a graphene_ray_t |

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

r | a graphene_ray_t |
p | a graphene_point3d_t |

#### 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

r | a graphene_ray_t |
p | a graphene_plane_t |

#### 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

a | a graphene_ray_t |
b | a graphene_ray_t |

#### 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

r | a graphene_ray_t |
s | a graphene_sphere_t |

#### 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

r | a graphene_ray_t |
b | a graphene_box_t |

#### 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

r | a graphene_ray_t |
t | a graphene_triangle_t |

#### 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