| 1 |
# `struct RGB` for [Rust](https://www.rust-lang.org) [](https://lib.rs/crates/rgb) |
| 2 |
|
| 3 |
Operating on pixels as weakly-typed vectors of `u8` is error-prone and inconvenient. It's better to use vectors of pixel structs. However, Rust is so strongly typed that *your* RGB pixel struct is not compatible with *my* RGB pixel struct. So let's all use mine :P |
| 4 |
|
| 5 |
[<img src="https://imgs.xkcd.com/comics/standards_2x.png" alt="xkcd: …there are 15 competing standards" width="500">](https://xkcd.com/927/) |
| 6 |
|
| 7 |
## Installation |
| 8 |
|
| 9 |
Add this to your `Cargo.toml`: |
| 10 |
|
| 11 |
```toml |
| 12 |
[dependencies] |
| 13 |
rgb = "0.8.51" |
| 14 |
``` |
| 15 |
|
| 16 |
## Usage |
| 17 |
|
| 18 |
### `RGB` and `RGBA` structs |
| 19 |
|
| 20 |
The structs implement common Rust traits and a few convenience functions, e.g. `map` that repeats an operation on every subpixel: |
| 21 |
|
| 22 |
```rust |
| 23 |
use rgb::*; // Laziest way to use traits which add extra methods to the structs |
| 24 |
|
| 25 |
let px = RGB { |
| 26 |
r:255_u8, |
| 27 |
g:0, |
| 28 |
b:255, |
| 29 |
}; |
| 30 |
let inverted = px.map(|ch| 255 - ch); |
| 31 |
|
| 32 |
println!("{}", inverted); // Display: rgb(0,255,0) |
| 33 |
assert_eq!(RGB8::new(0, 255, 0), inverted); |
| 34 |
``` |
| 35 |
|
| 36 |
### Byte slices to pixel slices |
| 37 |
|
| 38 |
For interoperability with functions operating on generic arrays of bytes there are functions for safe casting to and from pixel slices. |
| 39 |
|
| 40 |
```rust |
| 41 |
let raw = vec![0u8; width*height*3]; |
| 42 |
let pixels: &[RGB8] = raw.as_rgb(); /// Safe casts without copying |
| 43 |
let raw_again = pixels.as_bytes(); |
| 44 |
``` |
| 45 |
|
| 46 |
Note: if you get an error about "no method named `as_bytes` found", add `use rgb::ComponentBytes`. If you're using a custom component type (`RGB<CustomType>`), implement `rgb::Pod` (plain old data) and `rgb::Zeroable` trait for the component (these traits are from [`bytemuck`](https://lib.rs/bytemuck) crate). |
| 47 |
|
| 48 |
---- |
| 49 |
|
| 50 |
## About colorspaces |
| 51 |
|
| 52 |
*Correct* color management is a complex problem, and this crate aims to be the lowest common denominator, so it's intentionally agnostic about it. |
| 53 |
|
| 54 |
However, this library supports any subpixel type for `RGB<T>`, and `RGBA<RGBType, AlphaType>`, so you can use them with a newtype, e.g.: |
| 55 |
|
| 56 |
```rust |
| 57 |
struct LinearLight(u16); |
| 58 |
type LinearRGB = RGB<LinearLight>; |
| 59 |
``` |
| 60 |
|
| 61 |
|
| 62 |
### `BGRA`, `ARGB`, `Gray`, etc. |
| 63 |
|
| 64 |
There are other color types in `rgb::alt::*`. There's also an optional `serde` feature that makes all types (de)serializable. |
| 65 |
|
| 66 |
## Roadmap to 1.0 |
| 67 |
|
| 68 |
The plan is to provide easy migration to v1.0. There will be a transitional v0.9 version released that will be mostly backwards-compatible with 0.8, and forwards-compatible with 1.0. |
| 69 |
|
| 70 |
Planned changes: |
| 71 |
|
| 72 |
* Types will be renamed to follow Rust's naming convention: `RGBA` → `Rgba`. The old names will continue to work as hidden aliases. |
| 73 |
* The `Gray` and `GrayAlpha` types will change from tuple structs with `.0` to structs with named fields `.v` (value) and `.a` (alpha). Through a `Deref` trick both field names will work, but `.0` is going to be deprecated. |
| 74 |
* `bytemuck::Pod` (conversions from/to raw bytes) will require color and alpha components to be the same type (i.e. it will work with `Rgba<u8>`, but not `Rgba<Newtype, DifferentType>`). Currently it's unsound if the alpha has a different size than color components. |
| 75 |
* Many inherent methods will be moved to a new `Pixel` trait. |
| 76 |
|
| 77 |
## Migration from 0.8 to 0.9 |
| 78 |
|
| 79 |
1. Update to the latest version of 0.8, and fix all deprecation warnings. |
| 80 |
|
| 81 |
- rename `.alpha()` to `.with_alpha()` |
| 82 |
- rename `.map_c()` to `.map_colors()` |
| 83 |
|
| 84 |
2. Change field access on `GrayAlpha` from `.0` and `.1` to `.v` and `.a` where possible. |
| 85 |
3. Use the `bytemuck` crate for conversions from/to bytes instead of `ComponentBytes` trait. Disable the `as-bytes` feature if possible. |
| 86 |
4. Don't enable `gbr` and `argb` features. All pixel types are enabled by default. |
| 87 |
5. In generic code operating on pixels, add `Copy + 'static` bounds to the pixel types and/or their components. |
| 88 |
6. Test your code with `rgb = { version = "0.8.46", features = ["unstable-experimental"] }`, which enables some of the future breaking changes on the older version. This feature flag is only for testing, and will be changed/removed in the future. |
| 89 |
7. Avoid wildcard imports from `rgb::alt::*`, and avoid using `GRAY8`-`GRAYA16` type aliases. |