Skip to content

Commit 3bf5d2c

Browse files
committed
add more vector masks explanations to the guide-level explanation
1 parent 422a454 commit 3bf5d2c

File tree

1 file changed

+24
-2
lines changed

1 file changed

+24
-2
lines changed

text/0000-ppv.md

Lines changed: 24 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -165,13 +165,33 @@ vector with four `f32` lanes. Here:
165165

166166
* **lane width**: the bit width of a vector lane, that is, the bit width of
167167
the objects stored in the vector. For example, the type `f32` is 32-bits wide.
168+
169+
That is, the `m8x4` type is a 32-bit wide vector mask with 4 lanes containing an
170+
8-bit wide mask each. Vector masks are mainly used to select the lanes on which
171+
vector operations are performed. When a lane has all of its bits set to `true`,
172+
that lane is "selected", and when a lane has all of its bits set to `false`,
173+
that lane is "not selected". The following bit pattern is thus a valid
174+
bit-pattern for the `m8x4` mask:
175+
176+
> 00000000_11111111_00000000_11111111
177+
178+
and it select two eight-bit wide lanes from a 32-bit wide vector type with four
179+
lanes. The following bit-pattern is not, however, a valid value of the same mask
180+
type:
181+
182+
> 00000000_11111111_00000000_11110111
183+
184+
because it does not satisfies the invariant that all bits of a lane must be
185+
either set or cleared.
168186

169187
Operations on vector types can be either:
170188

171189
* **vertical**: that is, lane-wise. For example, `a + b` adds each lane of `a`
172190
with the corresponding lane of `b`, while `a.lt(b)` returns a boolean mask
173191
that indicates whether the less-than (`<`, `lt`) comparison returned `true` or
174-
`false` for each of the vector lanes. Most vertical operations are binary operations (they take two input vectors). These operations are typically very fast on most architectures and they are the most widely used in practice.
192+
`false` for each of the vector lanes. Most vertical operations are binary
193+
operations (they take two input vectors). These operations are typically very
194+
fast on most architectures and they are the most widely used in practice.
175195

176196
* **horizontal**: that is, along a single vector - they are unary operations.
177197
For example, `a.sum()` adds the elements of a vector together while
@@ -268,7 +288,9 @@ even elements of a vector with a scalar:
268288

269289
```rust
270290
fn mul_even(a: f32, x: f32x4) -> f32x4 {
271-
// Create a mask for the even elements 0 and 2:
291+
// Create a vector mask for the even elements 0 and 2.
292+
// The vector mask API uses `bool`s to set or clear
293+
// all bits of a lane:
272294
let m = m32x4::new(true, false, true, false);
273295

274296
// Perform a full multiplication

0 commit comments

Comments
 (0)