| 1 |
* **[Latest Docs.rs Here](https://docs.rs/bytemuck/)** |
| 2 |
|
| 3 |
[](https://opensource.org/licenses/Zlib) |
| 4 |
 |
| 5 |
[](https://crates.io/crates/bytemuck) |
| 6 |
|
| 7 |
# bytemuck |
| 8 |
|
| 9 |
A crate for mucking around with piles of bytes. |
| 10 |
|
| 11 |
This crate lets you safely perform "bit cast" operations between data types. |
| 12 |
That's where you take a value and just reinterpret the bits as being some other |
| 13 |
type of value, without changing the bits. |
| 14 |
|
| 15 |
* This is **not** like the [`as` keyword][keyword-as] |
| 16 |
* This is **not** like the [`From` trait][from-trait] |
| 17 |
* It is **most like** [`f32::to_bits`][f32-to_bits], just generalized to let you |
| 18 |
convert between all sorts of data types. |
| 19 |
|
| 20 |
[keyword-as]: https://doc.rust-lang.org/nightly/std/keyword.as.html |
| 21 |
[from-trait]: https://doc.rust-lang.org/nightly/core/convert/trait.From.html |
| 22 |
[f32-to_bits]: https://doc.rust-lang.org/nightly/std/primitive.f32.html#method.to_bits |
| 23 |
|
| 24 |
### Here's the part you're more likely to care about: *you can do this with slices too!* |
| 25 |
|
| 26 |
When a slice is involved it's not a *direct* bitcast. Instead, the `cast_slice` |
| 27 |
and `cast_slice_mut` functions will pull apart a slice's data and give you a new |
| 28 |
slice that's the same span of memory just viewed as the new type. If the size of |
| 29 |
the slice's element changes then the length of the slice you get back will be |
| 30 |
changed accordingly. |
| 31 |
|
| 32 |
This lets you cast a slice of color values into a slice of `u8` and send it to |
| 33 |
the GPU, or things like that. I'm sure there's other examples, but honestly this |
| 34 |
crate is as popular as it is mostly because of Rust's 3D graphics community |
| 35 |
wanting to cast slices of different types into byte slices for sending to the |
| 36 |
GPU. Hi friends! Push those vertices, or whatever it is that you all do. |
| 37 |
|
| 38 |
## See Also |
| 39 |
|
| 40 |
While `bytemuck` is full of unsafe code, I've also started a "sibling crate" |
| 41 |
called [bitfrob](https://docs.rs/bitfrob/latest/bitfrob/), which is where |
| 42 |
operations that are 100% safe will be added. |
| 43 |
|
| 44 |
## Stability |
| 45 |
|
| 46 |
* The crate is 1.0 and I consider this it to be "basically done". New features |
| 47 |
are usually being accepted when other people want to put in the work, but |
| 48 |
myself I wanna move on to using `bytemuck` in bigger projects. |
| 49 |
* The default build of the `bytemuck` crate will continue to work with `rustc-1.34` |
| 50 |
for at least the rest of the `1.y.z` versions. |
| 51 |
* Any other cargo features of the crate **are not** held to the same standard, and |
| 52 |
may work only on the latest Stable or even only on latest Nightly. |
| 53 |
|
| 54 |
**Future Plans:** Once the [Safe Transmute Project][pg-st] completes and |
| 55 |
stabilizes ("eventually") this crate will be updated to use that as the |
| 56 |
underlying mechanism for transmutation bounds, and a 2.0 version of `bytemuck` |
| 57 |
will be released. The hope is for the 1.0 to 2.0 transition to be as seamless as |
| 58 |
possible, but the future is always uncertain. |
| 59 |
|
| 60 |
[pg-st]: https://rust-lang.github.io/rfcs/2835-project-safe-transmute.html |