Vectors: Graphene Reference Manual

## Vectors Vectors — Vectors in 2, 3, and 4 dimensions |

## Functions

graphene_vec2_t * | graphene_vec2_alloc ()
void | graphene_vec2_free ()
graphene_vec2_t * | graphene_vec2_init ()
graphene_vec2_t * | graphene_vec2_init_from_vec2 ()
graphene_vec2_t * | graphene_vec2_init_from_float ()
void | graphene_vec2_to_float ()
void | graphene_vec2_add ()
void | graphene_vec2_subtract ()
void | graphene_vec2_multiply ()
void | graphene_vec2_divide ()
float | graphene_vec2_dot ()
void | graphene_vec2_scale ()
float | graphene_vec2_length ()
void | graphene_vec2_normalize ()
void | graphene_vec2_negate ()
bool | graphene_vec2_equal ()
bool | graphene_vec2_near ()
void | graphene_vec2_min ()
void | graphene_vec2_max ()
float | graphene_vec2_get_x ()
float | graphene_vec2_get_y ()
const graphene_vec2_t * | graphene_vec2_zero ()
const graphene_vec2_t * | graphene_vec2_one ()
const graphene_vec2_t * | graphene_vec2_x_axis ()
const graphene_vec2_t * | graphene_vec2_y_axis ()
graphene_vec3_t * | graphene_vec3_alloc ()
void | graphene_vec3_free ()
graphene_vec3_t * | graphene_vec3_init ()
graphene_vec3_t * | graphene_vec3_init_from_vec3 ()
graphene_vec3_t * | graphene_vec3_init_from_float ()
void | graphene_vec3_to_float ()
void | graphene_vec3_add ()
void | graphene_vec3_subtract ()
void | graphene_vec3_multiply ()
void | graphene_vec3_divide ()
void | graphene_vec3_cross ()
float | graphene_vec3_dot ()
void | graphene_vec3_scale ()
float | graphene_vec3_length ()
void | graphene_vec3_normalize ()
void | graphene_vec3_negate ()
bool | graphene_vec3_equal ()
bool | graphene_vec3_near ()
void | graphene_vec3_min ()
void | graphene_vec3_max ()
float | graphene_vec3_get_x ()
float | graphene_vec3_get_y ()
float | graphene_vec3_get_z ()
void | graphene_vec3_get_xy ()
void | graphene_vec3_get_xy0 ()
void | graphene_vec3_get_xyz0 ()
void | graphene_vec3_get_xyz1 ()
void | graphene_vec3_get_xyzw ()
const graphene_vec3_t * | graphene_vec3_zero ()
const graphene_vec3_t * | graphene_vec3_one ()
const graphene_vec3_t * | graphene_vec3_x_axis ()
const graphene_vec3_t * | graphene_vec3_y_axis ()
const graphene_vec3_t * | graphene_vec3_z_axis ()
graphene_vec4_t * | graphene_vec4_alloc ()
void | graphene_vec4_free ()
graphene_vec4_t * | graphene_vec4_init ()
graphene_vec4_t * | graphene_vec4_init_from_vec4 ()
graphene_vec4_t * | graphene_vec4_init_from_vec3 ()
graphene_vec4_t * | graphene_vec4_init_from_vec2 ()
graphene_vec4_t * | graphene_vec4_init_from_float ()
void | graphene_vec4_to_float ()
void | graphene_vec4_add ()
void | graphene_vec4_subtract ()
void | graphene_vec4_multiply ()
void | graphene_vec4_divide ()
float | graphene_vec4_dot ()
void | graphene_vec4_scale ()
float | graphene_vec4_length ()
void | graphene_vec4_normalize ()
void | graphene_vec4_negate ()
bool | graphene_vec4_equal ()
bool | graphene_vec4_near ()
void | graphene_vec4_min ()
void | graphene_vec4_max ()
float | graphene_vec4_get_x ()
float | graphene_vec4_get_y ()
float | graphene_vec4_get_z ()
float | graphene_vec4_get_w ()
void | graphene_vec4_get_xy ()
void | graphene_vec4_get_xyz ()
const graphene_vec4_t * | graphene_vec4_zero ()
const graphene_vec4_t * | graphene_vec4_one ()
const graphene_vec4_t * | graphene_vec4_x_axis ()
const graphene_vec4_t * | graphene_vec4_y_axis ()
const graphene_vec4_t * | graphene_vec4_z_axis ()
const graphene_vec4_t * | graphene_vec4_w_axis ()

