| 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 |
|
| 70 |
mod adam7; |
| 71 |
pub mod chunk; |
| 72 |
mod common; |
| 73 |
mod decoder; |
| 74 |
mod encoder; |
| 75 |
mod filter; |
| 76 |
mod srgb; |
| 77 |
pub mod text_metadata; |
| 78 |
mod traits; |
| 79 |
|
| 80 |
pub use crate::adam7::{ |
| 81 |
expand_pass as expand_interlaced_row, expand_pass_splat as splat_interlaced_row, |
| 82 |
}; |
| 83 |
|
| 84 |
pub use crate::adam7::{Adam7Info, Adam7Variant}; |
| 85 |
pub use crate::common::*; |
| 86 |
pub use crate::decoder::stream::{DecodeOptions, Decoded, DecodingError, StreamingDecoder}; |
| 87 |
pub use crate::decoder::{Decoder, InterlaceInfo, InterlacedRow, Limits, OutputInfo, Reader}; |
| 88 |
pub use crate::decoder::{UnfilterBuf, UnfilterRegion}; |
| 89 |
pub use crate::encoder::{Encoder, EncodingError, StreamWriter, Writer}; |
| 90 |
pub use crate::filter::Filter; |
| 91 |
|
| 92 |
#[cfg(test)] |
| 93 |
pub(crate) mod test_utils; |
| 94 |
|
| 95 |
#[cfg(feature = "benchmarks")] |
| 96 |
pub mod benchable_apis; |