| adam7.rs |
Utility functions related to handling of
[the Adam7 algorithm](https://en.wikipedia.org/wiki/Adam7_algorithm). |
37111 |
- |
| benchable_apis.rs |
Development-time-only helper module for exporting private APIs so that they can be benchmarked.
This module is gated behind the "benchmarks" feature. |
2016 |
- |
| chunk.rs |
Chunk types and functions |
3384 |
- |
| common.rs |
Common types shared between the encoder and decoder |
36343 |
- |
| decoder |
|
|
- |
| encoder.rs |
|
92077 |
- |
| filter |
|
|
- |
| lib.rs |
# PNG encoder and decoder
This crate contains a PNG encoder and decoder. It supports reading of single lines or whole frames.
## The decoder
The most important types for decoding purposes are [`Decoder`] and
[`Reader`]. They both wrap a [`std::io::Read`].
`Decoder` serves as a builder for `Reader`. Calling [`Decoder::read_info`] reads from the `Read` until the
image data is reached.
### Using the decoder
```
use std::fs::File;
use std::io::BufReader;
// The decoder is a build for reader and can be used to set various decoding options
// via `Transformations`. The default output transformation is `Transformations::IDENTITY`.
let decoder = png::Decoder::new(BufReader::new(File::open("tests/pngsuite/basi0g01.png").unwrap()));
let mut reader = decoder.read_info().unwrap();
// Allocate the output buffer.
let mut buf = vec![0; reader.output_buffer_size().unwrap()];
// Read the next frame. An APNG might contain multiple frames.
let info = reader.next_frame(&mut buf).unwrap();
// Grab the bytes of the image.
let bytes = &buf[..info.buffer_size()];
// Inspect more details of the last read frame.
let in_animation = reader.info().frame_control.is_some();
```
## Encoder
### Using the encoder
```no_run
// For reading and opening files
use std::path::Path;
use std::fs::File;
use std::io::BufWriter;
let path = Path::new(r"/path/to/image.png");
let file = File::create(path).unwrap();
let ref mut w = BufWriter::new(file);
let mut encoder = png::Encoder::new(w, 2, 1); // Width is 2 pixels and height is 1.
encoder.set_color(png::ColorType::Rgba);
encoder.set_depth(png::BitDepth::Eight);
encoder.set_source_gamma(png::ScaledFloat::from_scaled(45455)); // 1.0 / 2.2, scaled by 100000
encoder.set_source_gamma(png::ScaledFloat::new(1.0 / 2.2)); // 1.0 / 2.2, unscaled, but rounded
let source_chromaticities = png::SourceChromaticities::new( // Using unscaled instantiation here
(0.31270, 0.32900),
(0.64000, 0.33000),
(0.30000, 0.60000),
(0.15000, 0.06000)
);
encoder.set_source_chromaticities(source_chromaticities);
let mut writer = encoder.write_header().unwrap();
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.
writer.write_image_data(&data).unwrap(); // Save
```
|
3611 |
- |
| srgb.rs |
|
1041 |
- |
| test_utils.rs |
A set of test utilities.
There is some overlap between this module and `src/encoder.rs` module, but:
* This module (unlike `src/encoder.rs`) performs no validation of the data being written - this
allows building testcases that use arbitrary, potentially invalid PNGs as input.
* This module can be reused from `benches/decoder.rs` (a separate crate). |
4430 |
- |
| text_metadata.rs |
# Text chunks (tEXt/zTXt/iTXt) structs and functions
The [PNG spec](https://www.w3.org/TR/2003/REC-PNG-20031110/#11textinfo) optionally allows for
embedded text chunks in the file. They may appear either before or after the image data
chunks. There are three kinds of text chunks.
- `tEXt`: This has a `keyword` and `text` field, and is ISO 8859-1 encoded.
- `zTXt`: This is semantically the same as `tEXt`, i.e. it has the same fields and
encoding, but the `text` field is compressed before being written into the PNG file.
- `iTXt`: This chunk allows for its `text` field to be any valid UTF-8, and supports
compression of the text field as well.
The `ISO 8859-1` encoding technically doesn't allow any control characters
to be used, but in practice these values are encountered anyway. This can
either be the extended `ISO-8859-1` encoding with control characters or the
`Windows-1252` encoding. This crate assumes the `ISO-8859-1` encoding is
used.
## Reading text chunks
As a PNG is decoded, any text chunk encountered is appended the
[`Info`](`crate::common::Info`) struct, in the `uncompressed_latin1_text`,
`compressed_latin1_text`, and the `utf8_text` fields depending on whether the encountered
chunk is `tEXt`, `zTXt`, or `iTXt`.
```
use std::fs::File;
use std::io::BufReader;
use std::iter::FromIterator;
use std::path::PathBuf;
// Opening a png file that has a zTXt chunk
let decoder = png::Decoder::new(
BufReader::new(File::open("tests/text_chunk_examples/ztxt_example.png").unwrap())
);
let mut reader = decoder.read_info().unwrap();
// If the text chunk is before the image data frames, `reader.info()` already contains the text.
for text_chunk in &reader.info().compressed_latin1_text {
println!("{:?}", text_chunk.keyword); // Prints the keyword
println!("{:#?}", text_chunk); // Prints out the text chunk.
// To get the uncompressed text, use the `get_text` method.
println!("{}", text_chunk.get_text().unwrap());
}
```
## Writing text chunks
There are two ways to write text chunks: the first is to add the appropriate text structs directly to the encoder header before the header is written to file.
To add a text chunk at any point in the stream, use the `write_text_chunk` method.
```
# use png::text_metadata::{ITXtChunk, ZTXtChunk};
# use std::env;
# use std::fs::File;
# use std::io::BufWriter;
# use std::iter::FromIterator;
# use std::path::PathBuf;
# let file = File::create(PathBuf::from_iter(["target", "text_chunk.png"])).unwrap();
# let ref mut w = BufWriter::new(file);
let mut encoder = png::Encoder::new(w, 2, 1); // Width is 2 pixels and height is 1.
encoder.set_color(png::ColorType::Rgba);
encoder.set_depth(png::BitDepth::Eight);
// Adding text chunks to the header
encoder
.add_text_chunk(
"Testing tEXt".to_string(),
"This is a tEXt chunk that will appear before the IDAT chunks.".to_string(),
)
.unwrap();
encoder
.add_ztxt_chunk(
"Testing zTXt".to_string(),
"This is a zTXt chunk that is compressed in the png file.".to_string(),
)
.unwrap();
encoder
.add_itxt_chunk(
"Testing iTXt".to_string(),
"iTXt chunks support all of UTF8. Example: हिंदी.".to_string(),
)
.unwrap();
let mut writer = encoder.write_header().unwrap();
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.
writer.write_image_data(&data).unwrap(); // Save
// We can add a tEXt/zTXt/iTXt at any point before the encoder is dropped from scope. These chunks will be at the end of the png file.
let tail_ztxt_chunk = ZTXtChunk::new("Comment".to_string(), "A zTXt chunk after the image data.".to_string());
writer.write_text_chunk(&tail_ztxt_chunk).unwrap();
// The fields of the text chunk are public, so they can be mutated before being written to the file.
let mut tail_itxt_chunk = ITXtChunk::new("Author".to_string(), "सायंतन खान".to_string());
tail_itxt_chunk.compressed = true;
tail_itxt_chunk.language_tag = "hi".to_string();
tail_itxt_chunk.translated_keyword = "लेखक".to_string();
writer.write_text_chunk(&tail_itxt_chunk).unwrap();
``` |
22226 |
- |
| traits.rs |
|
1235 |
- |