## Types and Values

#define | GRAPHENE_VEC2_LEN
| graphene_vec2_t
#define | GRAPHENE_VEC3_LEN
| graphene_vec3_t
#define | GRAPHENE_VEC4_LEN
| graphene_vec4_t

## Includes

    #include <graphene.h>

## Description

Graphene has three vector types, distinguished by their length:

1. graphene_vec2_t, which holds 2 components x and y

2. graphene_vec3_t, which holds 3 components x, y, and z

3. graphene_vec4_t, which holds 4 components x, y, z, and w

Each vector type should be treated as an opaque data type.

## Functions

### graphene_vec2_alloc ()

    graphene_vec2_t *
    graphene_vec2_alloc (void);

Allocates a new graphene_vec2_t structure.

The contents of the returned structure are undefined.

Use `graphene_vec2_init()` to initialize the vector.

[constructor]

#### Returns

the newly allocated graphene_vec2_t structure. Use `graphene_vec2_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.0

### graphene_vec2_free ()

    void
    graphene_vec2_free (graphene_vec2_t *v);

Frees the resources allocated by `v`

#### Parameters

v | a graphene_vec2_t |

Since: 1.0

### graphene_vec2_init ()

    graphene_vec2_t *
    graphene_vec2_init (graphene_vec2_t *v,
                        float x,
                        float y);

Initializes a graphene_vec2_t using the given values.

This function can be called multiple times.

#### Parameters

v | a graphene_vec2_t |
x | the X field of the vector |
y | the Y field of the vector |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec2_init_from_vec2 ()

    graphene_vec2_t *
    graphene_vec2_init_from_vec2 (graphene_vec2_t *v,
                                  const graphene_vec2_t *src);

Copies the contents of `src` into `v` .

#### Parameters

v | a graphene_vec2_t |
src | a graphene_vec2_t |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec2_init_from_float ()

    graphene_vec2_t *
    graphene_vec2_init_from_float (graphene_vec2_t *v,
                                   const float *src);

Initializes `v` with the contents of the given array.

#### Parameters

v | a graphene_vec2_t |
src | an array of floating point values with at least two elements. | [array fixed-size=2]

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec2_to_float ()

    void
    graphene_vec2_to_float (const graphene_vec2_t *v,
                            float *dest);

Stores the components of `v` into an array.

#### Parameters

v | a graphene_vec2_t |
dest | return location for an array of floating point values with at least 2 elements. | [out caller-allocates][array fixed-size=2]

Since: 1.0

### graphene_vec2_add ()

    void
    graphene_vec2_add (const graphene_vec2_t *a,
                       const graphene_vec2_t *b,
                       graphene_vec2_t *res);

Adds each component of the two passed vectors and places each result into the components of `res` .

#### Parameters

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

Since: 1.0

### graphene_vec2_subtract ()

    void
    graphene_vec2_subtract (const graphene_vec2_t *a,
                            const graphene_vec2_t *b,
                            graphene_vec2_t *res);

Subtracts from each component of the first operand `a` the corresponding component of the second operand `b` and places each result into the components of `res` .

#### Parameters

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

Since: 1.0

### graphene_vec2_multiply ()

    void
    graphene_vec2_multiply (const graphene_vec2_t *a,
                            const graphene_vec2_t *b,
                            graphene_vec2_t *res);

Multiplies each component of the two passed vectors and places each result into the components of `res` .

#### Parameters

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

Since: 1.0

### graphene_vec2_divide ()

    void
    graphene_vec2_divide (const graphene_vec2_t *a,
                          const graphene_vec2_t *b,
                          graphene_vec2_t *res);

Divides each component of the first operand `a` by the corresponding component of the second operand `b` , and places the results into the vector `res` .

#### Parameters

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

Since: 1.0

### graphene_vec2_dot ()

    float
    graphene_vec2_dot (const graphene_vec2_t *a,
                       const graphene_vec2_t *b);

Computes the dot product of the two given vectors.

#### Parameters

a | a graphene_vec2_t |
b | a graphene_vec2_t |

#### Returns

the dot product of the vectors

Since: 1.0

### graphene_vec2_scale ()

    void
    graphene_vec2_scale (const graphene_vec2_t *v,
                         float factor,
                         graphene_vec2_t *res);

Multiplies all components of the given vector with the given scalar `factor` .

#### Parameters

v | a graphene_vec2_t |
factor | the scalar factor |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec2_length ()

    float
    graphene_vec2_length (const graphene_vec2_t *v);

Computes the length of the given vector.

#### Parameters

v | a graphene_vec2_t |

#### Returns

the length of the vector

Since: 1.0

### graphene_vec2_normalize ()

    void
    graphene_vec2_normalize (const graphene_vec2_t *v,
                             graphene_vec2_t *res);

Computes the normalized vector for the given vector `v` .

#### Parameters

v | a graphene_vec2_t |
res | return location for the normalized vector. | [out caller-allocates]

Since: 1.0

### graphene_vec2_negate ()

    void
    graphene_vec2_negate (const graphene_vec2_t *v,
                          graphene_vec2_t *res);

Negates the given graphene_vec2_t.

#### Parameters

v | a graphene_vec2_t |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec2_equal ()

    bool
    graphene_vec2_equal (const graphene_vec2_t *v1,
                         const graphene_vec2_t *v2);

Checks whether the two given graphene_vec2_t are equal.

#### Parameters

v1 | a graphene_vec2_t |
v2 | a graphene_vec2_t |

#### Returns

`true` if the two vectors are equal, and false otherwise

Since: 1.2

### graphene_vec2_near ()

    bool
    graphene_vec2_near (const graphene_vec2_t *v1,
                        const graphene_vec2_t *v2,
                        float epsilon);

Compares the two given graphene_vec2_t vectors and checks whether their values are within the given `epsilon` .

#### Parameters

v1 | a graphene_vec2_t |
v2 | a graphene_vec2_t |
epsilon | the threshold between the two vectors |

#### Returns

`true` if the two vectors are near each other

Since: 1.2

### graphene_vec2_min ()

    void
    graphene_vec2_min (const graphene_vec2_t *a,
                       const graphene_vec2_t *b,
                       graphene_vec2_t *res);

Compares the two given vectors and places the minimum values of each component into `res` .

#### Parameters

a | a graphene_vec2_t |
b | a graphene_vec2_t |
res | the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec2_max ()

    void
    graphene_vec2_max (const graphene_vec2_t *a,
                       const graphene_vec2_t *b,
                       graphene_vec2_t *res);

Compares the two given vectors and places the maximum values of each component into `res` .

#### Parameters

a | a graphene_vec2_t |
b | a graphene_vec2_t |
res | the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec2_get_x ()

    float
    graphene_vec2_get_x (const graphene_vec2_t *v);

Retrieves the X component of the graphene_vec2_t.

#### Parameters

v | a graphene_vec2_t |

#### Returns

the value of the X component

Since: 1.0

### graphene_vec2_get_y ()

    float
    graphene_vec2_get_y (const graphene_vec2_t *v);

Retrieves the Y component of the graphene_vec2_t.

#### Parameters

v | a graphene_vec2_t |

#### Returns

the value of the Y component

Since: 1.0

### graphene_vec2_zero ()

    const graphene_vec2_t *
    graphene_vec2_zero (void);

Retrieves a constant vector with (0, 0) components.

#### Returns

the zero vector.

[transfer none]

Since: 1.0

### graphene_vec2_one ()

    const graphene_vec2_t *
    graphene_vec2_one (void);

Retrieves a constant vector with (1, 1) components.

#### Returns

the one vector.

[transfer none]

Since: 1.0

### graphene_vec2_x_axis ()

    const graphene_vec2_t *
    graphene_vec2_x_axis (void);

Retrieves a constant vector with (1, 0) components.

#### Returns

the X axis vector.

[transfer none]

Since: 1.0

### graphene_vec2_y_axis ()

    const graphene_vec2_t *
    graphene_vec2_y_axis (void);

Retrieves a constant vector with (0, 1) components.

#### Returns

the Y axis vector.

[transfer none]

Since: 1.0

### graphene_vec3_alloc ()

    graphene_vec3_t *
    graphene_vec3_alloc (void);

Allocates a new graphene_vec3_t structure.

The contents of the returned structure are undefined.

Use `graphene_vec3_init()` to initialize the vector.

[constructor]

#### Returns

the newly allocated graphene_vec3_t structure. Use `graphene_vec3_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.0

