Vectors¶

API for handling single precision float vectors.

This exposes a utility API that can be used for basic manipulation of 3 component float vectors.

void c_vector3_init(float *vector, float x, float y, float z)¶

Parameters:	vector – The 3 component vector you want to initialize x – The x component y – The y component z – The z component

Initializes a 3 component, single precision float vector which can then be manipulated with the c_vector convenience APIs. Vectors can also be used in places where a “point” is often desired.

void c_vector3_init_zero(float *vector)¶

Parameters:	vector – The 3 component vector you want to initialize

Initializes a 3 component, single precision float vector with zero for each component.

_Bool c_vector3_equal(const void *v1, const void *v2)¶

Parameters:	v1 – The first 3 component vector you want to compare v2 – The second 3 component vector you want to compare

Compares the components of two vectors and returns true if they are the same.

The comparison of the components is done with the ‘==’ operator such that -0 is considered equal to 0, but otherwise there is no fuzziness such as an epsilon to consider vectors that are essentially identical except for some minor precision error differences due to the way they have been manipulated.

Returns:	true if the vectors are equal else false.

_Bool c_vector3_equal_with_epsilon(const float *vector0, const float *vector1, float epsilon)¶

Parameters:	vector0 – The first 3 component vector you want to compare vector1 – The second 3 component vector you want to compare epsilon – The allowable difference between components to still be considered equal

Compares the components of two vectors using the given epsilon and returns true if they are the same, using an internal epsilon for comparing the floats.

Each component is compared against the epsilon value in this way:

if (fabsf (vector0->x - vector1->x) < epsilon)

Returns:	true if the vectors are equal else false.

float *c_vector3_copy(const float *vector)¶

Parameters:	vector – The 3 component vector you want to copy

Allocates a new 3 component float vector on the heap initializing the components from the given vector and returns a pointer to the newly allocated vector. You should free the memory using c_vector3_free()

Returns:	A newly allocated 3 component float vector

void c_vector3_free(float *vector)¶

Parameters:	vector – The 3 component you want to free

Frees a 3 component vector that was previously allocated with c_vector3_copy()

void c_vector3_invert(float *vector)¶

Parameters:	vector – The 3 component vector you want to manipulate

Inverts/negates all the components of the given vector.

void c_vector3_add(float *result, const float *a, const float *b)¶

Parameters:	result – Where you want the result written a – The first vector operand b – The second vector operand

Adds each of the corresponding components in vectors a and b storing the results in result.

void c_vector3_subtract(float *result, const float *a, const float *b)¶

Parameters:	result – Where you want the result written a – The first vector operand b – The second vector operand

Subtracts each of the corresponding components in vector b from a storing the results in result.

void c_vector3_multiply_scalar(float *vector, float scalar)¶

Parameters:	vector – The 3 component vector you want to manipulate scalar – The scalar you want to multiply the vector components by

Multiplies each of the vector components by the given scalar.

void c_vector3_divide_scalar(float *vector, float scalar)¶

Parameters:	vector – The 3 component vector you want to manipulate scalar – The scalar you want to divide the vector components by

Divides each of the vector components by the given scalar.

void c_vector3_normalize(float *vector)¶

Parameters:	vector – The 3 component vector you want to manipulate

Updates the vector so it is a “unit vector” such that the :c:data:`vector`<!– –>s magnitude or length is equal to 1.

Note

It’s safe to use this function with the [0, 0, 0] vector, it will not try to divide components by 0 (its norm) and will leave the vector untouched.

float c_vector3_magnitude(const float *vector)¶

Parameters:	vector – The 3 component vector you want the magnitude for

Calculates the scalar magnitude or length of vector.

Returns:	The magnitude of vector.

void c_vector3_cross_product(float *result, const float *u, const float *v)¶

Parameters:	result – Where you want the result written u – Your first 3 component vector v – Your second 3 component vector

Calculates the cross product between the two vectors u and v.

The cross product is a vector perpendicular to both u and v. This can be useful for calculating the normal of a polygon by creating two vectors in its plane using the polygons vertices and taking their cross product.

If the two vectors are parallel then the cross product is 0.

You can use a right hand rule to determine which direction the perpendicular vector will point: If you place the two vectors tail, to tail and imagine grabbing the perpendicular line that extends through the common tail with your right hand such that you fingers rotate in the direction from u to v then the resulting vector points along your extended thumb.

Returns:	The cross product between two vectors u and v.

float c_vector3_dot_product(const float *a, const float *b)¶

Parameters:	a – Your first 3 component vector b – Your second 3 component vector

Calculates the dot product of the two 3 component vectors. This can be used to determine the magnitude of one vector projected onto another. (for example a surface normal)

For example if you have a polygon with a given normal vector and some other point for which you want to calculate its distance from the polygon, you can create a vector between one of the polygon vertices and that point and use the dot product to calculate the magnitude for that vector but projected onto the normal of the polygon. This way you don’t just get the distance from the point to the edge of the polygon you get the distance from the point to the nearest part of the polygon.

Note

If you don’t use a unit length normal in the above example then you would then also have to divide the result by the magnitude of the normal

The dot product is calculated as:

(a->x * b->x + a->y * b->y + a->z * b->z)

For reference, the dot product can also be calculated from the angle between two vectors as:

|a||b|cos𝜃

Returns:	The dot product of two vectors.

float c_vector3_distance(const float *a, const float *b)¶

Parameters:	a – The first point b – The second point

