Enhances graphics math writing with APIs modeled after GLSL, offering value types like vectors, matrices, and quaternions, enabling operations like swizzling and relational comparisons for easy shader code porting.
Surfaced from shared tags and platforms — no rankings paid for.
Set of Kotlin APIs to make graphics math easier to write. These APIs are mostly modeled after GLSL (OpenGL Shading Language) to make porting code to and from shaders easier.
The various types offered by this library are only meant to be value types. Most APIs are therefore exposed as top-level functions and not as methods. For instance:
val v = Float3(1.0f, 3.0f, 4.0f)
val n = normalize(v)
This project supports multi-platform thanks to ekgame.
This fork differs from the upstream implementation:
kotlin {
sourceSets {
commonMain {
dependencies {
implementation("io.technoirlab:kotlin-math:<latest version>")
}
}
}
}
Scalar types:
Half, half-precision floating point values (also called fp16)Rational, number expressed as the ratio of two integerVector types:
Matrix types:
Mat3, 3x3 float matrixMat4, 4x4 float matrixOther types:
Quaternion, unit quaternions to represent orientationRay, simple representation of a 3D ray (origin plus direction)Each vector type exposes its component as properties:
val x = myVector.x
val (x, y, z) = myVector
A vector can also be treated as an array:
val x = myVector[0]
val x = myVector[VectorComponents.X]
The traditional mathematical form with 1-based indexing can be used:
val x = myVector(1)
To improve code readability, the vector types provide aliases for each property, allowing you to choose the most appropriate names:
val (x, y, z) = myPosition.xyz
val (r, g, b) = myColor.rgb
val (s, t) = myTextureCoordinates.st
Vector types also provide different ways to swizzle their components, although in a more limited way than in GLSL. The most obvious use for swizzling is to extract sub-vectors:
val position = Float3(…)
val position2d = position.xy // extract a Float2
val colorWithAlpha = Float4(…)
val rgbColor = colorWithAlpha.rgb // extract a Float3
The get operators allows for more complex swizzling by enabling re-ordering and duplication of the components:
val colorWithAlpha = Float4(…)
val bgrColor = colorWithAlpha[
VectorComponents.B,
VectorComponents.G,
VectorComponents.R
] // re-ordered 3 components sub-vector
Vector comparisons follow GLSL rules:
== returns true if all components are equal!= returns true if not all components are equalIn addition you can use component-wise relational operators that return a vector of boolean with the result of each component-wise comparison:
lessThanlessThanEqualgreaterThangreaterThanEqualequalnotEqualExample:
if (all(lessThan(v1, v2))) {
// …
}
You can also use the following infix operators if you prefer the operator syntax:
ltltegtgteeqneqExample:
if (any(v1 lte v2)) {
// …
}
Matrices are represented as a set of column vectors. For instance, a Mat4 can
be destructured into the right, up, forward and translation vectors:
val (right, up, forward, translation) = myMat4
Each vector can be accessed as a property or by its index:
forward = myMat4.forward
forward = myMat4.z
forward = myMat4[2]
forward = myMat4[MatrixColumns.Z]
Matrix types also offer APIs to access each element individually by specifying the column then row:
v = myMat4.z[1]
v = myMat4[2, 1]
v = myMat4[MatrixColumns.Z, 1]
You can also use the invoke operator to access elements in row-major mode with 1-based indices to follow the traditional mathematical notation:
v = myMat4(2, 3) // equivalent to myMat4[2, 1]
lookAt and lookAtRH create right-handed world-to-camera view matrices, with
the camera looking along negative Z. lookAtLH uses positive Z instead. All
three functions default to Z-up and follow GLM's view-matrix formulas.
val eye = Float3(3.0f, 4.0f, 5.0f)
val target = Float3()
val view = lookAt(eye, target) // Same as lookAtRH(eye, target)
val leftHandedView = lookAtLH(eye, target)
val cameraSpacePoint = view * Float4(worldSpacePoint, 1.0f)
The eye and target must differ, and the up vector must be nonzero and not parallel to the viewing direction.
perspective and perspectiveRH create right-handed projections and pair with
lookAt and lookAtRH. perspectiveLH pairs with lookAtLH. All three map the
near and far clipping planes to normalized device depths 0 and 1, respectively.
The vertical field of view is in radians, and the aspect ratio is width / height.
val projection = perspective(fov = radians(60.0f), ratio = 16.0f / 9.0f, near = 0.1f, far = 100.0f)
val clipSpacePoint = projection * view * Float4(worldSpacePoint, 1.0f)
val normalizedDevicePoint = clipSpacePoint.xyz / clipSpacePoint.w
All rotation angle inputs and Euler-angle outputs use radians, including the
vector and scalar overloads of rotation and Quaternion.fromEuler.
Construct an Euler angles rotation matrix using per-axis angles in radians:
rotationMatrix = rotation(d = Float3(y = HALF_PI)) // rotation of 90° around y axis
Construct a rotation matrix using an axis direction and an angle in radians:
rotationMatrix = rotation(axis = Float3(y = 1.0f), angle = HALF_PI) // rotation of 90° around y axis
Construct a quaternion rotation matrix following the Hamilton convention (assumes the destination and local coordinate spaces are initially aligned, and the local coordinate space is then rotated counter-clockwise about a unit-length axis, k, by an angle, theta):
rotationMatrix = rotation(quaternion = Quaternion(y = 1.0f, w = 1.0f)) // rotation of 90° around y axis
The file Scalar.kt contains various helper methods to use common math operations
with floats. It is intended to be used in combination with Kotlin 1.2's new float
math methods.
This library provides simple support for rational numbers to avoid numerical imprecision. The current implementation is limited to 32 bits of storage for the numerator and the denominator. The current implementation is also not written for speed.
val a = Rational(2, 5) // Represents 2/5
val b = Rational(127) // Integers can be represented exactly
val c = Rational(0.25f) // Floats and doubles will be converted to a rational representation
// The following operators are supported:
println(+a)
println(-a)
println(a + b)
println(a - b)
println(c * d)
println(c / d)
// And you can convert back to other types:
println(a.toFloat())
println(a.toLong())
radians() and degrees() for explicit conversions.lookAt returns a right-handed world-to-camera view matrix; upstream returns
a camera-to-world transform. Explicit lookAtRH and lookAtLH variants are available.perspective defaults to right-handed coordinates and maps near/far depth to
[0, 1]; upstream uses left-handed coordinates and [-1, 1]. Both
perspectiveRH and perspectiveLH use [0, 1] depth.Float2, vector of 2 floatsFloat3, vector of 3 floatsFloat4, vector of 4 floatsHalf2, vector of 2 half-precision floatsHalf3, vector of 3 half-precision floatsHalf4, vector of 4 half-precision floatsBool2, vector of 2 booleansBool3, vector of 3 booleansBool4, vector of 4 booleans