simd

Vector of 16 b16 lanes (256 bits).

Vector of 32 b16 lanes (512 bits).

Vector of 8 b16 lanes (128 bits).

Vector of 16 b32 lanes (512 bits).

Vector of 4 b32 lanes (128 bits).

Vector of 8 b32 lanes (256 bits).

Vector of 2 b64 lanes (128 bits).

Vector of 4 b64 lanes (256 bits).

Vector of 8 b64 lanes (512 bits).

Vector of 16 b8 lanes (128 bits).

Vector of 32 b8 lanes (256 bits).

Vector of 64 b8 lanes (512 bits).

Vector of 16 bool lanes (128 bits).

Vector of 32 bool lanes (256 bits).

Vector of 64 bool lanes (512 bits).

Vector of 16 f32 lanes (512 bits).

Vector of 4 f32 lanes (128 bits).

Vector of 8 f32 lanes (256 bits).

Vector of 2 f64 lanes (128 bits).

Vector of 4 f64 lanes (256 bits).

Vector of 8 f64 lanes (512 bits).

Vector of 16 i16 lanes (256 bits).

Vector of 32 i16 lanes (512 bits).

Vector of 8 i16 lanes (128 bits).

Vector of 16 i32 lanes (512 bits).

Vector of 4 i32 lanes (128 bits).

Vector of 8 i32 lanes (256 bits).

Vector of 2 i64 lanes (128 bits).

Vector of 4 i64 lanes (256 bits).

Vector of 8 i64 lanes (512 bits).

Vector of 16 i8 lanes (128 bits).

Vector of 32 i8 lanes (256 bits).

Vector of 64 i8 lanes (512 bits).

Vector of 16 u16 lanes (256 bits).

Vector of 32 u16 lanes (512 bits).

Vector of 8 u16 lanes (128 bits).

Vector of 16 u32 lanes (512 bits).

Vector of 4 u32 lanes (128 bits).

Vector of 8 u32 lanes (256 bits).

Vector of 2 u64 lanes (128 bits).

Vector of 4 u64 lanes (256 bits).

Vector of 8 u64 lanes (512 bits).

Vector of 16 u8 lanes (128 bits).

Vector of 32 u8 lanes (256 bits).

Vector of 64 u8 lanes (512 bits).

Check if SIMD is software-emulated on a target platform.

This value is true, when the compile-time target has the hardware support for at least 128-bit (or wider) SIMD. If the compile-time target lacks the hardware support for 128-bit SIMD, this value is false, and all SIMD operations will likely be emulated.

Absolute value of a SIMD vector.

This procedure returns a vector where each lane has the absolute value of the corresponding lane in the vector a.

Inputs:

• a: An integer or a float vector to negate

Returns:

• The absolute value of a vector.

Operation:

for i in 0 ..< len(res) {
	switch {
		case a[i] < 0:  res[i] = -a[i]
		case a[i] > 0:  res[i] = a[i]
		case a[i] == 0: res[i] = 0
	}
}
return res

Example:

   +------+------+------+------+
a: |   0  |  -1  |   2  |  -3  |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Add SIMD vectors.

This procedure returns a vector, where each lane holds the sum of the corresponding a and b vectors' lanes.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector that is the sum of two input vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] + b[i]
}
return res

Example:

   +-----+-----+-----+-----+
a: |  0  |  1  |  2  |  3  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  0  |  1  |  2  | -1  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Bitwise AND of vectors.

This procedure returns a vector, such that each lane has the result of a bitwise AND operation between the corresponding lanes of the vectors a and b.

Inputs:

• a: An integer or a boolean vector.
• b: An integer or a boolean vector.

Returns:

• A vector that is the result of the bitwise AND operation between two vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] & b[i]
}
return res

Example:

   +------+------+------+------+
a: | 0x11 | 0x33 | 0x55 | 0xaa |
   +------+------+------+------+
   +------+------+------+------+
b: | 0xff | 0xf0 | 0x0f | 0x00 |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Bitwise AND NOT of vectors.

This procedure returns a vector, such that each lane has the result of a bitwise AND NOT operation between the corresponding lanes of the vectors a and b.

Inputs:

• a: An integer or a boolean vector.
• b: An integer or a boolean vector.

Returns:

• A vector that is the result of the bitwise AND NOT operation between two vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] &~ b[i]
}
return res

Example:

   +------+------+------+------+
a: | 0x11 | 0x33 | 0x55 | 0xaa |
   +------+------+------+------+
   +------+------+------+------+
b: | 0xff | 0xf0 | 0x0f | 0x00 |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Bitwise OR of vectors.

This procedure returns a vector, such that each lane has the result of a bitwise OR operation between the corresponding lanes of the vectors a and b.

Inputs:

• a: An integer or a boolean vector.
• b: An integer or a boolean vector.

Returns:

• A vector that is the result of the bitwise OR operation between two vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] | b[i]
}
return res

Example:

   +------+------+------+------+
a: | 0x11 | 0x33 | 0x55 | 0xaa |
   +------+------+------+------+
   +------+------+------+------+
b: | 0xff | 0xf0 | 0x0f | 0x00 |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Bitwise XOR of vectors.

This procedure returns a vector, such that each lane has the result of a bitwise XOR operation between the corresponding lanes of the vectors a and b.

Inputs:

• a: An integer or a boolean vector.
• b: An integer or a boolean vector.

Returns:

