From 68849692228a82eaf3b181fc78d6057c9a86e609 Mon Sep 17 00:00:00 2001 From: Ivan Smirnov Date: Tue, 4 Jan 2022 03:10:55 +0300 Subject: [PATCH] Update readme and crate root doc --- README.md | 5 +---- src/lib.rs | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 48 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index 6aa1d56..9e4fe39 100644 --- a/README.md +++ b/README.md @@ -9,10 +9,7 @@ Fast encoder/decoder for [QOI image format](https://qoiformat.org/), implemented in pure and safe Rust. -Quick summary: - -- One of the [fastest](https://github.com/aldanor/qoi-fast#benchmarks) - QOI encoders/decoders out there. +- 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. diff --git a/src/lib.rs b/src/lib.rs index 9b23f0b..a218af3 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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)] #![warn(clippy::all, clippy::pedantic, clippy::nursery, clippy::cargo)] #![allow(