Box: Graphene Reference Manual

## Box Box — Axis-aligned bounding box |

## Functions

graphene_box_t * | graphene_box_alloc ()
void | graphene_box_free ()
graphene_box_t * | graphene_box_init ()
graphene_box_t * | graphene_box_init_from_box ()
graphene_box_t * | graphene_box_init_from_points ()
graphene_box_t * | graphene_box_init_from_vec3 ()
graphene_box_t * | graphene_box_init_from_vectors ()
bool | graphene_box_equal ()
void | graphene_box_expand ()
void | graphene_box_expand_scalar ()
void | graphene_box_expand_vec3 ()
void | graphene_box_get_min ()
void | graphene_box_get_max ()
void | graphene_box_get_center ()
float | graphene_box_get_depth ()
float | graphene_box_get_height ()
float | graphene_box_get_width ()
void | graphene_box_get_size ()
void | graphene_box_get_bounding_sphere ()
void | graphene_box_get_vertices ()
void | graphene_box_union ()
bool | graphene_box_intersection ()
bool | graphene_box_contains_box ()
bool | graphene_box_contains_point ()
const graphene_box_t * | graphene_box_zero ()
const graphene_box_t * | graphene_box_one ()
const graphene_box_t * | graphene_box_minus_one ()
const graphene_box_t * | graphene_box_one_minus_one ()
const graphene_box_t * | graphene_box_empty ()
const graphene_box_t * | graphene_box_infinite ()

## Types and Values

| graphene_box_t

## Description

graphene_box_t provides a representation of an axis aligned minimum bounding box using the coordinates of its minimum and maximum vertices.

## Functions

### graphene_box_alloc ()

    graphene_box_t *
    graphene_box_alloc (void);

Allocates a new graphene_box_t.

The contents of the returned structure are undefined.

[constructor]

#### Returns

