pltrs_codec/png/decoded.rs
1//! The result of decoding a PNG file.
2
3use super::convert::Pixels;
4use super::header::Header;
5use super::metadata::Metadata;
6use super::types::{BitDepth, ColorType};
7
8/// The single colour that a `tRNS` chunk marks as fully transparent in a
9/// greyscale or RGB image, as raw sample values at the image's bit depth.
10#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
11pub enum ColorKey {
12 /// A grey level.
13 Gray(u16),
14 /// Red, green and blue samples.
15 Rgb([u16; 3]),
16}
17
18/// A decoded PNG image.
19///
20/// [`data`](Self::data) holds the pixels in PNG's own layout, de-interlaced:
21/// rows top to bottom, each [`row_bytes`](Self::row_bytes) long; samples of
22/// fewer than 8 bits packed most significant bits first; 16-bit samples as
23/// big-endian byte pairs; indexed images as palette indices. Use
24/// [`to_rgba8`](Self::to_rgba8) or [`to_rgba16`](Self::to_rgba16) for
25/// uniform RGBA pixels with palette and transparency applied.
26#[derive(Clone, Debug, PartialEq, Eq)]
27pub struct DecodedImage {
28 header: Header,
29 data: Vec<u8>,
30 palette: Option<Vec<[u8; 4]>>,
31 color_key: Option<ColorKey>,
32 metadata: Metadata,
33}
34
35impl DecodedImage {
36 pub(crate) fn new(
37 header: Header,
38 data: Vec<u8>,
39 palette: Option<Vec<[u8; 4]>>,
40 color_key: Option<ColorKey>,
41 metadata: Metadata,
42 ) -> Self {
43 Self {
44 header,
45 data,
46 palette,
47 color_key,
48 metadata,
49 }
50 }
51
52 /// Width in pixels.
53 pub const fn width(&self) -> u32 {
54 self.header.width
55 }
56
57 /// Height in pixels.
58 pub const fn height(&self) -> u32 {
59 self.header.height
60 }
61
62 /// Colour type as stored in the file.
63 pub const fn color_type(&self) -> ColorType {
64 self.header.format.color
65 }
66
67 /// Bit depth as stored in the file.
68 pub const fn bit_depth(&self) -> BitDepth {
69 self.header.format.depth
70 }
71
72 /// Whether the file was Adam7-interlaced.
73 pub const fn is_interlaced(&self) -> bool {
74 self.header.interlaced
75 }
76
77 /// Bytes per row of [`data`](Self::data).
78 pub fn row_bytes(&self) -> usize {
79 self.data.len() / self.header.height as usize
80 }
81
82 /// The pixel data in PNG layout (see the type documentation).
83 pub fn data(&self) -> &[u8] {
84 &self.data
85 }
86
87 /// Takes ownership of the pixel data.
88 pub fn into_data(self) -> Vec<u8> {
89 self.data
90 }
91
92 /// The palette of an indexed image as RGBA entries, with alpha from
93 /// `tRNS` (255 where it gives none).
94 pub fn palette(&self) -> Option<&[[u8; 4]]> {
95 self.palette.as_deref()
96 }
97
98 /// The transparent colour of a greyscale or RGB image, if any.
99 pub const fn color_key(&self) -> Option<ColorKey> {
100 self.color_key
101 }
102
103 /// Resolution and text metadata.
104 pub const fn metadata(&self) -> &Metadata {
105 &self.metadata
106 }
107
108 /// The pixels as 8-bit RGBA, 4 bytes per pixel.
109 ///
110 /// Grey is replicated into R, G and B; samples below 8 bits are scaled up
111 /// exactly (e.g. 4-bit 15 becomes 255); 16-bit samples are rounded to the
112 /// nearest 8-bit value. Alpha comes from the alpha channel, from the
113 /// colour key (0 for matching pixels) or from the palette, and is 255
114 /// otherwise. Palette indices beyond the palette yield opaque black.
115 pub fn to_rgba8(&self) -> Vec<u8> {
116 self.pixels().to_rgba8()
117 }
118
119 /// The pixels as 16-bit RGBA, 4 values per pixel; lossless for every
120 /// PNG format. Lower depths are scaled up exactly (8-bit 255 becomes
121 /// 65535), alpha is derived as for [`to_rgba8`](Self::to_rgba8).
122 pub fn to_rgba16(&self) -> Vec<u16> {
123 self.pixels().to_rgba16()
124 }
125
126 fn pixels(&self) -> Pixels<'_> {
127 Pixels {
128 width: self.header.width as usize,
129 format: self.header.format,
130 row_bytes: self.row_bytes(),
131 data: &self.data,
132 palette: self.palette.as_deref().unwrap_or_default(),
133 color_key: self.color_key,
134 }
135 }
136}