Sol

0.4.0

Sol exposes fully portable vector operations for C and Nim that use SIMD when possible, but use scalar operations otherwise.

Examples

First, a simple example in C:

#include <stdio.h>
#include <sol/sol.h>

int main() {
  f32x2 v = f32x2_set(0, 1);      // Initialize a vector at x = 0, y = 1.
  v = f32x2_rot(v, f32_pi);       // Rotate by pi radians counterclockwise. (180 degrees.)
  printf("%f, %f\n", x(v), y(v)); // Prints 0, -1.
  x(v) = 5;                       // Setting can also be done via the scalar accessor; it is a macro, not a function.
  printf("%f, %f\n", x(v), y(v)); // Prints 5, -1.
  return 0;
}

And the same thing in Nim:

import sol

var v: float32x2 = f32x2(0, 1) # Here more idiomatic names like "float32x2" are used for types. "f32x2" is analogous to "f32x2_set".
v = v.rot(f32_pi)              # Functions are overloaded instead of having the type name in them, for brevity.
echo v                         # Stringify is overloaded for the vector types; no need to format.
v.x = 5
echo v

Documentation

Types

Scalars

C Sol exposes the scalar types f32, f64, i8, i16, i32, i64, u8, u16, u32, and u64. The reason for these new names is because ARM NEON SIMD intrinsics already used the names float32x2_t and such, and I didn't want the name to be similar to those.

In Nim, the existing scalar types are used-- float32, float64, int8, int16, int32, int64, uint8, uint16, uint32, and uint64.

Vectors

All of the vector types in C are broken down into the name format TxW, where T is the scalar type being vectored and W is the width of the vector. For instance, f64x3 is a 3-wide vector of f64s. As it stands, 2- 3- and 4-wide vectors exist for each scalar type.

Nim is the same, but with the corresponding scalar names; for example, f64x3 is instead float64x3.

Functions & Constants

Scalars

The C scalar function names are of the form T_f, where T is the scalar type you are working with and f is the name of the function. For example, f32_cos is cos for f32.

The scalar constants and functions in Nim retain the same prefixes, f32 and the like. I would overload them, but the names already exist with the same type signature in Nim's math library, so it seems like more headache to try to be clean with naming here.

Vectors

The nim names are a bit different:

• TxW_set is now written just TxW, where T is named as if it were in C. f32x2_set becomes f32x2, for instance.
• TxW_setf is not available in Nim.
• TxW_add, TxW_addf, TxW_sub, TxW_subf, TxW_fsub, TxW_mul, TxW_mulf, TxW_div, TxW_divf, and TxW_fdiv are all just their symbolic operators now. f32x2_add(a, b) becomes a + b, for instance. As operators, mulf and addf may also be called "backwards" now, like 2 * v.
• TxW_sum and TxW_sq drop their prefix and are simply overloaded. For instance, f32x2_sum(f32x2_set(1, 0)) is instead sum(f32x2(1, 0)) or f32x2(1, 0).sum.
• Simple op= operators are supported, so you may do += and the like.
• All vectors have $ defined, so they may be converted to a string.
• Vector lane set is now written v.x = 5 rather x(v) = 5.
• Thanks to Nim UFCS, vector lane get can be written v.x now rather than x(v)-- but you can do either.

Floating 2D Vectors

T here is either f32 or f64.

In Nim, the prefixes for all of these functions are dropped and they are simply overloaded.

Floating 3D Vectors

In Nim, the prefixes for all of these functions are dropped and they are simply overloaded.

Floating 4D Vectors

In Nim, the prefixes for all of these functions are dropped and they are simply overloaded.