Plane

Plane — A plane in 3D space

Functions

Types and Values

Includes

#include <graphene.h>

Description

graphene_plane_t is a structure representing a plane that extends infinitely in 3D space, described using the Hessian normal form of a unit length normal vector pointing towards the origin, and a constant distance from the origin along the normal vector.

Functions

graphene_plane_alloc ()

graphene_plane_t *
graphene_plane_alloc (void);

Allocates a new graphene_plane_t structure.

The contents of the returned structure are undefined.

[constructor]

Returns

the newly allocated graphene_plane_t. Use graphene_plane_free() to free the resources allocated by this function.

[transfer full]

Since: 1.2


graphene_plane_free ()

void
graphene_plane_free (graphene_plane_t *p);

Frees the resources allocated by graphene_plane_alloc().

Parameters

Since: 1.2


graphene_plane_init ()

graphene_plane_t *
graphene_plane_init (graphene_plane_t *p,
                     const graphene_vec3_t *normal,
                     float constant);

Initializes the given graphene_plane_t using the given normal vector and constant values.

Parameters

p

the graphene_plane_t to initialize

 

normal

a unit length normal vector defining the plane pointing towards the origin; if unset, we use the X axis by default.

[nullable]

constant

the distance from the origin to the plane along the normal vector; the sign determines the half-space occupied by the plane

 

Returns

the initialized plane.

[transfer none]

Since: 1.2


graphene_plane_init_from_vec4 ()

graphene_plane_t *
graphene_plane_init_from_vec4 (graphene_plane_t *p,
                               const graphene_vec4_t *src);

Initializes the given graphene_plane_t using the components of the given graphene_vec4_t vector.

Parameters

p

the graphene_plane_t to initialize

 

src

a graphene_vec4_t containing the normal vector in its first three components, and the distance in its fourth component

 

Returns

the initialized plane.

[transfer none]

Since: 1.2


graphene_plane_init_from_plane ()

graphene_plane_t *
graphene_plane_init_from_plane (graphene_plane_t *p,
                                const graphene_plane_t *src);

Initializes the given graphene_plane_t using the normal vector and constant of another graphene_plane_t.

Parameters

p

the graphene_plane_t to initialize

 

src

a graphene_plane_t

 

Returns

the initialized plane.

[transfer none]

Since: 1.2


graphene_plane_init_from_point ()

graphene_plane_t *
graphene_plane_init_from_point (graphene_plane_t *p,
                                const graphene_vec3_t *normal,
                                const graphene_point3d_t *point);

Initializes the given graphene_plane_t using the given normal vector and an arbitrary co-planar point.

Parameters

p

the graphene_plane_t to initialize

 

normal

a normal vector defining the plane pointing towards the origin

 

point

a graphene_point3d_t

 

Returns

the initialized plane.

[transfer none]

Since: 1.2


graphene_plane_init_from_points ()

graphene_plane_t *
graphene_plane_init_from_points (graphene_plane_t *p,
                                 const graphene_point3d_t *a,
                                 const graphene_point3d_t *b,
                                 const graphene_point3d_t *c);

Initializes the given graphene_plane_t using the 3 provided co-planar points.

The winding order is counter-clockwise, and determines which direction the normal vector will point.

Parameters

p

the graphene_plane_t to initialize

 

a

a graphene_point3d_t

 

b

a graphene_point3d_t

 

c

a graphene_point3d_t

 

Returns

the initialized plane.

[transfer none]

Since: 1.2


graphene_plane_normalize ()

void
graphene_plane_normalize (const graphene_plane_t *p,
                          graphene_plane_t *res);

Normalizes the vector of the given graphene_plane_t, and adjusts the constant accordingly.

Parameters

p

a graphene_plane_t

 

res

return location for the normalized plane.

[out caller-allocates]

Since: 1.2


graphene_plane_negate ()

void
graphene_plane_negate (const graphene_plane_t *p,
                       graphene_plane_t *res);

Negates the normal vector and constant of a graphene_plane_t, effectively mirroring the plane across the origin.

Parameters

p

a graphene_plane_t

 

res

return location for the negated plane.

[out caller-allocates]

Since: 1.2


graphene_plane_equal ()

bool
graphene_plane_equal (const graphene_plane_t *a,
                      const graphene_plane_t *b);

Checks whether the two given graphene_plane_t are equal.

Parameters

Returns

true if the given planes are equal

Since: 1.2


graphene_plane_distance ()

float
graphene_plane_distance (const graphene_plane_t *p,
                         const graphene_point3d_t *point);

Computes the distance of point from a graphene_plane_t.

Parameters

Returns

the distance of the given graphene_point3d_t from the plane

Since: 1.2


graphene_plane_transform ()

void
graphene_plane_transform (const graphene_plane_t *p,
                          const graphene_matrix_t *matrix,
                          const graphene_matrix_t *normal_matrix,
                          graphene_plane_t *res);

Transforms a graphene_plane_t p using the given matrix and normal_matrix .

If normal_matrix is NULL, a transformation matrix for the plane normal will be computed from matrix . If you are transforming multiple planes using the same matrix it's recommended to compute the normal matrix beforehand to avoid incurring in the cost of recomputing it every time.

Parameters

p

a graphene_plane_t

 

matrix

a graphene_matrix_t

 

normal_matrix

a graphene_matrix_t.

[nullable]

res

the transformed plane.

[out caller-allocates]

Since: 1.10


graphene_plane_get_normal ()

void
graphene_plane_get_normal (const graphene_plane_t *p,
                           graphene_vec3_t *normal);

Retrieves the normal vector pointing towards the origin of the given graphene_plane_t.

Parameters

p

a graphene_plane_t

 

normal

return location for the normal vector.

[out caller-allocates]

Since: 1.2


graphene_plane_get_constant ()

float
graphene_plane_get_constant (const graphene_plane_t *p);

Retrieves the distance along the normal vector of the given graphene_plane_t from the origin.

Parameters

Returns

the constant value of the plane

Since: 1.2

Types and Values

graphene_plane_t

typedef struct {
} graphene_plane_t;

A 2D plane that extends infinitely in a 3D volume.

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

Since: 1.2