SIMD matrix: Graphene Reference Manual

## SIMD matrix SIMD matrix — Low level floating point 4 by 4 matrix |

## Functions

graphene_simd4x4f_t | graphene_simd4x4f_init ()
void | graphene_simd4x4f_init_identity ()
void | graphene_simd4x4f_init_from_float ()
void | graphene_simd4x4f_to_float ()
void | graphene_simd4x4f_transpose_in_place ()
void | graphene_simd4x4f_sum ()
void | graphene_simd4x4f_vec4_mul ()
void | graphene_simd4x4f_vec3_mul ()
void | graphene_simd4x4f_point3_mul ()
void | graphene_simd4x4f_transpose ()
void | graphene_simd4x4f_inv_ortho_vec3_mul ()
void | graphene_simd4x4f_inv_ortho_point3_mul ()
void | graphene_simd4x4f_matrix_mul ()
void | graphene_simd4x4f_init_perspective ()
void | graphene_simd4x4f_init_ortho ()
void | graphene_simd4x4f_init_look_at ()
void | graphene_simd4x4f_init_frustum ()
void | graphene_simd4x4f_perspective ()
void | graphene_simd4x4f_translation ()
void | graphene_simd4x4f_scale ()
void | graphene_simd4x4f_rotation ()
void | graphene_simd4x4f_add ()
void | graphene_simd4x4f_sub ()
void | graphene_simd4x4f_mul ()
void | graphene_simd4x4f_div ()
bool | graphene_simd4x4f_inverse ()
void | graphene_simd4x4f_determinant ()
bool | graphene_simd4x4f_is_identity ()
bool | graphene_simd4x4f_is_2d ()

## Types and Values

| graphene_simd4x4f_t

## Includes

    #include <graphene.h>

## Description

The graphene_simd4x4f_t type wraps a platform specific implementation of a four by four matrix of floating point values, using four graphene_simd4f_t row vectors.

Like graphene_simd4f_t, the graphene_simd4x4f_t type should be treated as an opaque type; you cannot access its components directly, and you can only operate on all components at the same time.

## Functions

### graphene_simd4x4f_init ()

    graphene_simd4x4f_t
    graphene_simd4x4f_init (graphene_simd4f_t x,
                            graphene_simd4f_t y,
                            graphene_simd4f_t z,
                            graphene_simd4f_t w);

Creates a new graphene_simd4x4f_t using the given row vectors to initialize it.

#### Parameters

x | a graphene_simd4f_t for the first row |
y | a graphene_simd4f_t for the second row |
z | a graphene_simd4f_t for the third row |
w | a graphene_simd4f_t for the fourth row |

#### Returns

the newly created graphene_simd4x4f_t

Since: 1.0

### graphene_simd4x4f_init_identity ()

    void
    graphene_simd4x4f_init_identity (graphene_simd4x4f_t *m);

Initializes `m` to be the identity matrix.

#### Parameters

m | a graphene_simd4x4f_t |

Since: 1.0

### graphene_simd4x4f_init_from_float ()

    void
    graphene_simd4x4f_init_from_float (graphene_simd4x4f_t *m,
                                       const float *f);

Initializes a graphene_simd4x4f_t with the given array of floating point values.

#### Parameters

m | a graphene_simd4x4f_t |
f | an array of 16 floating point values. | [array fixed-size=16]

Since: 1.0

### graphene_simd4x4f_to_float ()

    void
    graphene_simd4x4f_to_float (const graphene_simd4x4f_t *m,
                                float *v);

Copies the content of `m` in a float array.

#### Parameters

m | a graphene_sidm4x4f_t |
v | a floating point values vector capable of holding at least 16 values. | [out caller-allocates][array fixed-size=16]

Since: 1.0

### graphene_simd4x4f_transpose_in_place ()

    void
    graphene_simd4x4f_transpose_in_place (graphene_simd4x4f_t *s);

Transposes `s` in place.