### graphene_vec3_free ()

    void
    graphene_vec3_free (graphene_vec3_t *v);

Frees the resources allocated by `v`

#### Parameters

v | a graphene_vec3_t |

Since: 1.0

### graphene_vec3_init ()

    graphene_vec3_t *
    graphene_vec3_init (graphene_vec3_t *v,
                        float x,
                        float y,
                        float z);

Initializes a graphene_vec3_t using the given values.

This function can be called multiple times.

#### Parameters

v | a graphene_vec3_t |
x | the X field of the vector |
y | the Y field of the vector |
z | the Z field of the vector |

#### Returns

a pointer to the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec3_init_from_vec3 ()

    graphene_vec3_t *
    graphene_vec3_init_from_vec3 (graphene_vec3_t *v,
                                  const graphene_vec3_t *src);

Initializes a graphene_vec3_t with the values of another graphene_vec3_t.

#### Parameters

v | a graphene_vec3_t |
src | a graphene_vec3_t |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec3_init_from_float ()

    graphene_vec3_t *
    graphene_vec3_init_from_float (graphene_vec3_t *v,
                                   const float *src);

Initializes a graphene_vec3_t with the values from an array.

#### Parameters

v | a graphene_vec3_t |
src | an array of 3 floating point values. | [array fixed-size=3]

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec3_to_float ()

    void
    graphene_vec3_to_float (const graphene_vec3_t *v,
                            float *dest);