• A vector that is the result of the bitwise XOR operation between two vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] ~ b[i]
}
return res

Example:

   +------+------+------+------+
a: | 0x11 | 0x33 | 0x55 | 0xaa |
   +------+------+------+------+
   +------+------+------+------+
b: | 0xff | 0xf0 | 0x0f | 0x00 |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Swap the bytes of the elements of a SIMD vector.

Ceil each lane in a SIMD vector.

Clamp lanes of vector.

This procedure returns a vector, where each lane is the result of the clamping of the lane from the vector v between the values in the corresponding lanes of vectors min and max.

Inputs:

• v: An integer or a float vector with values to be clamped.
• min: An integer or a float vector with minimum bounds.
• max: An integer or a float vectoe with maximum bounds.

Returns:

• A vector containing clamped values in each lane.

Operation:

for i in 0 ..< len(res) {
	val := v[i]
	switch {
		case val < min: val = min
		case val > max: val = max
	}
	res[i] = val
}
return res

Example:

     +-------+-------+-------+-------+
v:   |  -1   |  0.3  |  1.2  |   1   |
     +-------+-------+-------+-------+
     +-------+-------+-------+-------+
min: |   0   |   0   |   0   |   0   |
     +-------+-------+-------+-------+
     +-------+-------+-------+-------+
max: |   1   |   1   |   1   |   1   |
     +-------+-------+-------+-------+
res:
     +-------+-------+-------+-------+

     +-------+-------+-------+-------+

Count the number of leading unset bits in each lane of a SIMD vector.

Count the number of set bits in each lane of a SIMD vector.

Count the number of trailing unset bits in each lane of a SIMD vector.

Count the number of unset bits in each lane of a SIMD vector.

Divide SIMD vectors.

This procedure returns a vector, where each lane holds the quotient (result of division) between the corresponding lanes of the vectors a and b. Each lane of the vector a is divided by the corresponding lane of the vector b.

This operation performs a standard floating-point division for each lane.

Inputs:

• a: A float vector.
• b: A float vector to divide by.

Returns:

• A vector that is the quotient of two vectors, a / b.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] / b[i]
}
return res

Example:

   +-----+-----+-----+-----+
a: |  2  |  2  |  2  |  2  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  0  | -1  |  2  | -3  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+------+

   +-----+-----+-----+------+

Extract scalar from a vector's lane.

This procedure returns the scalar from the lane at the specified index of the vector.

Inputs:

• a: The vector to extract from.
• idx: The lane index.

Returns:

• The value of the lane at the specified index.

Operation:

return a[idx]

Extract the set of least-significant bits of a SIMD vector.

This procedure checks the least-significant bit (LSB) for each lane of vector and returns the numbers of lanes with the least-significant bit set. This procedure can be used in conjuction with lanes_eq (and other similar procedures) to count the number of matched lanes by computing the cardinality of the resulting set.

Inputs:

• a: An input vector.

Result:

• A bitset of integers, corresponding to the indexes of the lanes, whose LSBs

are set.

Operation:

res = bit_set {}
for i in 0 ..< len(a) {
	if a[i] & 1 != 0 {
		res |= i
	}
}
return res

Example:

// Since lanes 0, 2, 4, 6 contain odd integers, the least significant bits
// for these lanes are set.

import "core:fmt"
import "core:simd"

simd_extract_lsbs_example :: proc() {
	v := #simd [8]i32 { -1, -2, +3, +4, -5, +6, +7, -8 }
	fmt.println(simd.extract_lsbs(v))
}

Output:

bit_set[0..=7]{0, 2, 4, 6}

Extract the set of most-significant bits of a SIMD vector.

This procedure checks the most-significant bit (MSB) for each lane of vector and returns the numbers of lanes with the most-significant bit set. This procedure can be used in conjuction with lanes_eq (and other similar procedures) to count the number of matched lanes by computing the cardinality of the resulting set.

Inputs:

• a: An input vector.

Result:

• A bitset of integers, corresponding to the indexes of the lanes, whose MSBs

are set.

Operation:

bits_per_lane = 8*size_of(a[0])
res = bit_set {}
for i in 0 ..< len(a) {
	if a[i] & 1<<(bits_per_lane-1) != 0 {
		res |= i
	}
}
return res

Example:

// Since lanes 0, 1, 4, 7 contain negative numbers, the most significant
// bits for them will be set.

import "core:fmt"
import "core:simd"

simd_extract_msbs_example :: proc() {
	v := #simd [8]i32 { -1, -2, +3, +4, -5, +6, +7, -8 }
	fmt.println(simd.extract_msbs(v))
}

Output:

bit_set[0..=7]{0, 1, 4, 7}

Floor each lane in a SIMD vector.

Perform a FMA (Fused multiply-add) operation on each lane of SIMD vectors.

A fused multiply-add is a ternary operation that for three operands, a, b and c performs the operation a*b+c. This operation is a hardware feature that allows to minimize floating-point error and allow for faster computation.

This procedure performs a FMA operation on each lane of the SIMD vectors.

Inputs:

• a: The multiplier.
• b: The multiplicand.
• c: The addend.

Returns:

• a*b+c

Operation

res := 0
	for i in 0 ..< len(a) {
		res[i] = fma(a[i], b[i], c[i])
	}
	return res

Perform a FMA (Fused multiply-add) operation on each lane of SIMD vectors.

