1//! # PNG encoder and decoder
2//!
3//! This crate contains a PNG encoder and decoder. It supports reading of single lines or whole frames.
4//!
5//! ## The decoder
6//!
7//! The most important types for decoding purposes are [`Decoder`] and
8//! [`Reader`]. They both wrap a [`std::io::Read`].
9//! `Decoder` serves as a builder for `Reader`. Calling [`Decoder::read_info`] reads from the `Read` until the
10//! image data is reached.
11//!
12//! ### Using the decoder
13//! ```
14//! use std::fs::File;
15//! // The decoder is a build for reader and can be used to set various decoding options
16//! // via `Transformations`. The default output transformation is `Transformations::IDENTITY`.
17//! let decoder = png::Decoder::new(File::open("tests/pngsuite/basi0g01.png").unwrap());
18//! let mut reader = decoder.read_info().unwrap();
19//! // Allocate the output buffer.
20//! let mut buf = vec![0; reader.output_buffer_size()];
21//! // Read the next frame. An APNG might contain multiple frames.
22//! let info = reader.next_frame(&mut buf).unwrap();
23//! // Grab the bytes of the image.
24//! let bytes = &buf[..info.buffer_size()];
25//! // Inspect more details of the last read frame.
26//! let in_animation = reader.info().frame_control.is_some();
27//! ```
28//!
29//! ## Encoder
30//! ### Using the encoder
31//!
32//! ```no_run
33//! // For reading and opening files
34//! use std::path::Path;
35//! use std::fs::File;
36//! use std::io::BufWriter;
37//!
38//! let path = Path::new(r"/path/to/image.png");
39//! let file = File::create(path).unwrap();
40//! let ref mut w = BufWriter::new(file);
41//!
42//! let mut encoder = png::Encoder::new(w, 2, 1); // Width is 2 pixels and height is 1.
43//! encoder.set_color(png::ColorType::Rgba);
44//! encoder.set_depth(png::BitDepth::Eight);
45//! encoder.set_source_gamma(png::ScaledFloat::from_scaled(45455)); // 1.0 / 2.2, scaled by 100000
46//! encoder.set_source_gamma(png::ScaledFloat::new(1.0 / 2.2)); // 1.0 / 2.2, unscaled, but rounded
47//! let source_chromaticities = png::SourceChromaticities::new( // Using unscaled instantiation here
48//! (0.31270, 0.32900),
49//! (0.64000, 0.33000),
50//! (0.30000, 0.60000),
51//! (0.15000, 0.06000)
52//! );
53//! encoder.set_source_chromaticities(source_chromaticities);
54//! let mut writer = encoder.write_header().unwrap();
55//!
56//! let data = [255, 0, 0, 255, 0, 0, 0, 255]; // An array containing a RGBA sequence. First pixel is red and second pixel is black.
57//! writer.write_image_data(&data).unwrap(); // Save
58//! ```
59//!
60
61#![cfg_attr(feature = "unstable", feature(portable_simd))]
62#![forbid(unsafe_code)]
63
64mod adam7;
65pub mod chunk;
66mod common;
67mod decoder;
68mod encoder;
69mod filter;
70mod srgb;
71pub mod text_metadata;
72mod traits;
73
74pub use crate::adam7::expand_pass as expand_interlaced_row;
75pub use crate::adam7::Adam7Info;
76pub use crate::common::*;
77pub use crate::decoder::stream::{DecodeOptions, Decoded, DecodingError, StreamingDecoder};
78pub use crate::decoder::{Decoder, InterlaceInfo, InterlacedRow, Limits, OutputInfo, Reader};
79pub use crate::encoder::{Encoder, EncodingError, StreamWriter, Writer};
80pub use crate::filter::{AdaptiveFilterType, FilterType};
81
82#[cfg(test)]
83pub(crate) mod test_utils;
84
85#[cfg(feature = "benchmarks")]
86pub mod benchable_apis;
87