Functionality related to vector constructs.
zmlVectorA vector construct of any given size. The values in a zmlVector are of floating-point type.
size the size of the vectorelements an array of elements in the vectorThe functions for vector-vector, vector-scalar, and vector-matrix operations are:
| Function name | Representation in operators |
|---|---|
zmlAddVecs_r(v1, v2) | v1 + v2 |
zmlAddVecs(v1, v2) | v1 += v2 |
zmlSubtractVecs_r(v1, v2) | v1 - v2 |
zmlSubtractVecs(v1, v2) | v1 -= v2 |
zmlMultiplyVecs_r(v1, v2) | v1 * v2 |
zmlMultiplyVecs(v1, v2) | v1 *= v2 |
zmlDivideVecs_r(v1, v2) | v1 / v2 |
zmlDivideVecs(v1, v2) | v1 /= v2 |
| Function name | Representation in operators |
|---|---|
zmlMultiplyVecMat_r(v1, v2) | v1 * v2 |
zmlMultiplyVecMat(v1, v2) | v1 *= v2 |
| Function name | Representation in operators |
|---|---|
zmlAddVecScalar_r(v1, v2) | v1 + v2 |
zmlAddVecScalar(v1, v2) | v1 += v2 |
zmlSubtractVecScalar_r(v1, v2) | v1 - v2 |
zmlSubtractVecScalar(v1, v2) | v1 -= v2 |
zmlMultiplyVecScalar_r(v1, v2) | v1 * v2 |
zmlMultiplyVecScalar(v1, v2) | v1 *= v2 |
zmlDivideVecScalar_r(v1, v2) | v1 / v2 |
zmlDivideVecScalar(v1, v2) | v1 /= v2 |
| Function name | Representation in operators |
|---|---|
zmlVecEquals(v1, v2) | v1 == v2 |
zmlVecGT(v1, v2) | v1 > v2 |
zmlVecGTE(v1, v2) | v1 >= v2 |
zmlVecLT(v1, v2) | v1 < v2 |
zmlVecLTE(v1, v2) | v1 <= v2 |
zmlVecEqualsScalar(v1, v2) | v1 == v2 |
zmlVecGTScalar(v1, v2) | v1 > v2 |
zmlVecGTEScalar(v1, v2) | v1 >= v2 |
zmlVecLTScalar(v1, v2) | v1 < v2 |
zmlVecLTEScalar(v1, v2) | v1 <= v2 |
For more information regarding the naming convention used for operator functions, see Home/Naming scheme of operator functions.
The_r operator functions allocate memory for their return values which must be freed to avoid memory leaks.
zmlVector zmlAllocVector(unsigned int size)size the size of the vectorAllocate memory for a vector struct, and return the empty vector. Elements are NOT initialised!
After a vector is created, it must be freed after use with zmlFreeVector().void zmlFreeVector(zmlVector *vec)vec the vector to free.Free a vector's memory.
zmlVector zmlConstructVectorDefault(unsigned int size, floating val)size the size of the vector.val the value to initialise the vector with.Construct a vector with a default value.
After a vector is created, it must be freed after use with zmlFreeVector().zmlVector zmlConstructVector(unsigned int size, ...)size the size of the vector.... the values to initialise the vector with. Must be floating-point!
Construct a vector with given values. The amount of given variable arguments is assumed to be size,
so you must initialise all values! For example, if you were to call zmlConstructVector(3, 2.0, 5.0),
a Vector3 will be created but only the first two elements will be initialised - the last element will be undetermined.
If you don't initialise all values, you should at least set the undefined elements manually as soon as possible.
stdout.
Given values must explicitly be floating-point; i.e., say '5.0' instead of '5'. This is simply due to how
variadic arguments work in C. If you do not explicitly make the values floating-point, the vector will be initialised
as a zero vector.
After a vector is created, it must be freed after use with zmlFreeVector().
zmlVector zmlCopyVector(zmlVector *val)val the vector to be copied.Copy a vector's values into a new vector and return the duplicate. The original vector is not freed.
The resultant vector must be freed after use with zmlFreeVector().zmlVector zmlCross(zmlVector v1, zmlVector v2)v1 the first vector to operate on.v2 the second vector to operate on.
Produces a vector that is the cross product of the two given vectors; this represents the vector perpendicular to the plane that
v1 and v2 create. All involved vectors must be of size 3: if not,
ZML_NULL_VECTOR is returned and a warning is printed to stdout.
floating zmlDot(zmlVector v1, zmlVector v2)v1 the first vector to operate on.v2 the second vector to operate on.
Produces the dot (scalar) product of the two given vectors v1 and v2.
All given vectors must be of the same size: if not, 0 is returned and a warning is printed to stdout.
floating zmlMagnitude(zmlVector vec)vec the specified vector.Returns the magnitude (length) of the given vector v.
zmlVector zmlNormalised(zmlVector vec)vec the specified vector.Returns the given vector in its normalised state - that is to say its magnitude is 1.
This function produces a new vector structure which must be freed with zmlFreeVector(). In cases where you would type, for example,vec = zmlNormalised(&vec), you should type zmlNormalise(&vec),
using the zmlNormalise() function instead.
void zmlNormalise(zmlVector *vec)vec the specified vector.Normalises the specified vector by modifying it. This is an alternative to zmlNormalised() that does not allocate any new memory; you should use this function instead in some cases to avoid memory leaks - see the warning in zmlNormlised().
void zmlCopyVectorElements(zmlVector vec, floating arr[vec.size])vec the specified vector.arr the destination array.
Copies the elements from vector vec into the specified array arr.
This is useful for copying the elements of the vector into the stack.
ZML_NULL_VECTOR
An undefined vector with a size of 0. This is sometimes returned when functions fail
(although functions will also print an error to stdout when they return ZML_NULL_VECTOR).
elements array in undefined vectors is a null pointer - using ZML_NULL_VECTOR is very unsafe!