png/
lib.rs

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//! use std::io::BufReader;
16//! // The decoder is a build for reader and can be used to set various decoding options
17//! // via `Transformations`. The default output transformation is `Transformations::IDENTITY`.
18//! let decoder = png::Decoder::new(BufReader::new(File::open("tests/pngsuite/basi0g01.png").unwrap()));
19//! let mut reader = decoder.read_info().unwrap();
20//! // Allocate the output buffer.
21//! let mut buf = vec![0; reader.output_buffer_size().unwrap()];
22//! // Read the next frame. An APNG might contain multiple frames.
23//! let info = reader.next_frame(&mut buf).unwrap();
24//! // Grab the bytes of the image.
25//! let bytes = &buf[..info.buffer_size()];
26//! // Inspect more details of the last read frame.
27//! let in_animation = reader.info().frame_control.is_some();
28//! ```
29//!
30//! ## Encoder
31//! ### Using the encoder
32//!
33//! ```no_run
34//! // For reading and opening files
35//! use std::path::Path;
36//! use std::fs::File;
37//! use std::io::BufWriter;
38//!
39//! let path = Path::new(r"/path/to/image.png");
40//! let file = File::create(path).unwrap();
41//! let ref mut w = BufWriter::new(file);
42//!
43//! let mut encoder = png::Encoder::new(w, 2, 1); // Width is 2 pixels and height is 1.
44//! encoder.set_color(png::ColorType::Rgba);
45//! encoder.set_depth(png::BitDepth::Eight);
46//! encoder.set_source_gamma(png::ScaledFloat::from_scaled(45455)); // 1.0 / 2.2, scaled by 100000
47//! encoder.set_source_gamma(png::ScaledFloat::new(1.0 / 2.2));     // 1.0 / 2.2, unscaled, but rounded
48//! let source_chromaticities = png::SourceChromaticities::new(     // Using unscaled instantiation here
49//!     (0.31270, 0.32900),
50//!     (0.64000, 0.33000),
51//!     (0.30000, 0.60000),
52//!     (0.15000, 0.06000)
53//! );
54//! encoder.set_source_chromaticities(source_chromaticities);
55//! let mut writer = encoder.write_header().unwrap();
56//!
57//! 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.
58//! writer.write_image_data(&data).unwrap(); // Save
59//! ```
60//!
61
62#![forbid(unsafe_code)]
63// Silence certain clippy warnings until our MSRV is higher.
64//
65// The #[default] attribute was stabilized in Rust 1.62.0.
66#![allow(clippy::derivable_impls)]
67// IIUC format args capture was stabilized in Rust 1.58.1.
68#![allow(clippy::uninlined_format_args)]
69#![cfg_attr(feature = "unstable", feature(portable_simd))]
70
71mod adam7;
72pub mod chunk;
73mod common;
74mod decoder;
75mod encoder;
76mod filter;
77mod srgb;
78pub mod text_metadata;
79mod traits;
80
81pub use crate::adam7::{
82    expand_pass as expand_interlaced_row, expand_pass_splat as splat_interlaced_row,
83};
84
85pub use crate::adam7::{Adam7Info, Adam7Variant};
86pub use crate::common::*;
87pub use crate::decoder::stream::{DecodeOptions, Decoded, DecodingError, StreamingDecoder};
88pub use crate::decoder::{Decoder, InterlaceInfo, InterlacedRow, Limits, OutputInfo, Reader};
89pub use crate::decoder::{UnfilterBuf, UnfilterRegion};
90pub use crate::encoder::{Encoder, EncodingError, StreamWriter, Writer};
91pub use crate::filter::Filter;
92
93#[cfg(test)]
94pub(crate) mod test_utils;
95
96#[cfg(feature = "benchmarks")]
97pub mod benchable_apis;
png/lib.rs

png/
lib.rs
