1use serde::de;
4use serde::{Deserialize, Deserializer, Serialize, Serializer};
5use std::fmt;
6use std::str::FromStr;
7
8#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
43pub struct Rgba {
44 pub r: u8,
46 pub g: u8,
48 pub b: u8,
50 pub a: u8,
52}
53
54impl Rgba {
62 #[must_use]
64 pub const fn rgb(r: u8, g: u8, b: u8) -> Self {
65 Self { r, g, b, a: 255 }
66 }
67
68 #[must_use]
70 pub const fn new(r: u8, g: u8, b: u8, a: u8) -> Self {
71 Self { r, g, b, a }
72 }
73
74 pub const TRANSPARENT: Self = Self {
84 r: 0,
85 g: 0,
86 b: 0,
87 a: 0,
88 };
89
90 pub const BLACK: Self = Self {
92 r: 0,
93 g: 0,
94 b: 0,
95 a: 255,
96 };
97
98 pub const WHITE: Self = Self {
100 r: 255,
101 g: 255,
102 b: 255,
103 a: 255,
104 };
105
106 #[must_use]
114 pub fn from_f32(r: f32, g: f32, b: f32, a: f32) -> Self {
115 Self {
116 r: (r.clamp(0.0, 1.0) * 255.0).round() as u8,
117 g: (g.clamp(0.0, 1.0) * 255.0).round() as u8,
118 b: (b.clamp(0.0, 1.0) * 255.0).round() as u8,
119 a: (a.clamp(0.0, 1.0) * 255.0).round() as u8,
120 }
121 }
122
123 #[must_use]
128 pub fn to_f32_array(&self) -> [f32; 4] {
129 [
130 self.r as f32 / 255.0,
131 self.g as f32 / 255.0,
132 self.b as f32 / 255.0,
133 self.a as f32 / 255.0,
134 ]
135 }
136}
137
138#[must_use]
169pub fn composite_over(layer: [f32; 4], base: [f32; 4]) -> [f32; 4] {
170 let [lr, lg, lb, la] = layer;
171 let [br, bg, bb, ba] = base;
172 if la >= 1.0 {
173 return layer;
174 }
175 if la <= 0.0 {
176 return base;
177 }
178 if ba <= 0.0 {
179 return layer;
180 }
181 let under = ba * (1.0 - la);
183 let a = la + under;
184 let channel = |l: f32, b: f32| (l * la + b * under) / a;
185 [channel(lr, br), channel(lg, bg), channel(lb, bb), a]
186}
187
188impl fmt::Display for Rgba {
189 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
190 if self.a == 255 {
191 write!(f, "#{:02x}{:02x}{:02x}", self.r, self.g, self.b)
192 } else {
193 write!(
194 f,
195 "#{:02x}{:02x}{:02x}{:02x}",
196 self.r, self.g, self.b, self.a
197 )
198 }
199 }
200}
201
202#[derive(Debug, Clone)]
208pub struct ParseColorError(String);
209
210impl fmt::Display for ParseColorError {
211 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
212 f.write_str(&self.0)
213 }
214}
215
216impl std::error::Error for ParseColorError {}
217
218fn hex_nibble(b: u8, label: &str) -> Result<u8, ParseColorError> {
220 char::from(b)
221 .to_digit(16)
222 .and_then(|v| u8::try_from(v).ok())
223 .ok_or_else(|| ParseColorError(format!("invalid {label} hex digit {:?}", char::from(b))))
224}
225
226fn hex_byte(hi: u8, lo: u8) -> u8 {
228 hi.wrapping_shl(4) | (lo & 0x0f)
230}
231
232fn double_nibble(n: u8) -> u8 {
235 n.wrapping_shl(4) | (n & 0x0f)
236}
237
238impl FromStr for Rgba {
239 type Err = ParseColorError;
240
241 fn from_str(s: &str) -> Result<Self, Self::Err> {
242 let hex = s.strip_prefix('#').unwrap_or(s);
243
244 if hex.is_empty() {
245 return Err(ParseColorError("empty hex color string".into()));
246 }
247
248 if !hex.is_ascii() {
251 return Err(ParseColorError(format!(
252 "invalid hex color {s:?}: not ASCII hex digits"
253 )));
254 }
255
256 match hex.as_bytes() {
259 [r, g, b] => {
261 let r = hex_nibble(*r, "red")?;
262 let g = hex_nibble(*g, "green")?;
263 let b = hex_nibble(*b, "blue")?;
264 Ok(Rgba::rgb(
265 double_nibble(r),
266 double_nibble(g),
267 double_nibble(b),
268 ))
269 }
270 [r, g, b, a] => {
272 let r = hex_nibble(*r, "red")?;
273 let g = hex_nibble(*g, "green")?;
274 let b = hex_nibble(*b, "blue")?;
275 let a = hex_nibble(*a, "alpha")?;
276 Ok(Rgba::new(
277 double_nibble(r),
278 double_nibble(g),
279 double_nibble(b),
280 double_nibble(a),
281 ))
282 }
283 [r1, r2, g1, g2, b1, b2] => {
285 let r = hex_byte(hex_nibble(*r1, "red")?, hex_nibble(*r2, "red")?);
286 let g = hex_byte(hex_nibble(*g1, "green")?, hex_nibble(*g2, "green")?);
287 let b = hex_byte(hex_nibble(*b1, "blue")?, hex_nibble(*b2, "blue")?);
288 Ok(Rgba::rgb(r, g, b))
289 }
290 [r1, r2, g1, g2, b1, b2, a1, a2] => {
292 let r = hex_byte(hex_nibble(*r1, "red")?, hex_nibble(*r2, "red")?);
293 let g = hex_byte(hex_nibble(*g1, "green")?, hex_nibble(*g2, "green")?);
294 let b = hex_byte(hex_nibble(*b1, "blue")?, hex_nibble(*b2, "blue")?);
295 let a = hex_byte(hex_nibble(*a1, "alpha")?, hex_nibble(*a2, "alpha")?);
296 Ok(Rgba::new(r, g, b, a))
297 }
298 other => Err(ParseColorError(format!(
299 "invalid hex color length {}: expected 3, 4, 6, or 8 hex digits",
300 other.len()
301 ))),
302 }
303 }
304}
305
306impl Serialize for Rgba {
307 fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
308 serializer.serialize_str(&self.to_string())
309 }
310}
311
312impl<'de> Deserialize<'de> for Rgba {
313 fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error> {
314 let s = String::deserialize(deserializer)?;
315 Rgba::from_str(&s).map_err(de::Error::custom)
316 }
317}
318
319#[allow(dead_code)]
329pub(crate) fn unpremultiply_alpha(buffer: &mut [u8]) {
330 for pixel in buffer.as_chunks_mut::<4>().0 {
335 let [r, g, b, a] = pixel;
336 let a_val = u16::from(*a);
337 if (1..255).contains(&a_val) {
341 #[allow(clippy::integer_division, clippy::arithmetic_side_effects)]
342 {
343 *r = (u16::from(*r).saturating_mul(255) / a_val).min(255) as u8;
344 *g = (u16::from(*g).saturating_mul(255) / a_val).min(255) as u8;
345 *b = (u16::from(*b).saturating_mul(255) / a_val).min(255) as u8;
346 }
347 }
348 }
349}
350
351#[allow(dead_code)]
359pub(crate) fn tint_monochrome(buffer: &mut [u8], rgb: Option<[u8; 3]>) {
360 let Some([r, g, b]) = rgb else {
361 return;
362 };
363 for pixel in buffer.as_chunks_mut::<4>().0 {
364 let [_, _, _, a] = *pixel;
365 *pixel = [r, g, b, a];
366 }
367}
368
369#[cfg(test)]
370#[allow(clippy::unwrap_used, clippy::expect_used)]
371mod tests {
372 use super::*;
373
374 #[test]
377 fn rgb_constructor_sets_alpha_255() {
378 let c = Rgba::rgb(61, 174, 233);
379 assert_eq!(
380 c,
381 Rgba {
382 r: 61,
383 g: 174,
384 b: 233,
385 a: 255
386 }
387 );
388 }
389
390 #[test]
391 fn rgba_constructor_sets_all_fields() {
392 let c = Rgba::new(61, 174, 233, 128);
393 assert_eq!(
394 c,
395 Rgba {
396 r: 61,
397 g: 174,
398 b: 233,
399 a: 128
400 }
401 );
402 }
403
404 #[test]
407 fn parse_6_digit_hex_with_hash() {
408 let c: Rgba = "#3daee9".parse().unwrap();
409 assert_eq!(c, Rgba::rgb(61, 174, 233));
410 }
411
412 #[test]
413 fn parse_8_digit_hex_with_hash() {
414 let c: Rgba = "#3daee980".parse().unwrap();
415 assert_eq!(c, Rgba::new(61, 174, 233, 128));
416 }
417
418 #[test]
419 fn parse_6_digit_hex_without_hash() {
420 let c: Rgba = "3daee9".parse().unwrap();
421 assert_eq!(c, Rgba::rgb(61, 174, 233));
422 }
423
424 #[test]
425 fn parse_3_digit_shorthand() {
426 let c: Rgba = "#abc".parse().unwrap();
427 assert_eq!(c, Rgba::rgb(0xaa, 0xbb, 0xcc));
428 }
429
430 #[test]
431 fn parse_4_digit_shorthand() {
432 let c: Rgba = "#abcd".parse().unwrap();
433 assert_eq!(c, Rgba::new(0xaa, 0xbb, 0xcc, 0xdd));
434 }
435
436 #[test]
437 fn parse_uppercase_hex() {
438 let c: Rgba = "#AABBCC".parse().unwrap();
439 assert_eq!(c, Rgba::rgb(0xaa, 0xbb, 0xcc));
440 }
441
442 #[test]
443 fn parse_empty_string_is_error() {
444 assert!("".parse::<Rgba>().is_err());
445 }
446
447 #[test]
448 fn parse_invalid_hex_chars_is_error() {
449 assert!("#gggggg".parse::<Rgba>().is_err());
450 }
451
452 #[test]
453 fn parse_invalid_length_5_chars_is_error() {
454 assert!("#12345".parse::<Rgba>().is_err());
455 }
456
457 #[test]
458 fn parse_non_ascii_three_bytes_names_the_input() {
459 let err = "#é0".parse::<Rgba>().unwrap_err();
460 assert_eq!(
461 err.to_string(),
462 "invalid hex color \"#é0\": not ASCII hex digits"
463 );
464 }
465
466 #[test]
467 fn parse_non_ascii_two_bytes_names_the_input() {
468 let err = "#é".parse::<Rgba>().unwrap_err();
469 assert_eq!(
470 err.to_string(),
471 "invalid hex color \"#é\": not ASCII hex digits"
472 );
473 }
474
475 #[test]
478 fn display_omits_alpha_when_255() {
479 assert_eq!(Rgba::rgb(61, 174, 233).to_string(), "#3daee9");
480 }
481
482 #[test]
483 fn display_includes_alpha_when_not_255() {
484 assert_eq!(Rgba::new(61, 174, 233, 128).to_string(), "#3daee980");
485 }
486
487 #[test]
490 fn serde_json_round_trip() {
491 let c = Rgba::rgb(61, 174, 233);
492 let json = serde_json::to_string(&c).unwrap();
493 assert_eq!(json, "\"#3daee9\"");
494 let deserialized: Rgba = serde_json::from_str(&json).unwrap();
495 assert_eq!(deserialized, c);
496 }
497
498 #[test]
499 fn serde_toml_round_trip() {
500 #[derive(Debug, PartialEq, Serialize, Deserialize)]
501 struct Wrapper {
502 color: Rgba,
503 }
504 let w = Wrapper {
505 color: Rgba::new(61, 174, 233, 128),
506 };
507 let toml_str = toml::to_string(&w).unwrap();
508 let deserialized: Wrapper = toml::from_str(&toml_str).unwrap();
509 assert_eq!(deserialized, w);
510 }
511
512 #[test]
515 fn to_f32_array_black() {
516 let arr = Rgba::rgb(0, 0, 0).to_f32_array();
517 assert_eq!(arr, [0.0, 0.0, 0.0, 1.0]);
518 }
519
520 #[test]
521 fn to_f32_array_white_transparent() {
522 let arr = Rgba::new(255, 255, 255, 0).to_f32_array();
523 assert_eq!(arr, [1.0, 1.0, 1.0, 0.0]);
524 }
525
526 #[test]
529 fn rgba_is_copy() {
530 let a = Rgba::rgb(1, 2, 3);
531 let b = a; assert_eq!(a, b); }
534
535 #[test]
536 fn rgba_is_hash() {
537 use std::collections::HashSet;
538 let mut set = HashSet::new();
539 set.insert(Rgba::rgb(1, 2, 3));
540 assert!(set.contains(&Rgba::rgb(1, 2, 3)));
541 }
542
543 #[test]
546 fn from_f32_basic() {
547 let c = Rgba::from_f32(1.0, 0.5, 0.0, 1.0);
548 assert_eq!(c.r, 255);
549 assert_eq!(c.g, 128); assert_eq!(c.b, 0);
551 assert_eq!(c.a, 255);
552 }
553
554 #[test]
555 fn from_f32_clamps_out_of_range() {
556 let c = Rgba::from_f32(-0.5, 1.5, 0.0, 0.0);
557 assert_eq!(c.r, 0);
558 assert_eq!(c.g, 255);
559 }
560
561 #[test]
564 fn tint_monochrome_colours_a_white_glyph_and_keeps_alpha() {
565 let mut buf = [255u8, 255, 255, 255, 255, 255, 255, 127];
566 tint_monochrome(&mut buf, Some([10, 20, 30]));
567 assert_eq!(buf, [10, 20, 30, 255, 10, 20, 30, 127]);
568 }
569
570 #[test]
571 fn tint_monochrome_keeps_a_transparent_pixel_transparent() {
572 let mut buf = [0u8, 0, 0, 0];
573 tint_monochrome(&mut buf, Some([10, 20, 30]));
574 assert_eq!(buf[3], 0);
575 }
576
577 #[test]
578 fn tint_monochrome_without_a_colour_leaves_the_bytes() {
579 let original = [255u8, 255, 255, 127, 0, 0, 0, 255, 1, 2, 3, 0];
580 let mut buf = original;
581 tint_monochrome(&mut buf, None);
582 assert_eq!(buf, original);
583 }
584
585 #[test]
588 fn composite_over_a_transparent_layer_is_the_base_exactly() {
589 let layer = [0.9, 0.1, 0.3, 0.0];
590 for base in [
591 [0.2, 0.4, 0.6, 1.0],
592 [0.2, 0.4, 0.6, 0.3],
593 [0.2, 0.4, 0.6, 0.0],
595 ] {
596 assert_eq!(composite_over(layer, base), base, "over {base:?}");
597 }
598 }
599
600 #[test]
601 fn composite_over_a_transparent_base_is_the_layer_exactly() {
602 let base = [0.2, 0.4, 0.6, 0.0];
603 for layer in [[0.9, 0.1, 0.3, 0.3], [0.1, 0.2, 0.3, 0.078_431_375]] {
604 assert_eq!(composite_over(layer, base), layer, "{layer:?}");
605 }
606 }
607
608 #[test]
609 fn composite_over_an_opaque_layer_is_the_layer() {
610 let layer = [0.3, 0.7, 0.1, 1.0];
611 for base in [[0.2, 0.4, 0.6, 1.0], [1.0, 1.0, 1.0, 0.25]] {
612 assert_eq!(composite_over(layer, base), layer, "over {base:?}");
613 }
614 }
615
616 #[test]
619 fn composite_over_an_opaque_base_is_the_plain_mix() {
620 let (layer, base) = ([0.9_f32, 0.1, 0.3, 0.5], [0.2_f32, 0.4, 0.6, 1.0]);
621 let [r, g, b, a] = composite_over(layer, base);
622 assert_eq!(a, 1.0);
623 let mix = |l: f32, b: f32| l * layer[3] + b * (1.0 - layer[3]);
624 assert_eq!(
625 [r, g, b],
626 [
627 mix(layer[0], base[0]),
628 mix(layer[1], base[1]),
629 mix(layer[2], base[2])
630 ]
631 );
632 }
633
634 #[test]
637 fn composite_over_two_translucent_colours_covers_both() {
638 let (layer, base) = ([0.8_f32, 0.2, 0.4, 0.5], [1.0_f32, 1.0, 1.0, 0.25]);
639 let [r, g, b, a] = composite_over(layer, base);
640 assert_eq!(a, 0.5 + 0.25 * 0.5);
641 let under = 0.25 * 0.5;
642 let channel = |l: f32, b: f32| (l * 0.5 + b * under) / a;
643 assert_eq!(
644 [r, g, b],
645 [channel(0.8, 1.0), channel(0.2, 1.0), channel(0.4, 1.0)]
646 );
647 let white = [1.0, 1.0, 1.0, 1.0];
650 let stacked = composite_over(composite_over(layer, base), white);
651 let painted = composite_over(layer, composite_over(base, white));
652 for (s, p) in stacked.into_iter().zip(painted) {
653 assert!((s - p).abs() < 1e-6, "{stacked:?} against {painted:?}");
654 }
655 }
656
657 #[test]
662 fn composite_over_macos_tahoe_lights_two_button_fills_is_source_over() {
663 let fill = Rgba::new(0, 0, 0, 0x14).to_f32_array();
664 let [.., a] = composite_over(fill, fill);
665 assert_eq!(a, fill[3] + fill[3] * (1.0 - fill[3]));
666 assert!((a - 0.1507).abs() < 5e-5, "{a}");
667 }
668}