Table of Contents

General purpose math functionality in bs::f is provided through the Math class. It provides a variety of familiar methods, such as Math::floor(), Math::clamp(), Math::cos() and many others. Check the API reference for a full list.

All other math functionality is provided through specific types, as listed below.

Vectors

Vectors are represented by Vector2, Vector3 and Vector4 classes. All classes come with a full range of operators so manipulating vectors is easy.

Vector3 a(0.0f, 10.0f, 20.0f);

Vector3 b(-1.0f, -2.0f, -3.0f);

Vector3 c = a + b;

Vector3 d = b - a;

Vector3 scaled = a * 3.0f;

They also come with a variety of helpful methods, and some of the more useful ones are:

Integer vectors

Integer 2D vector type is also provided as Vector2I. It also supports a full range of operators and comes with a few helper methods. Higher level integer vector types can also be created in the form of Vector3I and Vector4I.

Vector2I intVec(0, 10);

Angles

Angles are represented using either Degree or Radian classes. They accept a raw floating point value, which they expect to be in degrees or radians, respectively. Once created the system automatically converts between the two.

Quaternions only make sense for rotations if they are normalized. If you're doing many operations with them, due to precision issues they might become un-normalized. In such cases you can call Quaternion::normalize() to re-normalize them.

quat.normalize();

You can transform a quaternion back to a more familiar form using one of these methods:

Other useful methods

Often you want to rotate towards a certain direction, for example making a camera look towards something. You can create such rotation by calling Quaternion::lookRotation().

Quaternion q;

// Look towards negative z axis

q.lookRotation(-Vector3::UNIT_Z);

You can interpolate between using two quaternions using Quaternion::lerp() and Quaternion::slerp(). The first method offers normal linear interpolation, and the second method offers a specialized form of interpolation possible only with quaternions, called spherical interpolation. Spherical interpolation is special because it doesn't change the magnitude of the quaternion (i.e. the interpolation happens on a surface of a sphere), while linear interpolation might require a quaternion to be re-normalized after interpolating. On the other hand linear interpolation requires less CPU cycles to execute.

Quaternion interpVal0 = Quaternion::lerp(0.5f, a, b);

interpVal0.normalize();

Quaternion interpVal1 = Quaternion::slerp(0.5f, a, b);

Sometimes you have two vectors and want to find a rotation that rotates the first vector into the position of the second. You can do that by using Quaternion::getRotationFromTo().

Matrices

Matrices can be split into two major types: Matrix3 representing a 3x3 matrix and Matrix4 representing a 4x4 matrix. 3x3 matrices are used primarily for representing rotations, and are used similarly to quaternions. 4x4 matrices are used to represent a complete set of transformations like scale, translation and rotation, and are the most commonly used matrix type. We also provide a generic MatrixNxM<N, M> template for other matrix sizes, but they come with much simpler functionality.

Matrix3

Matrix3 can be initialized using Euler angles, axis/angle combination, or from a quaternion. It can also accept a scale factor as well as rotation.

You can decompose a matrix back into rotation & scale components by calling Matrix3::decomposition(). Note that this is only able to work if the matrix contains rotation and/or uniform scale, without any other transformations. Otherwise returned values will likely not be accurate.

Quaternion rotation;

Vector3 scale;

mat.decomposition(rotation, scale);

If the matrix contains only rotation you can also use any of the following methods to extract it:

Not that a vector has its 4th component set to 1. This means the vector is treated as a point, and will be translated by the matrix. If the 4th component was 0, the vector would be treated as a direction instead, and translation would not be applied.

You can also use overriden Matrix4::multiply() to multiply a Vector3, in which case it is assumed to be a point (4th component is equal to 1). If you instead wish to assume a Vector3 is a direction, use Matrix4::multiplyDirection() instead.

You can decompose a matrix back into rotation, scale and translation components by calling Matrix4::decomposition(). Note that this is only able to work if the matrix contains rotation, translation and uniform scale, without any other transformations. Otherwise returned values will likely not be accurate.

Vector3 translation;

Quaternion rotation;

Vector3 scale;

mat.decomposition(translation, rotation, scale);

Rays

Rays are represented using an origin point, and a direction. They are often used in physics for intersection tests.

// Ray with origin at world origin, looking up

Ray ray(Vector3(0, 0, 0), Vector3(0, 1, 0));

You can use Ray::getPoint() to get a point some distance from ray origin, along the direction.

Rectangles

Rect2 and Rect2I structures can be used for storing rectangles using floating point or integer values, respectively. Check their API reference for the methods they support, but in most scenarios you will be using them for storage and method parameters.

Shapes

How they work should be self explanatory from their API reference. All of the shapes provide a way be initialized, to be transformed by a world matrix as well a set of intersection tests against rays and other shapes.