The Beast Coordinate System

This page describes the coordinate system and vector data formats used by Beast.

Coordinate axes

Beast uses a right-handed coordinate system, like OpenGL.

The Y axis is nominally assumed to be Up. However, in practice the orientation of the coordinate axes used internally does not actually matter very much. If your project uses a coordinate system where Z is up, you can still exchange coordinates and vectors with Beast without the need for conversion. The rotation of the world space has no effect on the way light bounces in your scene, provided that your scene is internally consistent: i.e. that all meshes, light sources and other objects in the scene use the same coordinate space. You just have to be careful when creating objects such as directional light sources and cameras, to ensure that you replace their default orientations with orientations that match the coordinate system used in your scene. See the sub-sections below for details.

If your coordinate system is left-handed, you can still use Beast without needing to convert coordinates. Your meshes will be treated as if reflected around one axis, which does not affect the lighting calculations. However, any time you provide triangles to Beast, you will have to reverse the order in which you provide their vertices, so that their normals will be interpreted correctly.

Cameras

Cameras use a local coordinate system similar to OpenGL. When you create a camera with an identity matrix for its translation, rotation and scaling, its facing direction is in the negative direction of the global Z axis. Its local Right axis is therefore oriented in the positive direction of the global X axis, and its local Up axis is in the positive direction of the global Y axis.

The following image shows the orientation of a camera with an identity matrix relative to the Beast coordinate axes:

Directional and spot lights

When you create a directional light or spot light with an identity matrix for its translation, rotation and scaling, its facing direction is in the negative direction of the global Y axis.

The following image shows the orientation of a spot light with an identity matrix relative to the Beast coordinate axes:

Texture coordinates and images

Images and textures are treated as a coordinate system in which the origin is at the lower left corner, up is the positive direction of the Y axis, and right is the positive direction of the X axis. Note that this differs from many image formats, in which the origin is in the upper left corner and the positive direction of the Y axis points down.

Screen coordinates

Beast does not use projection matrices to go from world coordinates to screen coordinates. Instead, it uses camera objects, each of which contains a matrix that orients it in the world. The exact definition of screen coordinates therefore differs from camera to camera.

Matrices and vectors

Every type of object recognized by the Beast API that has a position and an orientation in the world stores that position and orientation as a 4 by 4 matrix. This may seem unnecessary for primitives such as directional lights (for which the translation is unimportant) or point lights (for which the rotation is unimportant). However, in the end it leads to greater simplicity because the same transformation pipeline applies to all types of objects.

Matrices are represented by ILBMatrix4x4 objects, whose data is stored line by line (the opposite of OpenGL):

(00 01 02 03)
(04 05 06 07)
(08 09 10 11)
(12 13 14 15)

Vector matrix multiplications are expressed in the following manner:

Note that Beast vectors and points only use the X, Y and Z components. The W component of the matrix is inferred depending on whether it represents a vector or a point. This is usually obvious from the context.