#### Parameters

s | a graphene_simd4x4f_t |

Since: 1.0

### graphene_simd4x4f_sum ()

    void
    graphene_simd4x4f_sum (const graphene_simd4x4f_t *a,
                           graphene_simd4f_t *res);

Adds all the row vectors of `a` .

#### Parameters

a | a graphene_simd4f_t |
res | return location for the sum vector. | [out]

Since: 1.0

### graphene_simd4x4f_vec4_mul ()

    void
    graphene_simd4x4f_vec4_mul (const graphene_simd4x4f_t *a,
                                const graphene_simd4f_t *b,
                                graphene_simd4f_t *res);

Multiplies the given graphene_simd4x4f_t with the given graphene_simd4f_t using a dot product.

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4f_t |
res | return location for a graphene_simd4f_t. | [out]

Since: 1.0

### graphene_simd4x4f_vec3_mul ()

    void
    graphene_simd4x4f_vec3_mul (const graphene_simd4x4f_t *m,
                                const graphene_simd4f_t *v,
                                graphene_simd4f_t *res);

Multiplies the given graphene_simd4x4f_t with the given graphene_simd4f_t, using only the first three row vectors of the matrix, and the first three components of the vector.

#### Parameters

m | a graphene_simd4x4f_t |
v | a graphene_simd4f_t |
res | return location for a graphene_simd4f_t. | [out]

Since: 1.0

### graphene_simd4x4f_point3_mul ()

    void
    graphene_simd4x4f_point3_mul (const graphene_simd4x4f_t *m,
                                  const graphene_simd4f_t *p,
                                  graphene_simd4f_t *res);

Multiplies the given graphene_simd4x4f_t with the given graphene_simd4f_t.

Unlike `graphene_simd4x4f_vec3_mul()`, this function will also use the fourth row vector of the matrix.

#### Parameters

m | a graphene_simd4x4f_t |
p | a graphene_simd4f_t |
res | return location for a graphene_simd4f_t. | [out]

Since: 1.0

### graphene_simd4x4f_transpose ()

    void
    graphene_simd4x4f_transpose (const graphene_simd4x4f_t *s,
                                 graphene_simd4x4f_t *res);

Transposes the given graphene_simd4x4f_t.

#### Parameters

s | a graphene_simd4x4f_t |
res | return location for the transposed matrix. | [out]

Since: 1.0

### graphene_simd4x4f_inv_ortho_vec3_mul ()

    void
    graphene_simd4x4f_inv_ortho_vec3_mul (const graphene_simd4x4f_t *a,
                                          const graphene_simd4f_t *b,
                                          graphene_simd4f_t *res);

Performs the inverse orthographic transformation of the first three components in the given vector, using the first three row vectors of the given SIMD matrix.

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4f_t |
res | return location for the transformed vector. | [out]

Since: 1.0

### graphene_simd4x4f_inv_ortho_point3_mul ()

    void
    graphene_simd4x4f_inv_ortho_point3_mul
                                   (const graphene_simd4x4f_t *a,
                                    const graphene_simd4f_t *b,
                                    graphene_simd4f_t *res);

Performs the inverse orthographic transformation of the first three components in the given vector, using the given SIMD matrix.

Unlike `graphene_simd4x4f_inv_ortho_vec3_mul()`, this function will also use the fourth row vector of the SIMD matrix.

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for the result vector. | [out]

Since: 1.0

### graphene_simd4x4f_matrix_mul ()

    void
    graphene_simd4x4f_matrix_mul (const graphene_simd4x4f_t *a,
                                  const graphene_simd4x4f_t *b,
                                  graphene_simd4x4f_t *res);

Multiplies the two matrices.

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for the result. | [out]

Since: 1.0

### graphene_simd4x4f_init_perspective ()

    void
    graphene_simd4x4f_init_perspective (graphene_simd4x4f_t *m,
                                        float fovy_rad,
                                        float aspect,
                                        float z_near,
                                        float z_far);

