Sphere: Graphene Reference Manual

## Sphere Sphere — A sphere |

## Functions

graphene_sphere_t * | graphene_sphere_alloc ()
void | graphene_sphere_free ()
graphene_sphere_t * | graphene_sphere_init ()
graphene_sphere_t * | graphene_sphere_init_from_points ()
graphene_sphere_t * | graphene_sphere_init_from_vectors ()
void | graphene_sphere_get_center ()
float | graphene_sphere_get_radius ()
void | graphene_sphere_get_bounding_box ()
bool | graphene_sphere_is_empty ()
float | graphene_sphere_distance ()
bool | graphene_sphere_contains_point ()
void | graphene_sphere_translate ()
bool | graphene_sphere_equal ()

## Types and Values

| graphene_sphere_t

## Includes

    #include <graphene.h>

## Description

graphene_sphere_t provides a representation of a sphere using its center and radius.

## Functions

### graphene_sphere_alloc ()

    graphene_sphere_t *
    graphene_sphere_alloc (void);

Allocates a new graphene_sphere_t.

The contents of the newly allocated structure are undefined.

[constructor]

#### Returns

the newly allocated graphene_sphere_t. Use `graphene_sphere_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.2

### graphene_sphere_free ()

    void
    graphene_sphere_free (graphene_sphere_t *s);

Frees the resources allocated by `graphene_sphere_alloc()`.

#### Parameters

s | a graphene_sphere_t |

Since: 1.2

### graphene_sphere_init ()

    graphene_sphere_t *
    graphene_sphere_init (graphene_sphere_t *s,
                          const graphene_point3d_t *center,
                          float radius);

Initializes the given graphene_sphere_t with the given `center` and `radius` .

#### Parameters

s | the graphene_sphere_t to initialize |
center | the coordinates of the center of the sphere, or `NULL` for a center in (0, 0, 0). | [nullable]
radius | the radius of the sphere |

#### Returns

the initialized graphene_sphere_t.

[transfer none]

Since: 1.2

### graphene_sphere_init_from_points ()

    graphene_sphere_t *
    graphene_sphere_init_from_points (graphene_sphere_t *s,
                                      unsigned int n_points,
                                      const graphene_point3d_t *points,
                                      const graphene_point3d_t *center);

Initializes the given graphene_sphere_t using the given array of 3D coordinates so that the sphere includes them.

The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all `points` .

#### Parameters

s | the graphene_sphere_t to initialize |
n_points | the number of graphene_point3d_t in the `points` array |
points | an array of graphene_point3d_t. | [array length=n_points]
center | the center of the sphere. | [nullable]

#### Returns

the initialized graphene_sphere_t.

[transfer none]

Since: 1.2

### graphene_sphere_init_from_vectors ()

    graphene_sphere_t *
    graphene_sphere_init_from_vectors (graphene_sphere_t *s,
                                       unsigned int n_vectors,
                                       const graphene_vec3_t *vectors,
                                       const graphene_point3d_t *center);

Initializes the given graphene_sphere_t using the given array of 3D coordinates so that the sphere includes them.

The center of the sphere can either be specified, or will be center of the 3D volume that encompasses all `vectors` .

#### Parameters

s | the graphene_sphere_t to initialize |
n_vectors | the number of graphene_vec3_t in the `vectors` array |
vectors | an array of graphene_vec3_t. | [array length=n_vectors]
center | the center of the sphere. | [nullable]

#### Returns

the initialized graphene_sphere_t.

[transfer none]

Since: 1.2

### graphene_sphere_get_center ()

    void
    graphene_sphere_get_center (const graphene_sphere_t *s,
                                graphene_point3d_t *center);

Retrieves the coordinates of the center of a graphene_sphere_t.

#### Parameters

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

Since: 1.2

### graphene_sphere_get_radius ()

    float
    graphene_sphere_get_radius (const graphene_sphere_t *s);

Retrieves the radius of a graphene_sphere_t.

#### Parameters

s | a graphene_sphere_t |

Since: 1.2

### graphene_sphere_get_bounding_box ()

    void
    graphene_sphere_get_bounding_box (const graphene_sphere_t *s,
                                      graphene_box_t *box);

Computes the bounding box capable of containing the given graphene_sphere_t.

#### Parameters

s | a graphene_sphere_t |
box | return location for the bounding box. | [out caller-allocates]

Since: 1.2

### graphene_sphere_is_empty ()

    bool
    graphene_sphere_is_empty (const graphene_sphere_t *s);

Checks whether the sphere has a zero radius.

#### Parameters

s | a graphene_sphere_t |

#### Returns

`true` if the sphere is empty

Since: 1.2

### graphene_sphere_distance ()

    float
    graphene_sphere_distance (const graphene_sphere_t *s,
                              const graphene_point3d_t *point);

Computes the distance of the given `point` from the surface of a graphene_sphere_t.

#### Parameters

s | a graphene_sphere_t |
point | a graphene_point3d_t |

#### Returns

the distance of the point

Since: 1.2

### graphene_sphere_contains_point ()

    bool
    graphene_sphere_contains_point (const graphene_sphere_t *s,
                                    const graphene_point3d_t *point);

Checks whether the given `point` is contained in the volume of a graphene_sphere_t.

#### Parameters

s | a graphene_sphere_t |
point | a graphene_point3d_t |

#### Returns

`true` if the sphere contains the point

Since: 1.2

### graphene_sphere_translate ()

    void
    graphene_sphere_translate (const graphene_sphere_t *s,
                               const graphene_point3d_t *point,
                               graphene_sphere_t *res);

Translates the center of the given graphene_sphere_t using the `point` coordinates as the delta of the translation.

#### Parameters

s | a graphene_sphere_t |
point | the coordinates of the translation |
res | return location for the translated sphere. | [out caller-allocates]

Since: 1.2

### graphene_sphere_equal ()

    bool
    graphene_sphere_equal (const graphene_sphere_t *a,
                           const graphene_sphere_t *b);

Checks whether two graphene_sphere_t are equal.

#### Parameters

a | a graphene_sphere_t |
b | a graphene_sphere_t |

#### Returns

`true` if the spheres are equal

Since: 1.2

## Types and Values

### graphene_sphere_t

    typedef struct {
    } graphene_sphere_t;

A sphere, represented by its center and radius.

Since: 1.2