A fused multiply-add is a ternary operation that for three operands, a, b and c performs the operation a*b+c. This operation is a hardware feature that allows to minimize floating-point error and allow for faster computation.

This procedure performs a FMA operation on each lane of the SIMD vectors.

Inputs:

• a: The multiplier
• b: The multiplicand
• c: The addend

Returns:

• a*b+c

Operation

res := 0
	for i in 0 ..< len(a) {
		res[i] = fma(a[i], b[i], c[i])
	}
	return res

Perform a gather load into a vector.

A gather operation is memory load operation, that loads values from an vector of addresses into a single value vector. This can be used to achieve the following results:

• Accessing every N'th element of an array (strided access)
• Access of elements according to some computed offsets (indexed access).
• Access of elements in a different order (shuffling access).

When used alongside other SIMD procedures in order to compute the offsets for the ptr and mask parameters.

Inputs:

• ptr: A vector of memory locations. Each pointer points to a single value,

of a SIMD vector's lane type that will be loaded into the vector. Pointer
	in this vector can be `nil` or any other invalid value, if the corresponding
	value in the `mask` parameter is zero.
- `val`: A vector of values that will be used at corresponding positions
	of the result vector, if the corresponding memory location has been
	masked out.
- `mask`: A vector of booleans or unsigned integers that determines which memory
	locations to read from. If the value at an index has the value true
	(lowest bit set), the value at that index will be loaded into the result
	vector from the corresponding memory location in the `ptr` vector. Otherwise
	the value will be loaded from the `val` vector.

Returns:
- A vector with all values from unmasked indices
loaded from the pointer vector `ptr`, and all values from masked indices loaded
from the value vector `val`.

Operation:

	for i in 0 ..< len(res) {
		if mask[i]&1 == 1 {
			res[i] = ptr[i]^
		} else {
			res[i] = val[i]
		}
	}
	return res

Example:

	// Example below loads 2 lanes of values from 2 lanes of float vectors, `v1` and
	// `v2`. From each of these vectors we're loading the second value, into the first
	// and the third position of the result vector.

	// Therefore the `ptrs` argument is initialized such that the first and the third
	// value are the addresses of the values that we want to load into the result
	// vector, and we'll fill in `nil` for the rest of them. To prevent CPU from
	// dereferencing those `nil` addresses we provide the mask that only allows us
	// to load valid positions of the `ptrs` array, and the array of defaults which
	// will have `127` in each position as the default value.

	import "core:fmt"
	import "core:simd"

	simd_gather_example :: proc() {
		v1 := [4] f32 {1, 2, 3, 4};
		v2 := [4] f32 {9, 10,11,12};
		ptrs := #simd [4]rawptr { &v1[1], nil, &v2[1], nil }
		mask := #simd [4]bool { true, false, true, false }
		defaults := #simd [4]f32 { 0x7f, 0x7f, 0x7f, 0x7f }
		res := simd.gather(ptrs, defaults, mask)
		fmt.println(res)
	}

Output:

	<2, 127, 10, 127>

The first and the third positions came from the `ptrs` array, and the other
2 lanes of from the default vector. The graphic below shows how the values of
the result are decided based on the mask:

	      +-------------------------------+ 
	mask: |   1   |   0   |   1   |   0   | 
	      +-------------------------------+ 
	        |         |       |       `----------------------------.
	        |         |       |                                    |
	        |          `----  |  ------------------------.         |
	        v                 v                          v         v
	      +-------------------------------+       +-------------------+
	ptrs: |  &m0  |  nil  |  &m2  |  nil  | vals: | d0 | d1 | d2 | d3 |
	      +-------------------------------+       +-------------------+
	          |               |                          |         |
	          |          .--- | -------------------------'         |
	          |         |     |          ,-------------------------'
	          v         v     v         v
	        +-------------------------------+
	result: |   m0  |   d1  |   m2  |  d3   |
	        +-------------------------------+

Create a vector where each lane contains the index of that lane. Inputs:

• V: The type of the vector to create.

Result:

• A vector of the given type, where each lane contains the index of that lane.

Operation:

for i in 0 ..< N {
	res[i] = i
}

Create a vector where each lane contains the index of that lane. Inputs:

• V: The type of the vector to create.

Result:

• A vector of the given type, where each lane contains the index of that lane.

Operation:

for i in 0 ..< N {
	res[i] = i
}

Check if lanes of vectors are equal.