the newly allocated graphene_box_t structure. Use `graphene_box_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.2

### graphene_box_free ()

    void
    graphene_box_free (graphene_box_t *box);

Frees the resources allocated by `graphene_box_alloc()`.

#### Parameters

box | a graphene_box_t |

Since: 1.2

### graphene_box_init ()

    graphene_box_t *
    graphene_box_init (graphene_box_t *box,
                       const graphene_point3d_t *min,
                       const graphene_point3d_t *max);

Initializes the given graphene_box_t with two vertices.

#### Parameters

box | the graphene_box_t to initialize |
min | the coordinates of the minimum vertex. | [nullable]
max | the coordinates of the maximum vertex. | [nullable]

#### Returns

the initialized graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_init_from_box ()

    graphene_box_t *
    graphene_box_init_from_box (graphene_box_t *box,
                                const graphene_box_t *src);

Initializes the given graphene_box_t with the vertices of another graphene_box_t.

#### Parameters

box | the graphene_box_t to initialize |
src | a graphene_box_t |

#### Returns

the initialized graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_init_from_points ()

    graphene_box_t *
    graphene_box_init_from_points (graphene_box_t *box,
                                   unsigned int n_points,
                                   const graphene_point3d_t *points);

Initializes the given graphene_box_t with the given array of vertices.

If `n_points` is 0, the returned box is initialized with `graphene_box_empty()`.

#### Parameters

box | the graphene_box_t to initialize |
n_points | the number graphene_point3d_t in the `points` array |
points | an array of graphene_point3d_t. | [array length=n_points]

#### Returns

the initialized graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_init_from_vec3 ()

    graphene_box_t *
    graphene_box_init_from_vec3 (graphene_box_t *box,
                                 const graphene_vec3_t *min,
                                 const graphene_vec3_t *max);

Initializes the given graphene_box_t with two vertices stored inside graphene_vec3_t.

#### Parameters

box | the graphene_box_t to initialize |
min | the coordinates of the minimum vertex. | [nullable]
max | the coordinates of the maximum vertex. | [nullable]

#### Returns

the initialized graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_init_from_vectors ()

    graphene_box_t *
    graphene_box_init_from_vectors (graphene_box_t *box,
                                    unsigned int n_vectors,
                                    const graphene_vec3_t *vectors);

Initializes the given graphene_box_t with the given array of vertices.

If `n_vectors` is 0, the returned box is initialized with `graphene_box_empty()`.

#### Parameters

box | the graphene_box_t to initialize |
n_vectors | the number graphene_point3d_t in the `vectors` array |
vectors | an array of graphene_vec3_t. | [array length=n_vectors]

#### Returns

the initialized graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_equal ()

    bool
    graphene_box_equal (const graphene_box_t *a,
                        const graphene_box_t *b);

Checks whether the two given boxes are equal.

#### Parameters

a | a graphene_box_t |
b | a graphene_box_t |

#### Returns

`true` if the boxes are equal

Since: 1.2

### graphene_box_expand ()

    void
    graphene_box_expand (const graphene_box_t *box,
                         const graphene_point3d_t *point,
                         graphene_box_t *res);

Expands the dimensions of `box` to include the coordinates at `point` .

#### Parameters

box | a graphene_box_t |
point | the coordinates of the point to include |
res | return location for the expanded box. | [out caller-allocates]

Since: 1.2

### graphene_box_expand_scalar ()

    void
    graphene_box_expand_scalar (const graphene_box_t *box,
                                float scalar,
                                graphene_box_t *res);

Expands the dimensions of `box` by the given `scalar` value.

If `scalar` is positive, the graphene_box_t will grow; if `scalar` is negative, the graphene_box_t will shrink.

#### Parameters

box | a graphene_box_t |
scalar | a scalar value |
res | return location for the expanded box. | [out caller-allocates]

Since: 1.2

### graphene_box_expand_vec3 ()

    void
    graphene_box_expand_vec3 (const graphene_box_t *box,
                              const graphene_vec3_t *vec,
                              graphene_box_t *res);

Expands the dimensions of `box` to include the coordinates of the given vector.

#### Parameters

box | a graphene_box_t |
vec | the coordinates of the point to include, as a graphene_vec3_t |
res | return location for the expanded box. | [out caller-allocates]

Since: 1.2

### graphene_box_get_min ()

    void
    graphene_box_get_min (const graphene_box_t *box,
                          graphene_point3d_t *min);

Retrieves the coordinates of the minimum point of the given graphene_box_t.

#### Parameters

box | a graphene_box_t |
min | return location for the minimum point. | [out caller-allocates]

Since: 1.2

### graphene_box_get_max ()

    void
    graphene_box_get_max (const graphene_box_t *box,
                          graphene_point3d_t *max);

Retrieves the coordinates of the maximum point of the given graphene_box_t.

#### Parameters

box | a graphene_box_t |
max | return location for the maximum point. | [out caller-allocates]

Since: 1.2

### graphene_box_get_center ()

    void
    graphene_box_get_center (const graphene_box_t *box,
                             graphene_point3d_t *center);

Retrieves the coordinates of the center of a graphene_box_t.

#### Parameters

box | a graphene_box_t |
center | return location for the coordinates of the center. | [out caller-allocates]

Since: 1.2

### graphene_box_get_depth ()

    float
    graphene_box_get_depth (const graphene_box_t *box);

Retrieves the size of the `box` on the Z axis.

#### Parameters

box | a graphene_box_t |

#### Returns

the depth of the box

Since: 1.2

### graphene_box_get_height ()

    float
    graphene_box_get_height (const graphene_box_t *box);

Retrieves the size of the `box` on the Y axis.

#### Parameters

box | a graphene_box_t |

#### Returns

the height of the box

Since: 1.2

### graphene_box_get_width ()

    float
    graphene_box_get_width (const graphene_box_t *box);

Retrieves the size of the `box` on the X axis.

#### Parameters

box | a graphene_box_t |

#### Returns

the width of the box

Since: 1.2

### graphene_box_get_size ()

    void
    graphene_box_get_size (const graphene_box_t *box,
                           graphene_vec3_t *size);

Retrieves the size of the box on all three axes, and stores it into the given `size` vector.

#### Parameters

box | a graphene_box_t |
size | return location for the size. | [out caller-allocates]

Since: 1.2

### graphene_box_get_bounding_sphere ()

    void
    graphene_box_get_bounding_sphere (const graphene_box_t *box,
                                      graphene_sphere_t *sphere);

Computes the bounding graphene_sphere_t capable of containing the given graphene_box_t.

#### Parameters

box | a graphene_box_t |
sphere | return location for the bounding sphere. | [out caller-allocates]

Since: 1.2

### graphene_box_get_vertices ()

    void
    graphene_box_get_vertices (const graphene_box_t *box,
                               graphene_vec3_t vertices[]);

Computes the vertices of the given graphene_box_t.

#### Parameters

box | a graphene_box_t |
vertices | return location for an array of 8 graphene_vec3_t. | [out][array fixed-size=8]

Since: 1.2

### graphene_box_union ()

    void
    graphene_box_union (const graphene_box_t *a,
                        const graphene_box_t *b,
                        graphene_box_t *res);

Unions the two given graphene_box_t.

#### Parameters

a | a graphene_box_t |
b | the box to union to `a` |
res | return location for the result. | [out caller-allocates]

Since: 1.2

### graphene_box_intersection ()

    bool
    graphene_box_intersection (const graphene_box_t *a,
                               const graphene_box_t *b,
                               graphene_box_t *res);

Intersects the two given graphene_box_t.

If the two boxes do not intersect, `res` will contain a degenerate box initialized with `graphene_box_empty()`.

#### Parameters

a | a graphene_box_t |
b | a graphene_box_t |
res | return location for the result. | [out caller-allocates][optional]

#### Returns

true if the two boxes intersect

Since: 1.2

### graphene_box_contains_box ()

    bool
    graphene_box_contains_box (const graphene_box_t *a,
                               const graphene_box_t *b);

Checks whether the graphene_box_t `a` contains the given graphene_box_t `b` .

#### Parameters

a | a graphene_box_t |
b | a graphene_box_t |

#### Returns

`true` if the box is contained in the given box

Since: 1.2

### graphene_box_contains_point ()

    bool
    graphene_box_contains_point (const graphene_box_t *box,
                                 const graphene_point3d_t *point);

Checks whether `box` contains the given `point` .

#### Parameters

box | a graphene_box_t |
point | the coordinates to check |

#### Returns

`true` if the point is contained in the given box

Since: 1.2

### graphene_box_zero ()

    const graphene_box_t *
    graphene_box_zero (void);

A graphene_box_t with both the minimum and maximum vertices set at (0, 0, 0).

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_one ()

    const graphene_box_t *
    graphene_box_one (void);

A graphene_box_t with the minimum vertex set at (0, 0, 0) and the maximum vertex set at (1, 1, 1).

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_minus_one ()

    const graphene_box_t *
    graphene_box_minus_one (void);

A graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (0, 0, 0).

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_one_minus_one ()

    const graphene_box_t *
    graphene_box_one_minus_one (void);

A graphene_box_t with the minimum vertex set at (-1, -1, -1) and the maximum vertex set at (1, 1, 1).

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_empty ()

    const graphene_box_t *
    graphene_box_empty (void);

A degenerate graphene_box_t that can only be expanded.

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

### graphene_box_infinite ()

    const graphene_box_t *
    graphene_box_infinite (void);

A degenerate graphene_box_t that cannot be expanded.

The returned value is owned by Graphene and should not be modified or freed.

#### Returns

a graphene_box_t.

[transfer none]

Since: 1.2

## Types and Values

### graphene_box_t

    typedef struct {
    } graphene_box_t;

A 3D box, described as the volume between a minimum and a maximum vertices.

Since: 1.2