Copies the components of a graphene_vec3_t into the given array.

#### Parameters

v | a graphene_vec3_t |
dest | return location for an array of floating point values. | [out caller-allocates][array fixed-size=3]

Since: 1.0

### graphene_vec3_add ()

    void
    graphene_vec3_add (const graphene_vec3_t *a,
                       const graphene_vec3_t *b,
                       graphene_vec3_t *res);

Adds each component of the two given vectors.

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_subtract ()

    void
    graphene_vec3_subtract (const graphene_vec3_t *a,
                            const graphene_vec3_t *b,
                            graphene_vec3_t *res);

Subtracts from each component of the first operand `a` the corresponding component of the second operand `b` and places each result into the components of `res` .

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_multiply ()

    void
    graphene_vec3_multiply (const graphene_vec3_t *a,
                            const graphene_vec3_t *b,
                            graphene_vec3_t *res);

Multiplies each component of the two given vectors.

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_divide ()

    void
    graphene_vec3_divide (const graphene_vec3_t *a,
                          const graphene_vec3_t *b,
                          graphene_vec3_t *res);

Divides each component of the first operand `a` by the corresponding component of the second operand `b` , and places the results into the vector `res` .

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_cross ()

    void
    graphene_vec3_cross (const graphene_vec3_t *a,
                         const graphene_vec3_t *b,
                         graphene_vec3_t *res);

Computes the cross product of the two given vectors.

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_dot ()

    float
    graphene_vec3_dot (const graphene_vec3_t *a,
                       const graphene_vec3_t *b);

Computes the dot product of the two given vectors.

#### Parameters

a | a graphene_vec3_t |
b | a graphene_vec3_t |

#### Returns

the value of the dot product

Since: 1.0

### graphene_vec3_scale ()

    void
    graphene_vec3_scale (const graphene_vec3_t *v,
                         float factor,
                         graphene_vec3_t *res);

Multiplies all components of the given vector with the given scalar `factor` .

#### Parameters

v | a graphene_vec3_t |
factor | the scalar factor |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec3_length ()

    float
    graphene_vec3_length (const graphene_vec3_t *v);

Retrieves the length of the given vector `v` .

#### Parameters

v | a graphene_vec3_t |

#### Returns

the value of the length of the vector