This procedure checks each pair of lanes from vectors a and b for whether they are equal, and if they are, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer, a float or a boolean vector.
• b: An integer, a float or a boolean vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] == b[i] {
		res[i] = max(T)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+

   +-------+-------+-------+-------+

Check if lanes of a vector are greater than or equal than another. SIMD vector.

This procedure checks each pair of lanes from vectors a and b for whether the lane of a is greater than or equal to the lane of b, and if so, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] >= b[i] {
		res[i] = unsigned(-1)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+

   +-------+-------+-------+-------+

Check if lanes of a vector are greater than another. vector.

This procedure checks each pair of lanes from vectors a and b for whether the lane of a is greater than to the lane of b, and if so, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] > b[i] {
		res[i] = unsigned(-1)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+

   +-------+-------+-------+-------+

Check if lanes of a vector are less than or equal than another. SIMD vector.

This procedure checks each pair of lanes from vectors a and b for whether the lane of a is less than or equal to the lane of b, and if so, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] <= b[i] {
		res[i] = unsigned(-1)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+

   +-------+-------+-------+-------+

Check if lanes of a vector are less than another.

This procedure checks each pair of lanes from vectors a and b for whether the lane of a is less than the lane of b, and if so, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] < b[i] {
		res[i] = unsigned(-1)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+
r: | 0x00  | 0xff  | 0x00  | 0x00  |
   +-------+-------+-------+-------+

Check if lanes of vectors are not equal.

This procedure checks each pair of lanes from vectors a and b for whether they are not equal, and if they are, the corresponding lane of the result vector will have a value with all bits set (0xff..ff). Otherwise the lane of the result vector will have the value 0.

Inputs:

• a: An integer, a float or a boolean vector.
• b: An integer, a float or a boolean vector.

Returns:

• A vector of unsigned integers of the same size as the input vector's lanes,

containing the comparison results for each lane.

Operation:

for i in 0 ..< len(res) {
	if a[i] != b[i] {
		res[i] = unsigned(-1)
	} else {
		res[i] = 0
	}
}
return res

Example:

   +-------+-------+-------+-------+
a: |   0   |   1   |   2   |   3   |
   +-------+-------+-------+-------+
   +-------+-------+-------+-------+
b: |   0   |   2   |   2   |   2   |
   +-------+-------+-------+-------+
res:
   +-------+-------+-------+-------+

   +-------+-------+-------+-------+

Reverse the lanes of a SIMD vector.

This procedure reverses the lanes of a vector, putting last lane in the first spot, etc. This procedure is equivalent to the following call (for 4-element vectors):

swizzle(a, 3, 2, 1, 0)

Rotate the lanes of a SIMD vector left.

This procedure rotates the lanes of a vector, putting the first lane of the last spot, second lane in the first spot, third lane in the second spot, etc. For 4-element vectors, this procedure is equvalent to the following:

swizzle(a, 1, 2, 3, 0)

Rotate the lanes of a SIMD vector right.

This procedure rotates the lanes of a SIMD vector, putting the first lane of the second spot, second lane in the third spot, etc. For 4-element vectors, this procedure is equvalent to the following:

swizzle(a, 3, 0, 1, 2)

Store masked values to consecutive memory locations.

This procedure stores values from masked lanes of a vector val consecutively into memory. This operation is the opposite of masked_expand_load. The number of items stored into memory is the number of set bits in the mask. If the value in a lane of a mask is true, that lane is stored into memory. Otherwise nothing is stored.

Inputs:

• ptr: The pointer to the memory of a store.
• val: The vector to store into memory.
• mask: The mask that selects which values to store into memory.

Operation:

mem_idx := 0
for i in 0 ..< len(mask) {
	if mask[i]&1 == 1 {
		ptr[mem_idx] = val[i]
		mem_idx += 1
	}
}

Example:

// The code below fills the vector `v` with two values from a 4-element SIMD
// vector, the first and the third value. The items in the mask are set to `true`
// in those lanes.

import "core:fmt"
import "core:simd"

simd_masked_compress_store_example :: proc() {
	v := [2] f64 { };
	mask := #simd [4]bool { true, false, true, false }
	vals := #simd [4]f64 { 1, 2, 3, 4 }
	simd.masked_compress_store(&v, vals, mask)
	fmt.println(v)
}

Output:

[1, 3]

Graphical representation of the operation:

      +-------------------+
	mask: | 1  | 0  | 1  | 0  |
	      +-------------------+
	        |         |
	        v         v
	      +-------------------+
	vals: | v0 | v1 | v2 | v3 |
	      +-------------------+
	        |      ,--'
	ptr     v     v
	 +--->+-----------------
	      | v0  | v2  | ...
	      +-----------------

Load consecutive scalar values and expand into a vector.

This procedure loads a number of consecutive scalar values from an address, specified by the ptr parameter, and stores them in a result vector, according to the mask. The number of values read from memory is the number of set bits in the mask. The lanes for which the mask has the value true get the next consecutive value from memory, otherwise if the mask is false for the lane, its value is filled from the corresponding lane of the val parameter.

This procedure acts like masked_store, except the values from memory are read consecutively, and not according to the lanes. The memory values are read and assigned to the result vector's masked lanes in order of increasing addresses.

Inputs:

• ptr: The pointer to the memory to read from.
• vals: The default values for masked-off entries.
• mask: The mask that determines which lanes get consecutive memory values.

Returns:

• The result vector, holding masked memory values unmasked default values.

Operation:

mem_idx := 0
for i in 0 ..< len(mask) {
	if mask[i]&1 == 1 {
		res[i] = ptr[mem_idx]
		mem_idx += 1
	} else {
		res[i] = val[i]
	}
}
return res

Example:

// The example below loads two values from memory of the vector `v`. Two values in
// the mask are set to `true`, meaning only two memory items will be loaded into
// the result vector. The mask is set to `true` in the first and the third
// position, which specifies that the first memory item will be read into the
// first lane of the result vector, and the second memory item will be read into
// the third lane of the result vector. All the other lanes of the result vector
// will be initialized to the default value `127`.

import "core:fmt"
import "core:simd"

simd_masked_expand_load_example :: proc() {
	v := [2] f64 {1, 2};
	mask := #simd [4]bool { true, false, true, false }
	vals := #simd [4]f64 { 0x7f, 0x7f, 0x7f, 0x7f }
	res := simd.masked_expand_load(&v, vals, mask)
	fmt.println(res)
}

Output:

<1, 127, 2, 127>

Graphical representation of the operation:

ptr --->+-----------+-----
	        | m0  | m1  | ...
	        +-----------+-----
	          |      `--.
	          v         v
	        +-------------------+         +-------------------+
	mask:   | 1  | 0  | 1  | 0  |   vals: | v0 | v1 | v2 | v3 |
	        +-------------------+         +-------------------+
	          |         |                         |         |
	          |     .-- | -----------------------'          |
	          |    |    |     ,----------------------------'
	          v    v    v    v
	        +-------------------+
	result: | m0 | v1 | m1 | v3 |
	        +-------------------+

Perform a masked load into the vector.

This procedure performs a masked load from memory, into the vector. The ptr argument specifies the base address from which the values of the vector will be loaded. The mask selects the source for the result vector's lanes. If the mask for the corresponding lane has the value true (lowest bit set), the result lane is loaded from memory. Otherwise the result lane is loaded from the corresponding lane of the val vector.

Inputs:

• ptr: The address of the vector values to load. Masked-off values are not

accessed.
- `val`: The vector of values that will be loaded into the masked slots of the
	result vector.
- `mask`: The mask that selects where to load the values from.

Returns:
- The loaded vector. The lanes for which the mask was set are loaded from
memory, and the other lanes are loaded from the `val` vector.

Operation:

	for i in 0 ..< len(res) {
		if mask[i]&1 == 1 {
			res[i] = ptr[i]
		} else {
			res[i] = vals[i]
		}
	}
	return res

Example:

	// The following code loads two values from the `src` vector, the first and the
	// third value (selected by the mask). The masked-off values are given the value
	// of 127 (`0x7f`).

	import "core:fmt"
	import "core:simd"

	simd_masked_load_example :: proc() {
		src := [4] f32 {1, 2, 3, 4};
		mask := #simd [4]bool { true, false, true, false }
		vals := #simd [4]f32 { 0x7f, 0x7f, 0x7f, 0x7f }
		res := simd.masked_load(&src, vals, mask)
		fmt.println(res)
	}

Output:

	<1, 127, 3, 127>

The graphic below demonstrates the flow of lanes.

	      +-------------------------------+ 
	mask: |   1   |   0   |   1   |   0   | 
	      +-------------------------------+ 
	        |         |       |       `----------------------------.
	        |         |       |                                    |
	        |          `----  |  ------------------------.         |
	ptr     v                 v                          v         v
	+---->+-------------------------------+       +-------------------+
	      |   v1  |   v2  |   v3  |   v4  | vals: | d0 | d1 | d2 | d3 |
	      +-------------------------------+       +-------------------+
	          |               |                          |         |
	          |          .--- | -------------------------'         |
	          |         |     |          ,-------------------------'
	          v         v     v         v
	        +-------------------------------+
	result: |  v1   |   d1  |  v3   |  d3   |
	        +-------------------------------+

Perform a masked store to memory.

This procedure performs a masked store from a vector val, into memory at address ptr, with the mask deciding which lanes are going to be stored, and which aren't. If the mask at a corresponding lane has the value true (lowest bit set), the lane is stored into memory. Otherwise the lane is not stored into memory.

Inputs:

• ptr: The base address of the store.
• val: The vector to store.
• mask: The mask, selecting which lanes of the vector to store into memory.

Operation:

for i in 0 ..< len(val) {
	if mask[i]&1 == 1 {
		ptr[i] = val
	}
}

Example:

// Example below stores the value 127 into the first and the third slot of the
// vector `v`.

import "core:fmt"
import "core:simd"

simd_masked_store_example :: proc() {
	v := [4] f32 {1, 2, 3, 4};
	mask := #simd [4]bool { true, false, true, false }
	vals := #simd [4]f32 { 0x7f, 0x7f, 0x7f, 0x7f }
	simd.masked_store(&v, vals, mask)
	fmt.println(v)
}

Output:

[127, 2, 127, 4]

The graphic below shows the flow of lanes:

      +-------------------+
	mask: | 1  | 0  | 1  | 0  |
	      +-------------------+
	        |    |    |    |
	        v    X    v    X
	      +-------------------+
	vals: | v0 | v1 | v2 | v3 |
	      +-------------------+
	         |         \
	ptr      v          v
	 +--->+-----------------------+
	      | v0  | ... | v2  | ... |
	      +-----------------------+

Maximum of each lane of vectors.

This procedure returns a vector, such that each lane has the maximum value between the corresponding lanes in vectors a and b.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector containing with maximum values from corresponding lanes of a and b.

Operation:

for i in 0 ..< len(res) {
	if a[i] > b[i] {
		res[i] = a[i]
	} else {
		res[i] = b[i]
	}
}
return res

Example:

   +-----+-----+-----+-----+
a: |  0  |  1  |  2  |  3  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  0  |  2  |  1  | -1  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Minimum of each lane of vectors.

This procedure returns a vector, such that each lane has the minimum value between the corresponding lanes in vectors a and b.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector containing with minimum values from corresponding lanes of a and b.

Operation:

for i in 0 ..< len(res) {
	if a[i] < b[i] {
		res[i] = a[i]
	} else {
		res[i] = b[i]
	}
}
return res

Example:

   +-----+-----+-----+-----+
a: |  0  |  1  |  2  |  3  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  0  |  2  |  1  | -1  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Multiply (component-wise) SIMD vectors.

This procedure returns a vector, where each lane holds the product of the corresponding lanes of the vectors a and b.

Inputs:

• a: An integer or a float vector.
• b: An integer or a float vector.

Returns:

• A vector that is the product of two vectors.

Operation:

for i in 0 ..< len(res) {
	res[i] = a[i] * b[i]
}
return res

Example:

   +-----+-----+-----+-----+
a: |  2  |  2  |  2  |  2  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  0  | -1  |  2  | -3  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Compute the nearest integer of each lane in a SIMD vector.

Negation of a SIMD vector.

This procedure returns a vector where each lane is the negation of the corresponding lane in the vector a.

Inputs:

• a: An integer or a float vector to negate.

Returns:

• The negated version of the vector a.

Operation:

for i in 0 ..< len(res) {
	res[i] = -a[i]
}
return res

Example:

   +------+------+------+------+
a: |   0  |   1  |   2  |   3  |
   +------+------+------+------+
res:
   +------+------+------+------+

   +------+------+------+------+

Operation

assert(len(a) == len(b))

res := 0
	N :: len(a)
	for i in 0 ..< N/2 {
		res[i] = a[2*i + 1]
	}
	for i in 0 ..< N/2 {
		res[i + N/2] = b[2*i]
	}
	return res

Reduce a vector to a scalar by adding up all the lanes in a bisecting fashion.

This procedure returns a scalar that is the sum of all lanes, calculated by bisecting the vector into two parts, where the first contains lanes [0, N/2) and the second contains lanes [N/2, N), and adding the two halves element-wise to produce N/2 values. This is repeated until only a single element remains. This order may be faster to compute than the ordered sum for floats, as it can often be better parallelized.

The order of the sum may be important for accounting for precision errors in floating-point computation, as floating-point addition is not associative, that is (a+b)+c may not be equal to a+(b+c).

Inputs:

• v: The vector to reduce.

Result:

• Sum of all lanes, as a scalar.

Operation:

for n > 1 {
	n = n / 2
	for i in 0 ..< n {
		a[i] += a[i+n]
	}
}
res := a[0]

Graphical representation of the operation for N=4:

     +-----------------------+
	     | v0  | v1  | v2  | v3  |
	     +-----------------------+
	        |     |     |     |
	       [+]<-- | ---'      |
	        |    [+]<--------'
	        |     |
	        `>[+]<'
	           |
	           v
	        +-----+
	result: | y0  |
	        +-----+

Reduce a vector to a scalar by adding up all the lanes in an ordered fashion.

This procedure returns a scalar that is the ordered sum of all lanes. The ordered sum may be important for accounting for precision errors in floating-point computation, as floating-point addition is not associative, that is (a+b)+c may not be equal to a+(b+c).

Inputs:

• a: The vector to reduce.

Result:

• Sum of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res += a[i]
}

