Debian Codegraph @

.cargo/vendor/rgb/README.md

raw
1 # `struct RGB` for [Rust](https://www.rust-lang.org) [![crate](https://img.shields.io/crates/v/rgb.svg)](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.