Since: 1.0

### graphene_vec3_normalize ()

    void
    graphene_vec3_normalize (const graphene_vec3_t *v,
                             graphene_vec3_t *res);

Normalizes the given graphene_vec3_t.

#### Parameters

v | a graphene_vec3_t |
res | return location for the normalized vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_negate ()

    void
    graphene_vec3_negate (const graphene_vec3_t *v,
                          graphene_vec3_t *res);

Negates the given graphene_vec3_t.

#### Parameters

v | a graphene_vec3_t |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec3_equal ()

    bool
    graphene_vec3_equal (const graphene_vec3_t *v1,
                         const graphene_vec3_t *v2);

Checks whether the two given graphene_vec3_t are equal.

#### Parameters

v1 | a graphene_vec3_t |
v2 | a graphene_vec3_t |

#### Returns

`true` if the two vectors are equal, and false otherwise

Since: 1.2

### graphene_vec3_near ()

    bool
    graphene_vec3_near (const graphene_vec3_t *v1,
                        const graphene_vec3_t *v2,
                        float epsilon);

Compares the two given graphene_vec3_t vectors and checks whether their values are within the given `epsilon` .

#### Parameters

v1 | a graphene_vec3_t |
v2 | a graphene_vec3_t |
epsilon | the threshold between the two vectors |

#### Returns

`true` if the two vectors are near each other

Since: 1.2

### graphene_vec3_min ()

    void
    graphene_vec3_min (const graphene_vec3_t *a,
                       const graphene_vec3_t *b,
                       graphene_vec3_t *res);

Compares each component of the two given vectors and creates a vector that contains the minimum values.

#### Parameters

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

Since: 1.0

### graphene_vec3_max ()

    void
    graphene_vec3_max (const graphene_vec3_t *a,
                       const graphene_vec3_t *b,
                       graphene_vec3_t *res);

Compares each component of the two given vectors and creates a vector that contains the maximum values.

#### Parameters

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

Since: 1.0

### graphene_vec3_get_x ()

    float
    graphene_vec3_get_x (const graphene_vec3_t *v);

Retrieves the first component of the given vector `v` .

#### Parameters

v | a graphene_vec3_t |

#### Returns

the value of the first component of the vector

Since: 1.0

### graphene_vec3_get_y ()

    float
    graphene_vec3_get_y (const graphene_vec3_t *v);

Retrieves the second component of the given vector `v` .

#### Parameters

v | a graphene_vec3_t |

#### Returns

the value of the second component of the vector

Since: 1.0

### graphene_vec3_get_z ()

    float
    graphene_vec3_get_z (const graphene_vec3_t *v);

Retrieves the third component of the given vector `v` .

#### Parameters

v | a graphene_vec3_t |

#### Returns

the value of the third component of the vector

Since: 1.0

### graphene_vec3_get_xy ()

    void
    graphene_vec3_get_xy (const graphene_vec3_t *v,
                          graphene_vec2_t *res);

Creates a graphene_vec2_t that contains the first and second components of the given graphene_vec3_t.

#### Parameters

v | a graphene_vec3_t |
res | return location for a graphene_vec2_t. | [out caller-allocates]

Since: 1.0

### graphene_vec3_get_xy0 ()

    void
    graphene_vec3_get_xy0 (const graphene_vec3_t *v,
                           graphene_vec3_t *res);

Creates a graphene_vec3_t that contains the first two components of the given graphene_vec3_t, and the third component set to 0.

#### Parameters

v | a graphene_vec3_t |
res | return location for a graphene_vec3_t. | [out caller-allocates]

Since: 1.0

### graphene_vec3_get_xyz0 ()

    void
    graphene_vec3_get_xyz0 (const graphene_vec3_t *v,
                            graphene_vec4_t *res);

Converts a graphene_vec3_t in a graphene_vec4_t using 0.0 as the value for the fourth component of the resulting vector.

#### Parameters

v | a graphene_vec3_t |
res | return location for the vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_get_xyz1 ()

    void
    graphene_vec3_get_xyz1 (const graphene_vec3_t *v,
                            graphene_vec4_t *res);

Converts a graphene_vec3_t in a graphene_vec4_t using 1.0 as the value for the fourth component of the resulting vector.