Reduce a vector to a scalar by adding up all the lanes in a pairwise fashion.

This procedure returns a scalar that is the sum of all lanes, calculated by adding each even-indexed element with the following odd-indexed element to produce N/2 values. This is repeated until only a single element remains. This order is supported by hardware instructions for some types/architectures (e.g. i16/i32/f32/f64 on x86 SSE, i8/i16/i32/f32 on ARM NEON).

The order of the sum may be important for accounting for precision errors in floating-point computation, as floating-point addition is not associative, that is (a+b)+c may not be equal to a+(b+c).

Inputs:

• v: The vector to reduce.

Result:

• Sum of all lanes, as a scalar.

Operation:

for n > 1 {
	n = n / 2
	for i in 0 ..< n {
		a[i] = a[2*i+0] + a[2*i+1]
	}
}
res := a[0]

Graphical representation of the operation for N=4:

   +-----------------------+
	v: | v0  | v1  | v2  | v3  |
	   +-----------------------+
	      |     |     |     |
	      `>[+]<'     `>[+]<'
	         |           |
	         `--->[+]<--'
	               |
	               v
	            +-----+
	    result: | y0  |
	            +-----+

Reduce SIMD vector to a scalar by performing bitwise AND of all of the lanes.

This procedure returns a scalar that is the result of the bitwise AND operation between all of the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Bitwise AND of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res &= a[i]
}

Reduce a vector to a scalar by performing bitwise AND of all of the lanes.

This procedure returns a scalar that is the result of the bitwise AND operation between all of the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Bitwise AND of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res &= a[i]
}

Reduce SIMD vector to a scalar by performing bitwise OR of all of the lanes.

This procedure returns a scalar that is the result of the bitwise OR operation between all of the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Bitwise OR of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res |= a[i]
}

Reduce a vector to a scalar by finding the maximum value between all of the lanes.

This procedure returns a scalar that is the maximum value of all the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Maximum value of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res = max(res, a[i])
}

Reduce a vector to a scalar by finding the minimum value between all of the lanes.

This procedure returns a scalar that is the minimum value of all the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Minimum value of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res = min(res, a[i])
}

Reduce a vector to a scalar by multiplying up all the lanes in a bisecting fashion.

This procedure returns a scalar that is the product of all lanes, calculated by bisecting the vector into two parts, where the first contains indices [0, N/2) and the second contains indices [N/2, N), and multiplying the two halves together element-wise to produce N/2 values. This is repeated until only a single element remains. This order may be faster to compute than the ordered product for floats, as it can often be better parallelized.

The order of the product may be important for accounting for precision errors in floating-point computation, as floating-point multiplication is not associative, that is (a*b)*c may not be equal to a*(b*c).

Inputs:

• v: The vector to reduce.

Result:

• Product of all lanes, as a scalar.

Operation:

for n > 1 {
	n = n / 2
	for i in 0 ..< n {
		a[i] *= a[i+n]
	}
}
res := a[0]

Graphical representation of the operation for N=4:

     +-----------------------+
	     | v0  | v1  | v2  | v3  |
	     +-----------------------+
	        |     |     |     |
	       [x]<-- | ---'      |
	        |    [x]<--------'
	        |     |
	        `>[x]<'
	           |
	           v
	        +-----+
	result: | y0  |
	        +-----+

