Box

Box — Axis-aligned bounding box

Functions

Types and Values

Includes

#include <graphene.h>

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

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

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