#### Parameters

v | a graphene_vec3_t |
res | return location for the vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_get_xyzw ()

    void
    graphene_vec3_get_xyzw (const graphene_vec3_t *v,
                            float w,
                            graphene_vec4_t *res);

Converts a graphene_vec3_t in a graphene_vec4_t using `w` as the value of the fourth component of the resulting vector.

#### Parameters

v | a graphene_vec3_t |
w | the value of the W component |
res | return location for the vector. | [out caller-allocates]

Since: 1.0

### graphene_vec3_zero ()

    const graphene_vec3_t *
    graphene_vec3_zero (void);

Provides a constant pointer to a vector with three components, all sets to 0.

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec3_one ()

    const graphene_vec3_t *
    graphene_vec3_one (void);

Provides a constant pointer to a vector with three components, all sets to 1.

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec3_x_axis ()

    const graphene_vec3_t *
    graphene_vec3_x_axis (void);

Provides a constant pointer to a vector with three components with values set to (1, 0, 0).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec3_y_axis ()

    const graphene_vec3_t *
    graphene_vec3_y_axis (void);

Provides a constant pointer to a vector with three components with values set to (0, 1, 0).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec3_z_axis ()

    const graphene_vec3_t *
    graphene_vec3_z_axis (void);

Provides a constant pointer to a vector with three components with values set to (0, 0, 1).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_alloc ()

    graphene_vec4_t *
    graphene_vec4_alloc (void);

Allocates a new graphene_vec4_t structure.

The contents of the returned structure are undefined.

Use `graphene_vec4_init()` to initialize the vector.

[constructor]

#### Returns

the newly allocated graphene_vec4_t structure. Use `graphene_vec4_free()` to free the resources allocated by this function.

[transfer full]

Since: 1.0

### graphene_vec4_free ()

    void
    graphene_vec4_free (graphene_vec4_t *v);

Frees the resources allocated by `v`

#### Parameters

v | a graphene_vec4_t |

Since: 1.0

### graphene_vec4_init ()

    graphene_vec4_t *
    graphene_vec4_init (graphene_vec4_t *v,
                        float x,
                        float y,
                        float z,
                        float w);

Initializes a graphene_vec4_t using the given values.

This function can be called multiple times.

#### Parameters

v | a graphene_vec4_t |
x | the X field of the vector |
y | the Y field of the vector |
z | the Z field of the vector |
w | the W field of the vector |

#### Returns

a pointer to the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec4_init_from_vec4 ()

    graphene_vec4_t *
    graphene_vec4_init_from_vec4 (graphene_vec4_t *v,
                                  const graphene_vec4_t *src);

Initializes a graphene_vec4_t using the components of another graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |
src | a graphene_vec4_t |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec4_init_from_vec3 ()

    graphene_vec4_t *
    graphene_vec4_init_from_vec3 (graphene_vec4_t *v,
                                  const graphene_vec3_t *src,
                                  float w);

Initializes a graphene_vec4_t using the components of a graphene_vec3_t and the value of `w` .

#### Parameters

v | a graphene_vec4_t |
src | a graphene_vec3_t |
w | the value for the fourth component of `v` |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec4_init_from_vec2 ()

    graphene_vec4_t *
    graphene_vec4_init_from_vec2 (graphene_vec4_t *v,
                                  const graphene_vec2_t *src,
                                  float z,
                                  float w);

Initializes a graphene_vec4_t using the components of a graphene_vec2_t and the values of `z` and `w` .

#### Parameters

v | a graphene_vec4_t |
src | a graphene_vec2_t |
z | the value for the third component of `v` |
w | the value for the fourth component of `v` |

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec4_init_from_float ()

    graphene_vec4_t *
    graphene_vec4_init_from_float (graphene_vec4_t *v,
                                   const float *src);

Initializes a graphene_vec4_t with the values inside the given array.

#### Parameters

v | a graphene_vec4_t |
src | an array of four floating point values. | [array fixed-size=4]

#### Returns

the initialized vector.

[transfer none]

Since: 1.0

### graphene_vec4_to_float ()

    void
    graphene_vec4_to_float (const graphene_vec4_t *v,
                            float *dest);

