Update readme and crate root doc

This commit is contained in:
Ivan Smirnov 2022-01-04 03:10:55 +03:00
parent f3120d5df3
commit 6884969222
2 changed files with 48 additions and 4 deletions

View file

@ -9,10 +9,7 @@
Fast encoder/decoder for [QOI image format](https://qoiformat.org/), implemented in pure and safe Rust. Fast encoder/decoder for [QOI image format](https://qoiformat.org/), implemented in pure and safe Rust.
Quick summary: - One of the [fastest](#benchmarks) QOI encoders/decoders out there.
- One of the [fastest](https://github.com/aldanor/qoi-fast#benchmarks)
QOI encoders/decoders out there.
- Compliant with the [latest](https://qoiformat.org/qoi-specification.pdf) QOI format specification. - Compliant with the [latest](https://qoiformat.org/qoi-specification.pdf) QOI format specification.
- Zero unsafe code. - Zero unsafe code.
- Supports decoding from / encoding to `std::io` streams directly. - Supports decoding from / encoding to `std::io` streams directly.

View file

@ -1,3 +1,50 @@
//! Fast encoder/decoder for [QOI image format](https://qoiformat.org/), implemented in pure and safe Rust.
//!
//! - One of the [fastest](#benchmarks) QOI encoders/decoders out there.
//! - Compliant with the [latest](https://qoiformat.org/qoi-specification.pdf) QOI format specification.
//! - Zero unsafe code.
//! - Supports decoding from / encoding to `std::io` streams directly.
//! - `no_std` support.
//! - Roundtrip-tested vs the reference C implementation; fuzz-tested.
//!
//! ### Examples
//!
//! ```rust
//! use qoi_fast::{encode_to_vec, decode_to_vec};
//!
//! let encoded = encode_to_vec(&pixels, width, height)?;
//! let (header, decoded) = decode_to_vec(&encoded)?;
//!
//! assert_eq!(header.width, width);
//! assert_eq!(header.height, height);
//! assert_eq!(decoded, pixels);
//! ```
//!
//! ### Benchmarks
//!
//! Comparison to the reference C implementation
//! (as of [00e34217](https://github.com/phoboslab/qoi/commit/00e34217)),
//! benchmarks timings collected on Apple M1 (1782 images, 1187 MB total):
//!
//! ```
//! codec decode:ms encode:ms decode:mp/s encode:mp/s
//!
//! qoi-c 4389.75 5524.18 283.5 225.3
//! qoi-fast 3026.68 4304.26 411.2 289.2
//! ```
//!
//! Benchmarks have also been run for all of the other Rust implementations
//! of QOI for comparison purposes and, at the time of writing this document,
//! this library proved to be the fastest one by a noticeable margin.
//!
//! ### `no_std`
//!
//! This crate supports `no_std` mode. By default, std is enabled via the `std`
//! feature. You can deactivate the `default-features` to target core instead.
//! In that case anything related to `std::io`, `std::error::Error` and heap
//! allocations is disabled. There is an additional `alloc` feature that can
//! be activated to bring back the support for heap allocations.
#![forbid(unsafe_code)] #![forbid(unsafe_code)]
#![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)] #![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)]
#![allow( #![allow(