Byte Engine Docs

Coordinates and units

Look up the engine's axes and handedness, the camera and clip-space conventions, the units of measure, the rotation and matrix representations, and the color spaces.

Every system in Byte Engine shares one set of spatial and unit conventions. This page specifies them.

Axes

ConventionValue
Up+Y
Forward+Z. A direction-only orientation rotates +Z to the direction without roll.
Right+X
HandednessLeft-handed: the cross product of +X and +Y is +Z.
World spaceThe default space of points, vectors, and directions. A game can brand its own spaces.

Local axes that systems define follow the same convention: a particle cone fires along local +Z, an IES profile emits along local +Z with +X as its C0 plane, and a capsule's axis is local Y.

Camera and clip space

ConventionValue
Field of viewVertical, in degrees, 45 by default. The horizontal field is the vertical times the aspect ratio.
Aspect ratioWidth over height.
Clip spacex and y from −1 to 1.
DepthReversed: the near plane maps to 1 and the far plane to 0, and 0 means no surface.
Front facesHave a negative signed area in clip space, for any view direction.
View basisRight, up, and the view direction; a vertical view direction uses +Z as its reference up.
Directional shadowsReach 100 m by default, or the far plane when closer.

Units

QuantityUnit
DistanceMeters. One world unit is one meter.
TimeTicks of 1/28,224,000 s; see Time and ticks.
AnglesDegrees for the field of view; radians everywhere else.
MassKilograms.
Color temperatureKelvin, from 1,000 to 40,000.
IlluminanceLux, for directional lights.
Luminous intensityCandela, for point and cone lights; lumens for flux; nits for luminance. See Lighting.
ExposureStops.
Gravity16 m/s² downward in physics.

Rotations

ConventionValue
RepresentationA unit quaternion, normalized and finite by construction.
Component orderx, y, z, w, in every array and serialized form.
CompositionComposing A with B applies B first, then A. The inverse is the conjugate.
From an axis and angleThe angle is in radians.
From a directionThe shortest rotation taking +Z to the direction, with no roll; the opposite direction rotates half a turn about +X.
InterpolationAlong the shorter arc.
Euler anglesNone. There is no yaw, pitch, or roll API, and no decomposition of a matrix into an orientation.

Matrices

ConventionValue
StorageRow-major 4 by 4.
VectorsColumn vectors: a transform applies as the matrix times the vector.
Model matrixTranslation times rotation times scale.
View matrixThe basis rows times a translation by the negated eye position.
View projectionProjection times view.
Affine matrixFour columns of three: the linear basis and the translation, with the bottom row implied. Shaders take the model matrix in this form and skinning poses are stored in it.

Color

ConventionValue
Scene colorScene-linear sRGB with Rec. 709 primaries. Light colors are given in it or converted to it from a temperature.
ExposureApplied as scene light is written, so real-world intensities fit the half-precision scene target.
DisplayThe display pass encodes scene-linear color to sRGB; tone-mapping and LUT passes produce display color instead when installed.
TexturesGamma follows the texture's role: albedo is sRGB, normal, roughness, and other data textures are linear, and PNG metadata overrides the default. Photometric profile images must be linear.

Rust API

On this page