Stores the components of the given graphene_vec4_t into an array of floating point values.

#### Parameters

v | a graphene_vec4_t |
dest | return location for an array of floating point values. | [out caller-allocates][array fixed-size=4]

Since: 1.0

### graphene_vec4_add ()

    void
    graphene_vec4_add (const graphene_vec4_t *a,
                       const graphene_vec4_t *b,
                       graphene_vec4_t *res);

Adds each component of the two given vectors.

#### Parameters

a | a graphene_vec4_t |
b | a graphene_vec4_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec4_subtract ()

    void
    graphene_vec4_subtract (const graphene_vec4_t *a,
                            const graphene_vec4_t *b,
                            graphene_vec4_t *res);

Subtracts from each component of the first operand `a` the corresponding component of the second operand `b` and places each result into the components of `res` .

#### Parameters

a | a graphene_vec4_t |
b | a graphene_vec4_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec4_multiply ()

    void
    graphene_vec4_multiply (const graphene_vec4_t *a,
                            const graphene_vec4_t *b,
                            graphene_vec4_t *res);

Multiplies each component of the two given vectors.

#### Parameters

a | a graphene_vec4_t |
b | a graphene_vec4_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec4_divide ()

    void
    graphene_vec4_divide (const graphene_vec4_t *a,
                          const graphene_vec4_t *b,
                          graphene_vec4_t *res);

Divides each component of the first operand `a` by the corresponding component of the second operand `b` , and places the results into the vector `res` .

#### Parameters

a | a graphene_vec4_t |
b | a graphene_vec4_t |
res | return location for the resulting vector. | [out caller-allocates]

Since: 1.0

### graphene_vec4_dot ()

    float
    graphene_vec4_dot (const graphene_vec4_t *a,
                       const graphene_vec4_t *b);

Computes the dot product of the two given vectors.

#### Parameters

a | a graphene_vec4_t |
b | a graphene_vec4_t |

#### Returns

the value of the dot product

Since: 1.0

### graphene_vec4_scale ()

    void
    graphene_vec4_scale (const graphene_vec4_t *v,
                         float factor,
                         graphene_vec4_t *res);

Multiplies all components of the given vector with the given scalar `factor` .

#### Parameters

v | a graphene_vec4_t |
factor | the scalar factor |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec4_length ()

    float
    graphene_vec4_length (const graphene_vec4_t *v);

Computes the length of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |

#### Returns

the length of the vector

Since: 1.0

### graphene_vec4_normalize ()

    void
    graphene_vec4_normalize (const graphene_vec4_t *v,
                             graphene_vec4_t *res);

Normalizes the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |
res | return location for the normalized vector. | [out caller-allocates]

Since: 1.0

### graphene_vec4_negate ()

    void
    graphene_vec4_negate (const graphene_vec4_t *v,
                          graphene_vec4_t *res);

Negates the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |
res | return location for the result vector. | [out caller-allocates]

Since: 1.2

### graphene_vec4_equal ()

    bool
    graphene_vec4_equal (const graphene_vec4_t *v1,
                         const graphene_vec4_t *v2);

Checks whether the two given graphene_vec4_t are equal.

#### Parameters

v1 | a graphene_vec4_t |
v2 | a graphene_vec4_t |

#### Returns

`true` if the two vectors are equal, and false otherwise

Since: 1.2

### graphene_vec4_near ()

    bool
    graphene_vec4_near (const graphene_vec4_t *v1,
                        const graphene_vec4_t *v2,
                        float epsilon);

Compares the two given graphene_vec4_t vectors and checks whether their values are within the given `epsilon` .

#### Parameters

v1 | a graphene_vec4_t |
v2 | a graphene_vec4_t |
epsilon | the threshold between the two vectors |

#### Returns

`true` if the two vectors are near each other

Since: 1.2

### graphene_vec4_min ()

    void
    graphene_vec4_min (const graphene_vec4_t *a,
                       const graphene_vec4_t *b,
                       graphene_vec4_t *res);

Compares each component of the two given vectors and creates a vector that contains the minimum values.

#### Parameters

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

Since: 1.0