Initializes a graphene_simd4x4f_t with a perspective projection.

#### Parameters

m | a graphene_simd4x4f_t |
fovy_rad | the angle of the field of vision, in radians |
aspect | the aspect value |
z_near | the depth of the near clipping plane |
z_far | the depth of the far clipping plane |

Since: 1.0

### graphene_simd4x4f_init_ortho ()

    void
    graphene_simd4x4f_init_ortho (graphene_simd4x4f_t *m,
                                  float left,
                                  float right,
                                  float bottom,
                                  float top,
                                  float z_near,
                                  float z_far);

Initializes the given SIMD matrix with an orthographic projection.

#### Parameters

m | a graphene_simd4x4f_t |
left | edge of the left clipping plane |
right | edge of the right clipping plane |
bottom | edge of the bottom clipping plane |
top | edge of the top clipping plane |
z_near | depth of the near clipping plane |
z_far | depth of the far clipping plane |

Since: 1.0

### graphene_simd4x4f_init_look_at ()

    void
    graphene_simd4x4f_init_look_at (graphene_simd4x4f_t *m,
                                    graphene_simd4f_t eye,
                                    graphene_simd4f_t center,
                                    graphene_simd4f_t up);

Initializes a SIMD matrix with the projection necessary for the camera at the `eye` coordinates to look at the object at the `center` coordinates. The top of the camera is aligned to the `up` vector.

#### Parameters

m | a graphene_simd4x4f_t |
eye | vector for the camera coordinates |
center | vector for the object coordinates |
up | vector for the upwards direction |

Since: 1.0

### graphene_simd4x4f_init_frustum ()

    void
    graphene_simd4x4f_init_frustum (graphene_simd4x4f_t *m,
                                    float left,
                                    float right,
                                    float bottom,
                                    float top,
                                    float z_near,
                                    float z_far);

Initializes a SIMD matrix with a frustum described by the distances of six clipping planes.

#### Parameters

m | a graphene_simd4x4f_t |
left | distance of the left clipping plane |
right | distance of the right clipping plane |
bottom | distance of the bottom clipping plane |
top | distance of the top clipping plane |
z_near | distance of the near clipping plane |
z_far | distance of the far clipping plane |

Since: 1.2

### graphene_simd4x4f_perspective ()

    void
    graphene_simd4x4f_perspective (graphene_simd4x4f_t *m,
                                   float depth);

Adds a perspective transformation for the given `depth` .

#### Parameters

m | a graphene_simd4x4f_t |
depth | depth of the perspective |

Since: 1.0

### graphene_simd4x4f_translation ()

    void
    graphene_simd4x4f_translation (graphene_simd4x4f_t *m,
                                   float x,
                                   float y,
                                   float z);

Initializes `m` to contain a translation to the given coordinates.

#### Parameters

m | a graphene_simd4x4f_t |
x | coordinate of the X translation |
y | coordinate of the Y translation |
z | coordinate of the Z translation |

Since: 1.0

### graphene_simd4x4f_scale ()

    void
    graphene_simd4x4f_scale (graphene_simd4x4f_t *m,
                             float x,
                             float y,
                             float z);

Initializes `m` to contain a scaling transformation with the given factors.

#### Parameters

m | a graphene_simd4x4f_t |
x | scaling factor on the X axis |
y | scaling factor on the Y axis |
z | scaling factor on the Z axis |

Since: 1.0

### graphene_simd4x4f_rotation ()

    void
    graphene_simd4x4f_rotation (graphene_simd4x4f_t *m,
                                float rad,
                                graphene_simd4f_t axis);

Initializes `m` to contain a rotation of the given angle along the given axis.

#### Parameters

m | a graphene_simd4x4f_t |
rad | the rotation, in radians |
axis | the vector of the axis of rotation |

Since: 1.0

