vmath/README.md

142 lines
5.6 KiB
Markdown
Raw Normal View History

<img src="docs/banner.png">
2023-05-12 05:15:07 +00:00
# VMath - 2D and 3D vector math.
2021-09-30 23:57:26 +00:00
`nimble install vmath`
2021-05-31 20:45:45 +00:00
![Github Actions](https://github.com/treeform/vmath/workflows/Github%20Actions/badge.svg)
2023-05-11 00:35:15 +00:00
[API reference](https://treeform.github.io/vmath)
2021-09-30 23:57:26 +00:00
2022-06-20 20:10:02 +00:00
This library has no dependencies other than the Nim standard library.
2021-09-30 23:57:26 +00:00
2023-05-12 05:15:07 +00:00
Supports c, cpp and js backend.
2021-09-30 23:57:26 +00:00
## About
2020-11-29 22:55:52 +00:00
2021-05-31 20:44:19 +00:00
Your one stop shop for vector math routines for 2d and 3d graphics.
2021-05-31 20:44:19 +00:00
* Pure Nim with no dependencies.
* Very similar to GLSL Shader Language with extra stuff.
* Extensively [benchmarked](tests/bench_raytracer.nim).
2021-05-31 20:44:19 +00:00
## Has vector functions for GLSL types:
Type | Constructor | Description
------|-------------| ---------------------------------------------------
BVec# | bvec# | a vector of booleans
IVec# | ivec# | a vector of signed integers
UVec# | uvec# | a vector of unsigned integers
Vec# | vec# | a vector of single-precision floating-point numbers
DVec# | dvec# | a vector of double-precision floating-point numbers
You can use these constructors to make them:
NIM | GLSL | 2 | 3 | 4 | 9 | 16 | 4 |
--------|--------|-------|-------|-------|-------|-------|-------|
bool | bool | BVec2 | BVec3 | BVec4 | | | |
int32 | int | IVec2 | IVec3 | IVec4 | | | |
uint32 | uint | UVec2 | UVec3 | UVec4 | | | |
float32 | float | Vec2 | Vec3 | Vec4 | Mat3 | Mat4 | Quat |
float64 | double | DVec2 | DVec3 | DVec4 | DMat3 | DMat4 | DQuat |
2021-05-31 20:44:19 +00:00
## 2D & 3D matrix math
2021-05-29 23:33:03 +00:00
You can combine and create 2d and 3d matrices by passing 2d or 3d vectors to matrix functions:
2019-10-17 14:42:23 +00:00
```nim
let mat2d = translate(vec2(10, 20)) * rotate(45.toRadians) * scale(vec2(2))
let mat3d = translate(vec3(10, 20, 0)) * rotateZ(45.toRadians) * scale(vec3(2))
2019-10-17 14:42:23 +00:00
```
## Almost equal operator
2019-10-17 14:42:23 +00:00
2021-05-31 20:44:19 +00:00
Easily check if floating point numbers are close, very useful for tests:
2019-10-17 14:42:23 +00:00
```nim
1.0 ~= 1.0
2021-05-29 23:33:03 +00:00
vec2(1.0, 2.0) ~= vec2(1.0, 2.0)
dvec2(1) ~= dvec2(1)
quat(1.0, 2.0, 3.0, 4.0) ~= quat(1.0, 2.0, 3.0, 4.0)
2019-10-17 14:42:23 +00:00
```
## Number functions
2019-10-17 14:42:23 +00:00
* `between` - Returns true if value is between min and max or equal to them.
* `sign` - Returns the sign of a number, -1 or 1.
2021-05-31 20:44:19 +00:00
* `quantize` - Makes v be a multiple of n. Rounding to integer quantize by 1.0.
* `fractional` - Returns fractional part of a number. 3.14 -> 0.14
* `lerp` - Interpolates value between a and b.
2019-10-17 14:42:23 +00:00
## Angle functions
2019-10-17 14:42:23 +00:00
* `fixAngle` - Make angle be from -PI to PI radians.
2021-05-31 20:44:19 +00:00
* `angleBetween` - Find the angle between angle a and angle b.
* `turnAngle` - Move from angle a to angle b with step of v.
2019-10-17 14:42:23 +00:00
2021-05-31 20:44:19 +00:00
## Vector and matrix representation and benchmarks.
2021-05-29 18:42:46 +00:00
2021-05-31 20:44:19 +00:00
C compilers seem to optimize different representations differently. This is very surprising for us and vmath has 3 different implementations:
2021-05-29 18:42:46 +00:00
* `-d:vmathObjBased` - A vector is an object of 3 floats.
2021-05-31 20:44:19 +00:00
* `-d:vmathArrayBased` - A vector is an array of 3 floats.
2021-05-29 18:42:46 +00:00
* `-d:vmathObjArrayBased` (default) - A vector is an object that has an array of 3 floats.
```
name ............................... min time avg time std dv runs
vmathObjBased ..................... 74.061 ms 74.297 ms ±0.347 x100
vmathArrayBased ................... 89.498 ms 89.911 ms ±1.019 x100
vmathObjArrayBased ................ 73.968 ms 74.292 ms ±0.631 x100
```
2021-05-29 18:46:49 +00:00
* [3d Ray Trace Benchmark](tests/bench_raytracer.nim)
2022-07-24 17:46:30 +00:00
* [2d SVG Render Benchmark](https://github.com/treeform/pixie/blob/master/tests/bench_svg.nim)
2021-05-29 18:42:46 +00:00
2023-03-04 20:57:17 +00:00
## Zmod - GLSL mod
GLSL uses a different type of float point mod. Because mod is a Nim keyword please use `zmod` when you need GLSL `mod` behavior.
## Coordinate System
Right-hand z-forward coordinate system
This is the same system used in the GLTF file format.
> glTF uses a right-handed coordinate system.
> glTF defines +Y as up, +Z as forward, and -X as right;
> the front of a glTF asset faces +Z.
[glTF Spec 2.0](https://registry.khronos.org/glTF/specs/2.0/glTF-2.0.html#coordinate-system-and-units)
## OpenGL matrix column-major notation.
> [9.005](https://www.opengl.org/archives/resources/faq/technical/transformations.htm) For programming purposes, OpenGL matrices are 16-value arrays with base vectors laid out contiguously in memory. The translation components occupy the 13th, 14th, and 15th elements of the 16-element matrix, where indices are numbered from 1 to 16 as described in section 2.11.2 of the [OpenGL 2.1 Specification](https://registry.khronos.org/OpenGL/specs/gl/glspec21.pdf).
>
> Sadly, the use of column-major format in the spec and blue book has resulted in endless confusion in the OpenGL programming community. Column-major notation suggests that matrices are not laid out in memory as a programmer would expect.
OpenGL/GLSL/vmath vs Math/Specification notation:
```
mat4([
a, b, c, 0, | a d g x |
d, e, f, 0, | b e h y |
g, h, i, 0, | c f i z |
x, y, z, 1 | 0 0 0 1 |
])
```
# 1.x.x to 2.0.0 vmath breaking changes:
* New right-hand-z-forward cordate system and functions that care about
coordinate system where moved there.
* deprecated `lookAt()` please use `toAngles()`/`fromAngles()` instead.
* deprecated `fractional()` use `frac()` instead.
# 0.x.x to 1.0.0 vmath breaking changes:
2019-10-17 14:42:23 +00:00
* `vec3(v)` no longer works please use `vec3(v.x, v.y, 0)` instead.
* `vec3(v, 0)` no longer works please use `vec3(v.x, v.y, 0)` instead.
* `2 * v` no longer works due to more vec types please use `v * 2` instead.
* `m[15]` no longer works because matrices are now m[x, y].
* Concept of 3x3 rotation 3d matrix was removed.
* `angleBetween` got renamed to `angle(a, b)`
* `scaleMat` got renamed to `scale(v)`
* `rotationMat3` got renamed to `rotate(x)`