png/
common.rs

Help
1//! Common types shared between the encoder and decoder
2use crate::text_metadata::{EncodableTextChunk, ITXtChunk, TEXtChunk, ZTXtChunk};
3use crate::{chunk, encoder};
4use io::Write;
5use std::{borrow::Cow, convert::TryFrom, fmt, io};
6
7/// Describes how a pixel is encoded.
8#[derive(Debug, Clone, Copy, PartialEq, Eq)]
9#[repr(u8)]
10pub enum ColorType {
11    /// 1 grayscale sample.
12    Grayscale = 0,
13    /// 1 red sample, 1 green sample, 1 blue sample.
14    Rgb = 2,
15    /// 1 sample for the palette index.
16    Indexed = 3,
17    /// 1 grayscale sample, then 1 alpha sample.
18    GrayscaleAlpha = 4,
19    /// 1 red sample, 1 green sample, 1 blue sample, and finally, 1 alpha sample.
20    Rgba = 6,
21}
22
23impl ColorType {
24    /// Returns the number of samples used per pixel encoded in this way.
25    pub fn samples(self) -> usize {
26        self.samples_u8().into()
27    }
28
29    pub(crate) fn samples_u8(self) -> u8 {
30        use self::ColorType::*;
31        match self {
32            Grayscale | Indexed => 1,
33            Rgb => 3,
34            GrayscaleAlpha => 2,
35            Rgba => 4,
36        }
37    }
38
39    /// u8 -> Self. Temporary solution until Rust provides a canonical one.
40    pub fn from_u8(n: u8) -> Option<ColorType> {
41        match n {
42            0 => Some(ColorType::Grayscale),
43            2 => Some(ColorType::Rgb),
44            3 => Some(ColorType::Indexed),
45            4 => Some(ColorType::GrayscaleAlpha),
46            6 => Some(ColorType::Rgba),
47            _ => None,
48        }
49    }
50
51    pub(crate) fn checked_raw_row_length(self, depth: BitDepth, width: u32) -> Option<usize> {
52        // No overflow can occur in 64 bits, we multiply 32-bit with 5 more bits.
53        let bits = u64::from(width) * u64::from(self.samples_u8()) * u64::from(depth.into_u8());
54        TryFrom::try_from(1 + (bits + 7) / 8).ok()
55    }
56
57    pub(crate) fn raw_row_length_from_width(self, depth: BitDepth, width: u32) -> usize {
58        let samples = width as usize * self.samples();
59        1 + match depth {
60            BitDepth::Sixteen => samples * 2,
61            BitDepth::Eight => samples,
62            subbyte => {
63                let samples_per_byte = 8 / subbyte as usize;
64                let whole = samples / samples_per_byte;
65                let fract = usize::from(samples % samples_per_byte > 0);
66                whole + fract
67            }
68        }
69    }
70
71    pub(crate) fn is_combination_invalid(self, bit_depth: BitDepth) -> bool {
72        // Section 11.2.2 of the PNG standard disallows several combinations
73        // of bit depth and color type
74        ((bit_depth == BitDepth::One || bit_depth == BitDepth::Two || bit_depth == BitDepth::Four)
75            && (self == ColorType::Rgb
76                || self == ColorType::GrayscaleAlpha
77                || self == ColorType::Rgba))
78            || (bit_depth == BitDepth::Sixteen && self == ColorType::Indexed)
79    }
80}
81
82/// Bit depth of the PNG file.
83/// Specifies the number of bits per sample.
84#[derive(Debug, Clone, Copy, PartialEq, Eq)]
85#[repr(u8)]
86pub enum BitDepth {
87    One = 1,
88    Two = 2,
89    Four = 4,
90    Eight = 8,
91    Sixteen = 16,
92}
93
94/// Internal count of bytes per pixel.
95/// This is used for filtering which never uses sub-byte units. This essentially reduces the number
96/// of possible byte chunk lengths to a very small set of values appropriate to be defined as an
97/// enum.
98#[derive(Debug, Clone, Copy)]
99#[repr(u8)]
100pub(crate) enum BytesPerPixel {
101    One = 1,
102    Two = 2,
103    Three = 3,
104    Four = 4,
105    Six = 6,
106    Eight = 8,
107}
108
109impl BitDepth {
110    /// u8 -> Self. Temporary solution until Rust provides a canonical one.
111    pub fn from_u8(n: u8) -> Option<BitDepth> {
112        match n {
113            1 => Some(BitDepth::One),
114            2 => Some(BitDepth::Two),
115            4 => Some(BitDepth::Four),
116            8 => Some(BitDepth::Eight),
117            16 => Some(BitDepth::Sixteen),
118            _ => None,
119        }
120    }
121
122    pub(crate) fn into_u8(self) -> u8 {
123        self as u8
124    }
125}
126
127/// Pixel dimensions information
128#[derive(Clone, Copy, Debug)]
129pub struct PixelDimensions {
130    /// Pixels per unit, X axis
131    pub xppu: u32,
132    /// Pixels per unit, Y axis
133    pub yppu: u32,
134    /// Either *Meter* or *Unspecified*
135    pub unit: Unit,
136}
137
138#[derive(Debug, Clone, Copy, PartialEq, Eq)]
139#[repr(u8)]
140/// Physical unit of the pixel dimensions
141pub enum Unit {
142    Unspecified = 0,
143    Meter = 1,
144}
145
146impl Unit {
147    /// u8 -> Self. Temporary solution until Rust provides a canonical one.
148    pub fn from_u8(n: u8) -> Option<Unit> {
149        match n {
150            0 => Some(Unit::Unspecified),
151            1 => Some(Unit::Meter),
152            _ => None,
153        }
154    }
155}
156
157/// How to reset buffer of an animated png (APNG) at the end of a frame.
158#[derive(Debug, Clone, Copy, PartialEq, Eq)]
159#[repr(u8)]
160pub enum DisposeOp {
161    /// Leave the buffer unchanged.
162    None = 0,
163    /// Clear buffer with the background color.
164    Background = 1,
165    /// Reset the buffer to the state before the current frame.
166    Previous = 2,
167}
168
169impl DisposeOp {
170    /// u8 -> Self. Using enum_primitive or transmute is probably the right thing but this will do for now.
171    pub fn from_u8(n: u8) -> Option<DisposeOp> {
172        match n {
173            0 => Some(DisposeOp::None),
174            1 => Some(DisposeOp::Background),
175            2 => Some(DisposeOp::Previous),
176            _ => None,
177        }
178    }
179}
180
181impl fmt::Display for DisposeOp {
182    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
183        let name = match *self {
184            DisposeOp::None => "DISPOSE_OP_NONE",
185            DisposeOp::Background => "DISPOSE_OP_BACKGROUND",
186            DisposeOp::Previous => "DISPOSE_OP_PREVIOUS",
187        };
188        write!(f, "{}", name)
189    }
190}
191
192/// How pixels are written into the buffer.
193#[derive(Debug, Clone, Copy, PartialEq, Eq)]
194#[repr(u8)]
195pub enum BlendOp {
196    /// Pixels overwrite the value at their position.
197    Source = 0,
198    /// The new pixels are blended into the current state based on alpha.
199    Over = 1,
200}
201
202impl BlendOp {
203    /// u8 -> Self. Using enum_primitive or transmute is probably the right thing but this will do for now.
204    pub fn from_u8(n: u8) -> Option<BlendOp> {
205        match n {
206            0 => Some(BlendOp::Source),
207            1 => Some(BlendOp::Over),
208            _ => None,
209        }
210    }
211}
212
213impl fmt::Display for BlendOp {
214    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
215        let name = match *self {
216            BlendOp::Source => "BLEND_OP_SOURCE",
217            BlendOp::Over => "BLEND_OP_OVER",
218        };
219        write!(f, "{}", name)
220    }
221}
222
223/// Frame control information
224#[derive(Clone, Copy, Debug)]
225pub struct FrameControl {
226    /// Sequence number of the animation chunk, starting from 0
227    pub sequence_number: u32,
228    /// Width of the following frame
229    pub width: u32,
230    /// Height of the following frame
231    pub height: u32,
232    /// X position at which to render the following frame
233    pub x_offset: u32,
234    /// Y position at which to render the following frame
235    pub y_offset: u32,
236    /// Frame delay fraction numerator
237    pub delay_num: u16,
238    /// Frame delay fraction denominator
239    pub delay_den: u16,
240    /// Type of frame area disposal to be done after rendering this frame
241    pub dispose_op: DisposeOp,
242    /// Type of frame area rendering for this frame
243    pub blend_op: BlendOp,
244}
245
246impl Default for FrameControl {
247    fn default() -> FrameControl {
248        FrameControl {
249            sequence_number: 0,
250            width: 0,
251            height: 0,
252            x_offset: 0,
253            y_offset: 0,
254            delay_num: 1,
255            delay_den: 30,
256            dispose_op: DisposeOp::None,
257            blend_op: BlendOp::Source,
258        }
259    }
260}
261
262impl FrameControl {
263    pub fn set_seq_num(&mut self, s: u32) {
264        self.sequence_number = s;
265    }
266
267    pub fn inc_seq_num(&mut self, i: u32) {
268        self.sequence_number += i;
269    }
270
271    pub fn encode<W: Write>(self, w: &mut W) -> encoder::Result<()> {
272        let mut data = [0u8; 26];
273        data[..4].copy_from_slice(&self.sequence_number.to_be_bytes());
274        data[4..8].copy_from_slice(&self.width.to_be_bytes());
275        data[8..12].copy_from_slice(&self.height.to_be_bytes());
276        data[12..16].copy_from_slice(&self.x_offset.to_be_bytes());
277        data[16..20].copy_from_slice(&self.y_offset.to_be_bytes());
278        data[20..22].copy_from_slice(&self.delay_num.to_be_bytes());
279        data[22..24].copy_from_slice(&self.delay_den.to_be_bytes());
280        data[24] = self.dispose_op as u8;
281        data[25] = self.blend_op as u8;
282
283        encoder::write_chunk(w, chunk::fcTL, &data)
284    }
285}
286
287/// Animation control information
288#[derive(Clone, Copy, Debug)]
289pub struct AnimationControl {
290    /// Number of frames
291    pub num_frames: u32,
292    /// Number of times to loop this APNG.  0 indicates infinite looping.
293    pub num_plays: u32,
294}
295
296impl AnimationControl {
297    pub fn encode<W: Write>(self, w: &mut W) -> encoder::Result<()> {
298        let mut data = [0; 8];
299        data[..4].copy_from_slice(&self.num_frames.to_be_bytes());
300        data[4..].copy_from_slice(&self.num_plays.to_be_bytes());
301        encoder::write_chunk(w, chunk::acTL, &data)
302    }
303}
304
305/// The type and strength of applied compression.
306#[derive(Debug, Clone, Copy)]
307pub enum Compression {
308    /// Default level
309    Default,
310    /// Fast minimal compression
311    Fast,
312    /// Higher compression level
313    ///
314    /// Best in this context isn't actually the highest possible level
315    /// the encoder can do, but is meant to emulate the `Best` setting in the `Flate2`
316    /// library.
317    Best,
318    #[deprecated(
319        since = "0.17.6",
320        note = "use one of the other compression levels instead, such as 'fast'"
321    )]
322    Huffman,
323    #[deprecated(
324        since = "0.17.6",
325        note = "use one of the other compression levels instead, such as 'fast'"
326    )]
327    Rle,
328}
329
330impl Default for Compression {
331    fn default() -> Self {
332        Self::Default
333    }
334}
335
336/// An unsigned integer scaled version of a floating point value,
337/// equivalent to an integer quotient with fixed denominator (100_000)).
338#[derive(Clone, Copy, Debug, PartialEq, Eq)]
339pub struct ScaledFloat(u32);
340
341impl ScaledFloat {
342    const SCALING: f32 = 100_000.0;
343
344    /// Gets whether the value is within the clamped range of this type.
345    pub fn in_range(value: f32) -> bool {
346        value >= 0.0 && (value * Self::SCALING).floor() <= u32::MAX as f32
347    }
348
349    /// Gets whether the value can be exactly converted in round-trip.
350    #[allow(clippy::float_cmp)] // Stupid tool, the exact float compare is _the entire point_.
351    pub fn exact(value: f32) -> bool {
352        let there = Self::forward(value);
353        let back = Self::reverse(there);
354        value == back
355    }
356
357    fn forward(value: f32) -> u32 {
358        (value.max(0.0) * Self::SCALING).floor() as u32
359    }
360
361    fn reverse(encoded: u32) -> f32 {
362        encoded as f32 / Self::SCALING
363    }
364
365    /// Slightly inaccurate scaling and quantization.
366    /// Clamps the value into the representable range if it is negative or too large.
367    pub fn new(value: f32) -> Self {
368        Self(Self::forward(value))
369    }
370
371    /// Fully accurate construction from a value scaled as per specification.
372    pub fn from_scaled(val: u32) -> Self {
373        Self(val)
374    }
375
376    /// Get the accurate encoded value.
377    pub fn into_scaled(self) -> u32 {
378        self.0
379    }
380
381    /// Get the unscaled value as a floating point.
382    pub fn into_value(self) -> f32 {
383        Self::reverse(self.0)
384    }
385
386    pub(crate) fn encode_gama<W: Write>(self, w: &mut W) -> encoder::Result<()> {
387        encoder::write_chunk(w, chunk::gAMA, &self.into_scaled().to_be_bytes())
388    }
389}
390
391/// Chromaticities of the color space primaries
392#[derive(Clone, Copy, Debug, PartialEq, Eq)]
393pub struct SourceChromaticities {
394    pub white: (ScaledFloat, ScaledFloat),
395    pub red: (ScaledFloat, ScaledFloat),
396    pub green: (ScaledFloat, ScaledFloat),
397    pub blue: (ScaledFloat, ScaledFloat),
398}
399
400impl SourceChromaticities {
401    pub fn new(white: (f32, f32), red: (f32, f32), green: (f32, f32), blue: (f32, f32)) -> Self {
402        SourceChromaticities {
403            white: (ScaledFloat::new(white.0), ScaledFloat::new(white.1)),
404            red: (ScaledFloat::new(red.0), ScaledFloat::new(red.1)),
405            green: (ScaledFloat::new(green.0), ScaledFloat::new(green.1)),
406            blue: (ScaledFloat::new(blue.0), ScaledFloat::new(blue.1)),
407        }
408    }
409
410    #[rustfmt::skip]
411    pub fn to_be_bytes(self) -> [u8; 32] {
412        let white_x = self.white.0.into_scaled().to_be_bytes();
413        let white_y = self.white.1.into_scaled().to_be_bytes();
414        let red_x   = self.red.0.into_scaled().to_be_bytes();
415        let red_y   = self.red.1.into_scaled().to_be_bytes();
416        let green_x = self.green.0.into_scaled().to_be_bytes();
417        let green_y = self.green.1.into_scaled().to_be_bytes();
418        let blue_x  = self.blue.0.into_scaled().to_be_bytes();
419        let blue_y  = self.blue.1.into_scaled().to_be_bytes();
420        [
421            white_x[0], white_x[1], white_x[2], white_x[3],
422            white_y[0], white_y[1], white_y[2], white_y[3],
423            red_x[0],   red_x[1],   red_x[2],   red_x[3],
424            red_y[0],   red_y[1],   red_y[2],   red_y[3],
425            green_x[0], green_x[1], green_x[2], green_x[3],
426            green_y[0], green_y[1], green_y[2], green_y[3],
427            blue_x[0],  blue_x[1],  blue_x[2],  blue_x[3],
428            blue_y[0],  blue_y[1],  blue_y[2],  blue_y[3],
429        ]
430    }
431
432    pub fn encode<W: Write>(self, w: &mut W) -> encoder::Result<()> {
433        encoder::write_chunk(w, chunk::cHRM, &self.to_be_bytes())
434    }
435}
436
437/// The rendering intent for an sRGB image.
438///
439/// Presence of this data also indicates that the image conforms to the sRGB color space.
440#[repr(u8)]
441#[derive(Clone, Copy, Debug, PartialEq, Eq)]
442pub enum SrgbRenderingIntent {
443    /// For images preferring good adaptation to the output device gamut at the expense of colorimetric accuracy, such as photographs.
444    Perceptual = 0,
445    /// For images requiring colour appearance matching (relative to the output device white point), such as logos.
446    RelativeColorimetric = 1,
447    /// For images preferring preservation of saturation at the expense of hue and lightness, such as charts and graphs.
448    Saturation = 2,
449    /// For images requiring preservation of absolute colorimetry, such as previews of images destined for a different output device (proofs).
450    AbsoluteColorimetric = 3,
451}
452
453impl SrgbRenderingIntent {
454    pub(crate) fn into_raw(self) -> u8 {
455        self as u8
456    }
457
458    pub(crate) fn from_raw(raw: u8) -> Option<Self> {
459        match raw {
460            0 => Some(SrgbRenderingIntent::Perceptual),
461            1 => Some(SrgbRenderingIntent::RelativeColorimetric),
462            2 => Some(SrgbRenderingIntent::Saturation),
463            3 => Some(SrgbRenderingIntent::AbsoluteColorimetric),
464            _ => None,
465        }
466    }
467
468    pub fn encode<W: Write>(self, w: &mut W) -> encoder::Result<()> {
469        encoder::write_chunk(w, chunk::sRGB, &[self.into_raw()])
470    }
471}
472
473/// Coding-independent code points (cICP) specify the color space (primaries),
474/// transfer function, matrix coefficients and scaling factor of the image using
475/// the code points specified in [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273).
476///
477/// See https://www.w3.org/TR/png-3/#cICP-chunk for more details.
478#[derive(Clone, Copy, Debug, PartialEq, Eq)]
479pub struct CodingIndependentCodePoints {
480    /// Id number of the color primaries defined in
481    /// [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273) in "Table 2 -
482    /// Interpretation of colour primaries (ColourPrimaries) value".
483    pub color_primaries: u8,
484
485    /// Id number of the transfer characteristics defined in
486    /// [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273) in "Table 3 -
487    /// Interpretation of transfer characteristics (TransferCharacteristics)
488    /// value".
489    pub transfer_function: u8,
490
491    /// Id number of the matrix coefficients defined in
492    /// [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273) in "Table 4 -
493    /// Interpretation of matrix coefficients (MatrixCoefficients) value".
494    ///
495    /// This field is included to faithfully replicate the base
496    /// [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273) specification, but matrix coefficients
497    /// will always be set to 0, because RGB is currently the only supported color mode in PNG.
498    pub matrix_coefficients: u8,
499
500    /// Whether the image is
501    /// [a full range image](https://www.w3.org/TR/png-3/#dfn-full-range-image)
502    /// or
503    /// [a narrow range image](https://www.w3.org/TR/png-3/#dfn-narrow-range-image).
504    ///
505    /// This field is included to faithfully replicate the base
506    /// [ITU-T-H.273](https://www.itu.int/rec/T-REC-H.273) specification, but it has limited
507    /// practical application to PNG images, because narrow-range images are [quite
508    /// rare](https://github.com/w3c/png/issues/312#issuecomment-2327349614) in practice.
509    pub is_video_full_range_image: bool,
510}
511
512/// Mastering Display Color Volume (mDCV) used at the point of content creation,
513/// as specified in [SMPTE-ST-2086](https://ieeexplore.ieee.org/stamp/stamp.jsp?arnumber=8353899).
514///
515/// See https://www.w3.org/TR/png-3/#mDCV-chunk for more details.
516#[derive(Clone, Copy, Debug, PartialEq, Eq)]
517pub struct MasteringDisplayColorVolume {
518    /// Mastering display chromaticities.
519    pub chromaticities: SourceChromaticities,
520
521    /// Mastering display maximum luminance.
522    ///
523    /// The value is expressed in units of 0.0001 cd/m^2 - for example if this field
524    /// is set to `10000000` then it indicates 1000 cd/m^2.
525    pub max_luminance: u32,
526
527    /// Mastering display minimum luminance.
528    ///
529    /// The value is expressed in units of 0.0001 cd/m^2 - for example if this field
530    /// is set to `10000000` then it indicates 1000 cd/m^2.
531    pub min_luminance: u32,
532}
533
534/// Content light level information of HDR content.
535///
536/// See https://www.w3.org/TR/png-3/#cLLI-chunk for more details.
537#[derive(Clone, Copy, Debug, PartialEq, Eq)]
538pub struct ContentLightLevelInfo {
539    /// Maximum Content Light Level indicates the maximum light level of any
540    /// single pixel (in cd/m^2, also known as nits) of the entire playback
541    /// sequence.
542    ///
543    /// The value is expressed in units of 0.0001 cd/m^2 - for example if this field
544    /// is set to `10000000` then it indicates 1000 cd/m^2.
545    ///
546    /// A value of zero means that the value is unknown or not currently calculable.
547    pub max_content_light_level: u32,
548
549    /// Maximum Frame Average Light Level indicates the maximum value of the
550    /// frame average light level (in cd/m^2, also known as nits) of the entire
551    /// playback sequence. It is calculated by first averaging the decoded
552    /// luminance values of all the pixels in each frame, and then using the
553    /// value for the frame with the highest value.
554    ///
555    /// The value is expressed in units of 0.0001 cd/m^2 - for example if this field
556    /// is set to `10000000` then it indicates 1000 cd/m^2.
557    ///
558    /// A value of zero means that the value is unknown or not currently calculable.
559    pub max_frame_average_light_level: u32,
560}
561
562/// PNG info struct
563#[derive(Clone, Debug)]
564#[non_exhaustive]
565pub struct Info<'a> {
566    pub width: u32,
567    pub height: u32,
568    pub bit_depth: BitDepth,
569    /// How colors are stored in the image.
570    pub color_type: ColorType,
571    pub interlaced: bool,
572    /// The image's `sBIT` chunk, if present; contains significant bits of the sample.
573    pub sbit: Option<Cow<'a, [u8]>>,
574    /// The image's `tRNS` chunk, if present; contains the alpha channel of the image's palette, 1 byte per entry.
575    pub trns: Option<Cow<'a, [u8]>>,
576    pub pixel_dims: Option<PixelDimensions>,
577    /// The image's `PLTE` chunk, if present; contains the RGB channels (in that order) of the image's palettes, 3 bytes per entry (1 per channel).
578    pub palette: Option<Cow<'a, [u8]>>,
579    /// The contents of the image's gAMA chunk, if present.
580    /// Prefer `source_gamma` to also get the derived replacement gamma from sRGB chunks.
581    pub gama_chunk: Option<ScaledFloat>,
582    /// The contents of the image's `cHRM` chunk, if present.
583    /// Prefer `source_chromaticities` to also get the derived replacements from sRGB chunks.
584    pub chrm_chunk: Option<SourceChromaticities>,
585    /// The contents of the image's `bKGD` chunk, if present.
586    pub bkgd: Option<Cow<'a, [u8]>>,
587
588    pub frame_control: Option<FrameControl>,
589    pub animation_control: Option<AnimationControl>,
590    pub compression: Compression,
591    /// Gamma of the source system.
592    /// Set by both `gAMA` as well as to a replacement by `sRGB` chunk.
593    pub source_gamma: Option<ScaledFloat>,
594    /// Chromaticities of the source system.
595    /// Set by both `cHRM` as well as to a replacement by `sRGB` chunk.
596    pub source_chromaticities: Option<SourceChromaticities>,
597    /// The rendering intent of an SRGB image.
598    ///
599    /// Presence of this value also indicates that the image conforms to the SRGB color space.
600    pub srgb: Option<SrgbRenderingIntent>,
601    /// The ICC profile for the image.
602    pub icc_profile: Option<Cow<'a, [u8]>>,
603    /// The coding-independent code points for video signal type identification of the image.
604    pub coding_independent_code_points: Option<CodingIndependentCodePoints>,
605    /// The mastering display color volume for the image.
606    pub mastering_display_color_volume: Option<MasteringDisplayColorVolume>,
607    /// The content light information for the image.
608    pub content_light_level: Option<ContentLightLevelInfo>,
609    /// The EXIF metadata for the image.
610    pub exif_metadata: Option<Cow<'a, [u8]>>,
611    /// tEXt field
612    pub uncompressed_latin1_text: Vec<TEXtChunk>,
613    /// zTXt field
614    pub compressed_latin1_text: Vec<ZTXtChunk>,
615    /// iTXt field
616    pub utf8_text: Vec<ITXtChunk>,
617}
618
619impl Default for Info<'_> {
620    fn default() -> Info<'static> {
621        Info {
622            width: 0,
623            height: 0,
624            bit_depth: BitDepth::Eight,
625            color_type: ColorType::Grayscale,
626            interlaced: false,
627            palette: None,
628            sbit: None,
629            trns: None,
630            gama_chunk: None,
631            chrm_chunk: None,
632            bkgd: None,
633            pixel_dims: None,
634            frame_control: None,
635            animation_control: None,
636            // Default to `deflate::Compression::Fast` and `filter::FilterType::Sub`
637            // to maintain backward compatible output.
638            compression: Compression::Fast,
639            source_gamma: None,
640            source_chromaticities: None,
641            srgb: None,
642            icc_profile: None,
643            coding_independent_code_points: None,
644            mastering_display_color_volume: None,
645            content_light_level: None,
646            exif_metadata: None,
647            uncompressed_latin1_text: Vec::new(),
648            compressed_latin1_text: Vec::new(),
649            utf8_text: Vec::new(),
650        }
651    }
652}
653
654impl Info<'_> {
655    /// A utility constructor for a default info with width and height.
656    pub fn with_size(width: u32, height: u32) -> Self {
657        Info {
658            width,
659            height,
660            ..Default::default()
661        }
662    }
663
664    /// Size of the image, width then height.
665    pub fn size(&self) -> (u32, u32) {
666        (self.width, self.height)
667    }
668
669    /// Returns true if the image is an APNG image.
670    pub fn is_animated(&self) -> bool {
671        self.frame_control.is_some() && self.animation_control.is_some()
672    }
673
674    /// Returns the frame control information of the image.
675    pub fn animation_control(&self) -> Option<&AnimationControl> {
676        self.animation_control.as_ref()
677    }
678
679    /// Returns the frame control information of the current frame
680    pub fn frame_control(&self) -> Option<&FrameControl> {
681        self.frame_control.as_ref()
682    }
683
684    /// Returns the number of bits per pixel.
685    pub fn bits_per_pixel(&self) -> usize {
686        self.color_type.samples() * self.bit_depth as usize
687    }
688
689    /// Returns the number of bytes per pixel.
690    pub fn bytes_per_pixel(&self) -> usize {
691        // If adjusting this for expansion or other transformation passes, remember to keep the old
692        // implementation for bpp_in_prediction, which is internal to the png specification.
693        self.color_type.samples() * ((self.bit_depth as usize + 7) >> 3)
694    }
695
696    /// Return the number of bytes for this pixel used in prediction.
697    ///
698    /// Some filters use prediction, over the raw bytes of a scanline. Where a previous pixel is
699    /// require for such forms the specification instead references previous bytes. That is, for
700    /// a gray pixel of bit depth 2, the pixel used in prediction is actually 4 pixels prior. This
701    /// has the consequence that the number of possible values is rather small. To make this fact
702    /// more obvious in the type system and the optimizer we use an explicit enum here.
703    pub(crate) fn bpp_in_prediction(&self) -> BytesPerPixel {
704        BytesPerPixel::from_usize(self.bytes_per_pixel())
705    }
706
707    /// Returns the number of bytes needed for one deinterlaced image.
708    pub fn raw_bytes(&self) -> usize {
709        self.height as usize * self.raw_row_length()
710    }
711
712    /// Returns the number of bytes needed for one deinterlaced row.
713    pub fn raw_row_length(&self) -> usize {
714        self.raw_row_length_from_width(self.width)
715    }
716
717    pub(crate) fn checked_raw_row_length(&self) -> Option<usize> {
718        self.color_type
719            .checked_raw_row_length(self.bit_depth, self.width)
720    }
721
722    /// Returns the number of bytes needed for one deinterlaced row of width `width`.
723    pub fn raw_row_length_from_width(&self, width: u32) -> usize {
724        self.color_type
725            .raw_row_length_from_width(self.bit_depth, width)
726    }
727
728    /// Mark the image data as conforming to the SRGB color space with the specified rendering intent.
729    ///
730    /// Any ICC profiles will be ignored.
731    ///
732    /// Source gamma and chromaticities will be written only if they're set to fallback
733    /// values specified in [11.3.2.5](https://www.w3.org/TR/png-3/#sRGB-gAMA-cHRM).
734    pub(crate) fn set_source_srgb(&mut self, rendering_intent: SrgbRenderingIntent) {
735        self.srgb = Some(rendering_intent);
736        self.icc_profile = None;
737    }
738
739    /// Encode this header to the writer.
740    ///
741    /// Note that this does _not_ include the PNG signature, it starts with the IHDR chunk and then
742    /// includes other chunks that were added to the header.
743    #[deprecated(note = "Use Encoder+Writer instead")]
744    pub fn encode<W: Write>(&self, mut w: W) -> encoder::Result<()> {
745        // Encode the IHDR chunk
746        let mut data = [0; 13];
747        data[..4].copy_from_slice(&self.width.to_be_bytes());
748        data[4..8].copy_from_slice(&self.height.to_be_bytes());
749        data[8] = self.bit_depth as u8;
750        data[9] = self.color_type as u8;
751        data[12] = self.interlaced as u8;
752        encoder::write_chunk(&mut w, chunk::IHDR, &data)?;
753
754        // Encode the pHYs chunk
755        if let Some(pd) = self.pixel_dims {
756            let mut phys_data = [0; 9];
757            phys_data[0..4].copy_from_slice(&pd.xppu.to_be_bytes());
758            phys_data[4..8].copy_from_slice(&pd.yppu.to_be_bytes());
759            match pd.unit {
760                Unit::Meter => phys_data[8] = 1,
761                Unit::Unspecified => phys_data[8] = 0,
762            }
763            encoder::write_chunk(&mut w, chunk::pHYs, &phys_data)?;
764        }
765
766        // If specified, the sRGB information overrides the source gamma and chromaticities.
767        if let Some(srgb) = &self.srgb {
768            srgb.encode(&mut w)?;
769
770            // gAMA and cHRM are optional, for backwards compatibility
771            let srgb_gamma = crate::srgb::substitute_gamma();
772            if Some(srgb_gamma) == self.source_gamma {
773                srgb_gamma.encode_gama(&mut w)?
774            }
775            let srgb_chromaticities = crate::srgb::substitute_chromaticities();
776            if Some(srgb_chromaticities) == self.source_chromaticities {
777                srgb_chromaticities.encode(&mut w)?;
778            }
779        } else {
780            if let Some(gma) = self.source_gamma {
781                gma.encode_gama(&mut w)?
782            }
783            if let Some(chrms) = self.source_chromaticities {
784                chrms.encode(&mut w)?;
785            }
786            if let Some(iccp) = &self.icc_profile {
787                encoder::write_iccp_chunk(&mut w, "_", iccp)?
788            }
789        }
790
791        if let Some(exif) = &self.exif_metadata {
792            encoder::write_chunk(&mut w, chunk::eXIf, exif)?;
793        }
794
795        if let Some(actl) = self.animation_control {
796            actl.encode(&mut w)?;
797        }
798
799        // The position of the PLTE chunk is important, it must come before the tRNS chunk and after
800        // many of the other metadata chunks.
801        if let Some(p) = &self.palette {
802            encoder::write_chunk(&mut w, chunk::PLTE, p)?;
803        };
804
805        if let Some(t) = &self.trns {
806            encoder::write_chunk(&mut w, chunk::tRNS, t)?;
807        }
808
809        for text_chunk in &self.uncompressed_latin1_text {
810            text_chunk.encode(&mut w)?;
811        }
812
813        for text_chunk in &self.compressed_latin1_text {
814            text_chunk.encode(&mut w)?;
815        }
816
817        for text_chunk in &self.utf8_text {
818            text_chunk.encode(&mut w)?;
819        }
820
821        Ok(())
822    }
823}
824
825impl BytesPerPixel {
826    pub(crate) fn from_usize(bpp: usize) -> Self {
827        match bpp {
828            1 => BytesPerPixel::One,
829            2 => BytesPerPixel::Two,
830            3 => BytesPerPixel::Three,
831            4 => BytesPerPixel::Four,
832            6 => BytesPerPixel::Six,   // Only rgb×16bit
833            8 => BytesPerPixel::Eight, // Only rgba×16bit
834            _ => unreachable!("Not a possible byte rounded pixel width"),
835        }
836    }
837
838    pub(crate) fn into_usize(self) -> usize {
839        self as usize
840    }
841}
842
843bitflags::bitflags! {
844    /// Output transformations
845    ///
846    /// Many flags from libpng are not yet supported. A PR discussing/adding them would be nice.
847    ///
848    #[doc = "
849    ```c
850    /// Discard the alpha channel
851    const STRIP_ALPHA         = 0x0002; // read only
852    /// Expand 1; 2 and 4-bit samples to bytes
853    const PACKING             = 0x0004; // read and write
854    /// Change order of packed pixels to LSB first
855    const PACKSWAP            = 0x0008; // read and write
856    /// Invert monochrome images
857    const INVERT_MONO         = 0x0020; // read and write
858    /// Normalize pixels to the sBIT depth
859    const SHIFT               = 0x0040; // read and write
860    /// Flip RGB to BGR; RGBA to BGRA
861    const BGR                 = 0x0080; // read and write
862    /// Flip RGBA to ARGB or GA to AG
863    const SWAP_ALPHA          = 0x0100; // read and write
864    /// Byte-swap 16-bit samples
865    const SWAP_ENDIAN         = 0x0200; // read and write
866    /// Change alpha from opacity to transparency
867    const INVERT_ALPHA        = 0x0400; // read and write
868    const STRIP_FILLER        = 0x0800; // write only
869    const STRIP_FILLER_BEFORE = 0x0800; // write only
870    const STRIP_FILLER_AFTER  = 0x1000; // write only
871    const GRAY_TO_RGB         = 0x2000; // read only
872    const EXPAND_16           = 0x4000; // read only
873    /// Similar to STRIP_16 but in libpng considering gamma?
874    /// Not entirely sure the documentation says it is more
875    /// accurate but doesn't say precisely how.
876    const SCALE_16            = 0x8000; // read only
877    ```
878    "]
879    pub struct Transformations: u32 {
880        /// No transformation
881        const IDENTITY            = 0x00000; // read and write */
882        /// Strip 16-bit samples to 8 bits
883        const STRIP_16            = 0x00001; // read only */
884        /// Expand paletted images to RGB; expand grayscale images of
885        /// less than 8-bit depth to 8-bit depth; and expand tRNS chunks
886        /// to alpha channels.
887        const EXPAND              = 0x00010; // read only */
888        /// Expand paletted images to include an alpha channel. Implies `EXPAND`.
889        const ALPHA               = 0x10000; // read only */
890    }
891}
892
893impl Transformations {
894    /// Transform every input to 8bit grayscale or color.
895    ///
896    /// This sets `EXPAND` and `STRIP_16` which is similar to the default transformation used by
897    /// this library prior to `0.17`.
898    pub fn normalize_to_color8() -> Transformations {
899        Transformations::EXPAND | Transformations::STRIP_16
900    }
901}
902
903/// Instantiate the default transformations, the identity transform.
904impl Default for Transformations {
905    fn default() -> Transformations {
906        Transformations::IDENTITY
907    }
908}
909
910#[derive(Debug)]
911pub struct ParameterError {
912    inner: ParameterErrorKind,
913}
914
915#[derive(Debug)]
916pub(crate) enum ParameterErrorKind {
917    /// A provided buffer must be have the exact size to hold the image data. Where the buffer can
918    /// be allocated by the caller, they must ensure that it has a minimum size as hinted previously.
919    /// Even though the size is calculated from image data, this does counts as a parameter error
920    /// because they must react to a value produced by this library, which can have been subjected
921    /// to limits.
922    ImageBufferSize { expected: usize, actual: usize },
923    /// A bit like return `None` from an iterator.
924    /// We use it to differentiate between failing to seek to the next image in a sequence and the
925    /// absence of a next image. This is an error of the caller because they should have checked
926    /// the number of images by inspecting the header data returned when opening the image. This
927    /// library will perform the checks necessary to ensure that data was accurate or error with a
928    /// format error otherwise.
929    PolledAfterEndOfImage,
930    /// Attempt to continue decoding after a fatal, non-resumable error was reported (e.g. after
931    /// [`DecodingError::Format`]).  The only case when it is possible to resume after an error
932    /// is an `UnexpectedEof` scenario - see [`DecodingError::IoError`].
933    PolledAfterFatalError,
934}
935
936impl From<ParameterErrorKind> for ParameterError {
937    fn from(inner: ParameterErrorKind) -> Self {
938        ParameterError { inner }
939    }
940}
941
942impl fmt::Display for ParameterError {
943    fn fmt(&self, fmt: &mut fmt::Formatter) -> fmt::Result {
944        use ParameterErrorKind::*;
945        match self.inner {
946            ImageBufferSize { expected, actual } => {
947                write!(fmt, "wrong data size, expected {} got {}", expected, actual)
948            }
949            PolledAfterEndOfImage => write!(fmt, "End of image has been reached"),
950            PolledAfterFatalError => {
951                write!(fmt, "A fatal decoding error has been encounted earlier")
952            }
953        }
954    }
955}
png/common.rs

png/
common.rs
