Skip to main content

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}