rgb/
lib.rs

1//! Basic struct for `RGB` and `RGBA` pixels. Packed, with red first, alpha last.
2//!
3//! This crate is intended to be the lowest common denominator for sharing `RGB`/`RGBA` bitmaps between other crates.
4//!
5//! The crate includes convenience functions for converting between the struct and bytes,
6//! and overloaded operators that work on all channels at once.
7//!
8//! This crate intentionally doesn't implement color management (due to complexity of the problem),
9//! but the structs can be parametrized to implement this if necessary. Other colorspaces are out of scope.
10//!
11#![cfg_attr(feature = "as-bytes", doc = "```rust")]
12#![cfg_attr(not(feature = "as-bytes"), doc = "```ignore")]
13//! # use rgb::*;
14//! let pixel = RGB8 {r:0, g:100, b:255};
15//!
16//! let pixel_rgba = pixel.alpha(255);
17//! let pixel = pixel_rgba.rgb();
18//!
19//! let pixels = vec![pixel; 100];
20//! /// Can be converted to a type-less slice without copying
21//! let bytes: &[u8] = rgb::bytemuck::cast_slice(&pixels);
22//!
23//! use rgb::prelude::*; // Import pixel map trait
24//! let half_bright = pixel.map(|channel| channel / 2);
25//! let doubled = half_bright * 2;
26//! # let _ = doubled;
27//! ```
28#![doc(html_logo_url = "https://kornel.ski/rgb-logo.png")]
29#![warn(missing_docs)]
30#![cfg_attr(docsrs, feature(doc_cfg))]
31#![no_std]
32
33// std is required to run unit tests
34#[cfg(test)]
35#[macro_use] extern crate std;
36/// Re-export of the [`bytemuck` crate](https://lib.rs/bytemuck). [See docs](https://docs.rs/bytemuck).
37///
38/// Use [`::bytemuck::cast_slice()`] or [`::bytemuck::from_bytes()`] to convert
39/// pixels to/from `&[u8]`.
40#[cfg(feature = "bytemuck")]
41#[doc(alias = "ComponentSlice")]
42#[doc(alias = "as_bytes")]
43#[doc(alias = "Pod")]
44pub use ::bytemuck;
45
46pub(crate) mod formats {
47    pub mod abgr;
48    pub mod argb;
49    pub mod bgr;
50    pub mod bgra;
51    pub mod gray;
52    pub mod gray_a;
53    pub mod gray_alpha;
54    pub mod grb;
55    pub mod rgb;
56    pub mod rgba;
57}
58
59/// Use as `use rgb::prelude::*`
60///
61/// The prelude will contain commonly used traits, and will be expanded in the future.
62///
63/// Using a glob import is recommended for forward compatibility with the next major version of the crate.
64pub mod prelude {
65    pub use crate::legacy::internal::pixel::ComponentMap;
66    pub use crate::legacy::internal::pixel::ColorComponentMap;
67}
68
69pub use formats::abgr::Abgr;
70pub use formats::argb::Argb;
71pub use formats::bgr::Bgr;
72pub use formats::bgra::Bgra;
73#[cfg(not(feature = "unstable-experimental"))]
74pub use formats::gray_alpha::GrayAlpha_v08 as GrayAlpha;
75#[cfg(feature = "unstable-experimental")]
76#[deprecated(note = "Renamed to GrayA")]
77pub use formats::gray_a::GrayA as GrayAlpha;
78#[cfg(not(feature = "unstable-experimental"))]
79pub use formats::gray::Gray_v08 as Gray;
80#[cfg(feature = "unstable-experimental")]
81pub use formats::gray::Gray_v09 as Gray;
82pub use formats::grb::Grb;
83pub use formats::rgb::Rgb;
84pub use formats::rgba::Rgba;
85
86mod inherent_impls;
87
88pub(crate) mod legacy {
89    pub(crate) mod internal {
90        pub mod convert;
91        pub mod ops;
92        pub mod pixel;
93        pub mod rgb;
94        pub mod rgba;
95    }
96    /// BGR/BGRA alernative layouts & grayscale
97    ///
98    /// BGR might be useful for some Windows or OpenGL APIs.
99    pub mod alt;
100}
101
102pub use legacy::alt;
103
104#[cfg(all(feature = "bytemuck", not(feature = "as-bytes")))]
105mod bytemuck_impl;
106#[cfg(feature = "as-bytes")]
107mod as_bytes;
108
109/// Re-export from `bytemuck` crate
110#[cfg(feature = "as-bytes")]
111pub use ::bytemuck::Pod;
112/// Re-export from `bytemuck` crate
113#[cfg(feature = "as-bytes")]
114pub use ::bytemuck::Zeroable;
115
116pub use crate::legacy::internal::convert::*;
117pub use crate::legacy::internal::pixel::*;
118
119#[doc(hidden)]
120/// Renamed to `Rgb`
121pub use formats::rgb::Rgb as RGB;
122#[doc(hidden)]
123/// Renamed to `Rgba`
124pub use formats::rgba::Rgba as RGBA;
125
126#[doc(hidden)]
127/// Incompatible replacement for the `GrayAlpha` type
128pub use formats::gray_a::GrayA;
129
130/// 8-bit RGB
131///
132/// The colorspace is technically undefined, but generally sRGB is assumed.
133pub type RGB8 = RGB<u8>;
134
135/// 16-bit RGB in machine's native endian
136///
137/// Be careful to perform byte-swapping when reading from files.
138pub type RGB16 = RGB<u16>;
139
140/// 8-bit RGBA, alpha is last. 0 = transparent, 255 = opaque.
141pub type RGBA8 = RGBA<u8>;
142
143/// 16-bit RGB in machine's native endian. 0 = transparent, 65535 = opaque.
144///
145/// Alpha is last.
146pub type RGBA16 = RGBA<u16>;
147
rgb/lib.rs

rgb/
lib.rs