Reduce a vector to a scalar by multiplying all the lanes in an ordered fashion.

This procedure returns a scalar that is the ordered product of all lanes. The ordered product may be important for accounting for precision errors in floating-point computation, as floating-point multiplication is not associative, that is (a*b)*c may not be equal to a*(b*c).

Inputs:

• a: The vector to reduce.

Result:

• Product of all lanes, as a scalar.

Operation:

res := 1
for i in 0 ..< len(a) {
	res *= a[i]
}

Reduce a vector to a scalar by multiplying all the lanes in a pairwise fashion.

This procedure returns a scalar that is the product of all lanes, calculated by bisecting the vector into two parts, where the first contains lanes [0, N/2) and the second contains lanes [N/2, N), and multiplying the two halves together multiplying each even-indexed element with the following odd-indexed element to produce N/2 values. This is repeated until only a single element remains. This order may be faster to compute than the ordered product for floats, as it can often be better parallelized.

The order of the product may be important for accounting for precision errors in floating-point computation, as floating-point multiplication is not associative, that is (a*b)*c may not be equal to a*(b*c).

Inputs:

• v: The vector to reduce.

Result:

• Product of all lanes, as a scalar.

Operation:

for n > 1 {
	n = n / 2
	for i in 0 ..< n {
		a[i] = a[2*i+0] * a[2*i+1]
	}
}
res := a[0]

