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

## 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()`.

 p

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

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

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

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

 a b

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

#### 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 matrix normal_matrix [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 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.

 p

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