### graphene_simd4x4f_add ()

    void
    graphene_simd4x4f_add (const graphene_simd4x4f_t *a,
                           const graphene_simd4x4f_t *b,
                           graphene_simd4x4f_t *res);

Adds each row vector of `a` and `b` and places the results in `res` .

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for a graphene_simd4x4f_t. | [out caller-allocates]

Since: 1.0

### graphene_simd4x4f_sub ()

    void
    graphene_simd4x4f_sub (const graphene_simd4x4f_t *a,
                           const graphene_simd4x4f_t *b,
                           graphene_simd4x4f_t *res);

Subtracts each row vector of `a` and `b` and places the results in `res` .

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for a graphene_simd4x4f_t. | [out caller-allocates]

Since: 1.0

### graphene_simd4x4f_mul ()

    void
    graphene_simd4x4f_mul (const graphene_simd4x4f_t *a,
                           const graphene_simd4x4f_t *b,
                           graphene_simd4x4f_t *res);

Multiplies each row vector of `a` and `b` and places the results in `res` .

You most likely want `graphene_simd4x4f_matrix_mul()` instead.

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for a graphene_simd4x4f_t. | [out caller-allocates]

Since: 1.0

### graphene_simd4x4f_div ()

    void
    graphene_simd4x4f_div (const graphene_simd4x4f_t *a,
                           const graphene_simd4x4f_t *b,
                           graphene_simd4x4f_t *res);

Divides each row vector of `a` and `b` and places the results in `res` .

#### Parameters

a | a graphene_simd4x4f_t |
b | a graphene_simd4x4f_t |
res | return location for a graphene_simd4x4f_t. | [out caller-allocates]

Since: 1.0

### graphene_simd4x4f_inverse ()

    bool
    graphene_simd4x4f_inverse (const graphene_simd4x4f_t *m,
                               graphene_simd4x4f_t *res);

Inverts the given graphene_simd4x4f_t.

#### Parameters

m | a graphene_simd4x4f_t |
res | return location for the inverse matrix. | [out]

#### Returns

`true` if the matrix was invertible

Since: 1.0

### graphene_simd4x4f_determinant ()

    void
    graphene_simd4x4f_determinant (const graphene_simd4x4f_t *m,
                                   graphene_simd4f_t *det_r,
                                   graphene_simd4f_t *invdet_r);

Computes the determinant (and its inverse) of the given matrix

#### Parameters

m | a graphene_simd4x4f_t |
det_r | return location for the matrix determinant. | [out]
invdet_r | return location for the inverse of the matrix determinant. | [out]

Since: 1.0

### graphene_simd4x4f_is_identity ()

    bool
    graphene_simd4x4f_is_identity (const graphene_simd4x4f_t *m);

Checks whether the given matrix is the identity matrix.

#### Parameters

m | a graphene_simd4x4f_t |

#### Returns

`true` if the matrix is the identity matrix

Since: 1.0

### graphene_simd4x4f_is_2d ()

    bool
    graphene_simd4x4f_is_2d (const graphene_simd4x4f_t *m);

Checks whether the given matrix is compatible with an affine transformation matrix.

#### Parameters

m | a graphene_simd4x4f_t |

#### Returns

`true` if the matrix is compatible with an affine transformation matrix

Since: 1.0

## Types and Values

### graphene_simd4x4f_t

    typedef struct _graphene_simd4x4f_t graphene_simd4x4f_t;

A SIMD-based matrix type that uses four graphene_simd4f_t vectors.

The matrix is treated as row-major, i.e. the x, y, z, and w vectors are rows, and elements of each vector are a column:

    1
    2
    3
    4
    5
    6
    graphene_simd4x4f_t = {
      x.x, x.y, x.z, x.w,
      y.x, y.y, y.z, y.w,
      z.x, z.y, z.z, z.w,
      w.x, w.y, w.z, w.w
    }

The contents of the graphene_simd4x4f_t type are private and cannot be accessed directly; use the provided API instead.

Since: 1.0