Graphical representation of the operation for N=4:

   +-----------------------+
	v: | v0  | v1  | v2  | v3  |
	   +-----------------------+
	      |     |     |     |
	      `>[x]<'     `>[x]<'
	         |           |
	         `--->[x]<--'
	               |
	               v
	            +-----+
	    result: | y0  |
	            +-----+

Reduce a vector to a scalar by performing bitwise OR of all of the lanes.

This procedure returns a scalar that is the result of the bitwise OR operation between all of the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Bitwise OR of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res |= a[i]
}

Reduce SIMD vector to a scalar by performing bitwise XOR of all of the lanes.

This procedure returns a scalar that is the result of the bitwise XOR operation between all of the lanes in a vector.

Inputs:

• a: The vector to reduce.

Result:

• Bitwise XOR of all lanes, as a scalar.

Operation:

res := 0
for i in 0 ..< len(a) {
	res ~= a[i]
}

Replace the value in a vector's lane.

This procedure places a scalar value at the lane corresponding to the given index of the vector.

Inputs:

• a: The vector to replace a lane in.
• idx: The lane index.
• elem: The scalar to place.

Returns:

• Vector with the specified lane replaced.

Operation:

a[idx] = elem

Reverse the bit pattern of a SIMD vector.

Hardware-level dynamic swizzle / table lookup.

For each output lane i, picks an element from table using indices[i] as the source position. Maps directly onto hardware table-lookup instructions where available (tbl on ARM, pshufb on x86, swizzle on WASM). This is the runtime counterpart of simd.shuffle.

Inputs:

• table: a #simd[N]T lookup table, where T is an integer type and

N is a power of two (enforced by #simd).

• indices: a #simd[N]T of source positions. Must have the exact same

type as table.

Returns:

• A #simd[N]T. For indices[i] in [0, N-1], result[i] = table[indices[i]]

on ARM, on WebAssembly (16-byte), and on the scalar emulation fallback. On x86 vectors larger than 16 bytes, the operation is lane-local; see Notes.

Operation (in-range indices, non-lane-local platforms):

for i in 0 ..< N {
		result[i] = table[indices[i]]   // indices[i] assumed to be in [0, N-1]
	}

Notes:
- **Out-of-range indices** (`indices[i] >= N`) are platform-defined:
  most hardware paths return 0; the scalar fallback wraps via
  `indices[i] & (N-1)`. Mask explicitly if you need portable behavior.
- **x86 wide vectors are lane-local.** `vpshufb` treats a 256-bit AVX2
  register as two independent 128-bit lanes; `pshufb.b.512` treats a
  512-bit AVX-512 register as four. An index in lane `k` can only address
  table entries in that same lane. AVX2 Example: Lane 0 is [0..15], Lane 1
  is [16..31]. Accessing `indices[20] = 5` yields `table[21]`, not `table[5]`.
  ARM `tbl` and the emulation fallback are cross-lane across the full table.
- **Hardware acceleration is conditional.** It requires 8-bit integer
  elements, a vector size supported by the target, and the relevant
  target features enabled (`ssse3` / `avx2` / `avx512f`+`avx512bw` on x86,
  `neon` on ARM). Otherwise this falls back to scalar emulation. Non-byte
  element types always use the scalar fallback.

Implementation:

	| Platform    | Hardware path (8-bit elements)                  | Notes                         |
	|-------------|-------------------------------------------------|-------------------------------|
	| x86-64      | pshufb (16B), vpshufb (32B), pshufb.b.512 (64B) | 32 / 64 B are lane-local      |
	| ARM64       | tbl1 (16B), tbl2 (32B), tbl4 (64B)              | >16 B: split into 16-B chunks |
	| ARM32       | vtbl1 (8B), vtbl2 (16B), vtbl4 (32B)            | >8 B: split into 8-B chunks   |
	| WebAssembly | i8x16.swizzle (16B)                             | Other sizes: emulated         |
	| Other       | Scalar emulation                                |                               |

Example:

	import "core:simd"
	import "core:fmt"

	runtime_swizzle_example :: proc() {
		table   := simd.u8x16{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15}
		indices := simd.u8x16{15, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14}
		result  := simd.runtime_swizzle(table, indices)
		fmt.println(result) // {15, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14}
	}

Saturated addition of SIMD vectors.

The saturated sum is a just like a normal sum, except the treatment of the result upon overflow or underflow is different. In saturated operations, the result is not wrapped to the bit-width of the lane, and instead is kept clamped between the minimum and the maximum values of the lane type.

This procedure returns a vector where each lane is the saturated sum of the corresponding lanes of vectors a and b.

Inputs:

• a: An integer vector.
• b: An integer vector.

Returns:

• The saturated sum of the two vectors.

Operation:

for i in 0 ..< len(res) {
	switch {
	case b[i] >= max(type_of(a[i])) - a[i]: // (overflow of a[i])
		res[i] = max(type_of(a[i]))
	case b[i] <= min(type_of(a[i])) - a[i]: // (underflow of a[i])
		res[i] = min(type_of(a[i]))
	} else {
		res[i] = a[i] + b[i]
	}
}
return res

Example:

// An example for a 4-lane vector `a` of 8-bit signed integers.

   +-----+-----+-----+-----+
a: |  0  | 255 |  2  |  3  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  1  |  3  |  2  | -1  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Saturated subtraction of 2 lanes of vectors.

The saturated difference is a just like a normal difference, except the treatment of the result upon overflow or underflow is different. In saturated operations, the result is not wrapped to the bit-width of the lane, and instead is kept clamped between the minimum and the maximum values of the lane type.

This procedure returns a vector where each lane is the saturated difference of the corresponding lanes of vectors a and b.

Inputs:

• a: An integer vector to subtract from.
• b: An integer vector.

Returns:

• The saturated difference of the two vectors.

Operation:

for i in 0 ..< len(res) {
	switch {
	case b[i] >= max(type_of(a[i])) + a[i]: // (overflow of a[i])
		res[i] = max(type_of(a[i]))
	case b[i] <= min(type_of(a[i])) + a[i]: // (underflow of a[i])
		res[i] = min(type_of(a[i]))
	} else {
		res[i] = a[i] - b[i]
	}
}
return res

Example:

// An example for a 4-lane vector `a` of 8-bit signed integers.

   +-----+-----+-----+-----+
a: |  0  | 255 |  2  |  3  |
   +-----+-----+-----+-----+
   +-----+-----+-----+-----+
b: |  3  |  3  |  2  | -1  |
   +-----+-----+-----+-----+
res:
   +-----+-----+-----+-----+

   +-----+-----+-----+-----+

Perform a scatter store from a vector.

A scatter operation is a memory store operation that stores values from a vector into multiple memory locations. This operation is effectively the opposite of the gather operation.

Inputs:

• ptr: A vector of memory locations. Each masked location will be written

to with a value from the `val` vector. Pointers in this vector can be `nil`
	or any other invalid value if the corresponding value in the `mask`
	parameter is zero.
- `val`: A vector of values to write to the memory locations.
- `mask`: A vector of booleans or unsigned integers that decides which lanes
	get written to memory. If the value of the mask is `true` (the lowest bit
	set), the corresponding lane is written into memory. Otherwise it's not
	written into memory.

Operation:

	for i in 0 ..< len(ptr) {
		if mask[i]&1 == 1 {
			ptr[i]^ = val[i]
		}
	}

Example:

	// Example below writes value `127` to the second element of two different
	// vectors. The addresses of store destinations are written to the first and the
	// third argument of the `ptr` vector, and the `mask` is set accordingly.

	import "core:fmt"
	import "core:simd"

	simd_scatter_example :: proc() {
		v1 := [4] f32 {1, 2, 3, 4};
		v2 := [4] f32 {5, 6, 7, 8};
		ptrs := #simd [4]rawptr { &v1[1], nil, &v2[1], nil }
		mask := #simd [4]bool { true, false, true, false }
		vals := #simd [4]f32 { 0x7f, 0x7f, 0x7f, 0x7f }
		simd.scatter(ptrs, vals, mask)
		fmt.println(v1)
		fmt.println(v2)
	}

Output:

	[1, 127, 3, 4]
	[5, 127, 7, 8]

The graphic below shows how the data gets written into memory.

	
	      +-------------------+
	mask: | 1  | 0  | 1  | 0  |
	      +-------------------+
	        |    |    |    |
	        v    X    v    X
	      +-------------------+
	vals: | d0 | d1 | d2 | d3 |
	      +-------------------+
	         |         \
	         v          v
	      +-----------------------+
	ptrs: | &m0 | nil | &m2 | nil |
	      +-----------------------+