If you consider the two given vectors as (x,y,z) points instead then this will compute the distance between those two points.

Returns:	The distance between two points given as 3 component vectors.

void c_vector3_init(float *vector, float x, float y, float z)

Parameters:	vector – The 3 component vector you want to initialize x – The x component y – The y component z – The z component

Initializes a 3 component, single precision float vector which can then be manipulated with the c_vector convenience APIs. Vectors can also be used in places where a “point” is often desired.

void c_vector3_init_zero(float *vector)

Parameters:	vector – The 3 component vector you want to initialize

Initializes a 3 component, single precision float vector with zero for each component.

_Bool c_vector3_equal(const void *v1, const void *v2)

Parameters:	v1 – The first 3 component vector you want to compare v2 – The second 3 component vector you want to compare

Compares the components of two vectors and returns true if they are the same.

The comparison of the components is done with the ‘==’ operator such that -0 is considered equal to 0, but otherwise there is no fuzziness such as an epsilon to consider vectors that are essentially identical except for some minor precision error differences due to the way they have been manipulated.

Returns:	true if the vectors are equal else false.

_Bool c_vector3_equal_with_epsilon(const float *vector0, const float *vector1, float epsilon)

Parameters:	vector0 – The first 3 component vector you want to compare vector1 – The second 3 component vector you want to compare epsilon – The allowable difference between components to still be considered equal

Compares the components of two vectors using the given epsilon and returns true if they are the same, using an internal epsilon for comparing the floats.

Each component is compared against the epsilon value in this way:

if (fabsf (vector0->x - vector1->x) < epsilon)

Returns:	true if the vectors are equal else false.

float *c_vector3_copy(const float *vector)

Parameters:	vector – The 3 component vector you want to copy

Allocates a new 3 component float vector on the heap initializing the components from the given vector and returns a pointer to the newly allocated vector. You should free the memory using c_vector3_free()

Returns:	A newly allocated 3 component float vector

void c_vector3_free(float *vector)

Parameters:	vector – The 3 component you want to free

Frees a 3 component vector that was previously allocated with c_vector3_copy()

void c_vector3_invert(float *vector)

Parameters:	vector – The 3 component vector you want to manipulate

Inverts/negates all the components of the given vector.

void c_vector3_add(float *result, const float *a, const float *b)

Parameters:	result – Where you want the result written a – The first vector operand b – The second vector operand

Adds each of the corresponding components in vectors a and b storing the results in result.

void c_vector3_subtract(float *result, const float *a, const float *b)

Parameters:	result – Where you want the result written a – The first vector operand b – The second vector operand

Subtracts each of the corresponding components in vector b from a storing the results in result.

void c_vector3_multiply_scalar(float *vector, float scalar)

Parameters:	vector – The 3 component vector you want to manipulate scalar – The scalar you want to multiply the vector components by

Multiplies each of the vector components by the given scalar.

void c_vector3_divide_scalar(float *vector, float scalar)

Parameters:	vector – The 3 component vector you want to manipulate scalar – The scalar you want to divide the vector components by

Divides each of the vector components by the given scalar.

void c_vector3_normalize(float *vector)

Parameters:	vector – The 3 component vector you want to manipulate

Updates the vector so it is a “unit vector” such that the :c:data:`vector`<!– –>s magnitude or length is equal to 1.

Note

It’s safe to use this function with the [0, 0, 0] vector, it will not try to divide components by 0 (its norm) and will leave the vector untouched.

float c_vector3_magnitude(const float *vector)

Parameters:	vector – The 3 component vector you want the magnitude for

Calculates the scalar magnitude or length of vector.

Returns:	The magnitude of vector.

void c_vector3_cross_product(float *result, const float *u, const float *v)

Parameters:	result – Where you want the result written u – Your first 3 component vector v – Your second 3 component vector

Calculates the cross product between the two vectors u and v.

The cross product is a vector perpendicular to both u and v. This can be useful for calculating the normal of a polygon by creating two vectors in its plane using the polygons vertices and taking their cross product.

If the two vectors are parallel then the cross product is 0.

You can use a right hand rule to determine which direction the perpendicular vector will point: If you place the two vectors tail, to tail and imagine grabbing the perpendicular line that extends through the common tail with your right hand such that you fingers rotate in the direction from u to v then the resulting vector points along your extended thumb.

Returns:	The cross product between two vectors u and v.

float c_vector3_dot_product(const float *a, const float *b)

Parameters:	a – Your first 3 component vector b – Your second 3 component vector

Calculates the dot product of the two 3 component vectors. This can be used to determine the magnitude of one vector projected onto another. (for example a surface normal)

For example if you have a polygon with a given normal vector and some other point for which you want to calculate its distance from the polygon, you can create a vector between one of the polygon vertices and that point and use the dot product to calculate the magnitude for that vector but projected onto the normal of the polygon. This way you don’t just get the distance from the point to the edge of the polygon you get the distance from the point to the nearest part of the polygon.

Note

If you don’t use a unit length normal in the above example then you would then also have to divide the result by the magnitude of the normal

The dot product is calculated as:

(a->x * b->x + a->y * b->y + a->z * b->z)

For reference, the dot product can also be calculated from the angle between two vectors as:

|a||b|cos𝜃

Returns:	The dot product of two vectors.

float c_vector3_distance(const float *a, const float *b)

Parameters:	a – The first point b – The second point

If you consider the two given vectors as (x,y,z) points instead then this will compute the distance between those two points.

Returns:	The distance between two points given as 3 component vectors.