Plane: Graphene Reference Manual

## Plane Plane — A plane in 3D space |

## Functions

graphene_plane_t * | graphene_plane_alloc ()
void | graphene_plane_free ()
graphene_plane_t * | graphene_plane_init ()
graphene_plane_t * | graphene_plane_init_from_vec4 ()
graphene_plane_t * | graphene_plane_init_from_plane ()
graphene_plane_t * | graphene_plane_init_from_point ()
graphene_plane_t * | graphene_plane_init_from_points ()
void | graphene_plane_normalize ()
void | graphene_plane_negate ()
bool | graphene_plane_equal ()
float | graphene_plane_distance ()
void | graphene_plane_transform ()
void | graphene_plane_get_normal ()
float | graphene_plane_get_constant ()

## Types and Values

| graphene_plane_t

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

p | a graphene_plane_t |

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

a | a graphene_plane_t |
b | a graphene_plane_t |

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

p | a graphene_plane_t |
point | a graphene_point3d_t |

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

p | a graphene_plane_t |

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