### graphene_vec4_max ()

    void
    graphene_vec4_max (const graphene_vec4_t *a,
                       const graphene_vec4_t *b,
                       graphene_vec4_t *res);

Compares each component of the two given vectors and creates a vector that contains the maximum values.

#### Parameters

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

Since: 1.0

### graphene_vec4_get_x ()

    float
    graphene_vec4_get_x (const graphene_vec4_t *v);

Retrieves the value of the first component of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |

#### Returns

the value of the first component

Since: 1.0

### graphene_vec4_get_y ()

    float
    graphene_vec4_get_y (const graphene_vec4_t *v);

Retrieves the value of the second component of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |

#### Returns

the value of the second component

Since: 1.0

### graphene_vec4_get_z ()

    float
    graphene_vec4_get_z (const graphene_vec4_t *v);

Retrieves the value of the third component of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |

#### Returns

the value of the third component

Since: 1.0

### graphene_vec4_get_w ()

    float
    graphene_vec4_get_w (const graphene_vec4_t *v);

Retrieves the value of the fourth component of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |

#### Returns

the value of the fourth component

Since: 1.0

### graphene_vec4_get_xy ()

    void
    graphene_vec4_get_xy (const graphene_vec4_t *v,
                          graphene_vec2_t *res);

Creates a graphene_vec2_t that contains the first two components of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |
res | return location for a graphene_vec2_t. | [out caller-allocates]

Since: 1.0

### graphene_vec4_get_xyz ()

    void
    graphene_vec4_get_xyz (const graphene_vec4_t *v,
                           graphene_vec3_t *res);

Creates a graphene_vec3_t that contains the first three components of the given graphene_vec4_t.

#### Parameters

v | a graphene_vec4_t |
res | return location for a graphene_vec3_t. | [out caller-allocates]

Since: 1.0

### graphene_vec4_zero ()

    const graphene_vec4_t *
    graphene_vec4_zero (void);

Retrieves a pointer to a graphene_vec4_t with all its components set to 0.

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_one ()

    const graphene_vec4_t *
    graphene_vec4_one (void);

Retrieves a pointer to a graphene_vec4_t with all its components set to 1.

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_x_axis ()

    const graphene_vec4_t *
    graphene_vec4_x_axis (void);

Retrieves a pointer to a graphene_vec4_t with its components set to (1, 0, 0, 0).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_y_axis ()

    const graphene_vec4_t *
    graphene_vec4_y_axis (void);

Retrieves a pointer to a graphene_vec4_t with its components set to (0, 1, 0, 0).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_z_axis ()

    const graphene_vec4_t *
    graphene_vec4_z_axis (void);

Retrieves a pointer to a graphene_vec4_t with its components set to (0, 0, 1, 0).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

### graphene_vec4_w_axis ()

    const graphene_vec4_t *
    graphene_vec4_w_axis (void);

Retrieves a pointer to a graphene_vec4_t with its components set to (0, 0, 0, 1).

#### Returns

a constant vector.

[transfer none]

Since: 1.0

## Types and Values

### GRAPHENE_VEC2_LEN

    #define GRAPHENE_VEC2_LEN       2

Evaluates to the number of components of a graphene_vec2_t.

Since: 1.0

### graphene_vec2_t

    typedef struct {
    } graphene_vec2_t;

A structure capable of holding a vector with two dimensions, x and y.

The contents of the graphene_vec2_t structure are private and should never be accessed directly.

### GRAPHENE_VEC3_LEN

    #define GRAPHENE_VEC3_LEN       3

Evaluates to the number of components of a graphene_vec3_t.

Since: 1.0

### graphene_vec3_t

    typedef struct {
    } graphene_vec3_t;

A structure capable of holding a vector with three dimensions: x, y, and z.

The contents of the graphene_vec3_t structure are private and should never be accessed directly.

### GRAPHENE_VEC4_LEN

    #define GRAPHENE_VEC4_LEN       4

Evaluates to the number of components of a graphene_vec4_t.

Since: 1.0

### graphene_vec4_t

    typedef struct {
    } graphene_vec4_t;

A structure capable of holding a vector with four dimensions: x, y, z, and w.

The contents of the graphene_vec4_t structure are private and should never be accessed directly.