aldanor / qoi-rust

VERY fast encoder/decoder for QOI image format in pure and safe Rust

qoi

Fast encoder/decoder for QOI image format, implemented in pure and safe Rust.

• One of the fastest QOI encoders/decoders out there.
• Compliant with the latest 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

use qoi::{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

             decode:Mp/s  encode:Mp/s  decode:MB/s  encode:MB/s
qoi.h              282.9        225.3        978.3        778.9
qoi-rust           427.4        290.0       1477.7       1002.9

• Reference C implementation: phoboslab/qoi@8d35d93.
• Benchmark timings were collected on an Apple M1 laptop.
• 2846 images from the suite provided upstream (tarball): all pngs except two with broken checksums.
• 1.32 GPixels in total with 4.46 GB of raw pixel data.

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.

Rust version

The minimum required Rust version for the latest crate version is 1.62.0.

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.

License

This project is dual-licensed under MIT and Apache 2.0.

qoi-rust's Issues

Where are the benchmarks against other Rust implementations?

Title

`qoi::decode::Bytes<'_>` is private

qoi::decode::Bytes<'_> is a private type, which makes the new method on qoi::Decoder useless. example:

use qoi;
fn main() {
    let arr = [0u8];
    let _ = qoi::Decoder::new(&arr[..]);
}

fails to compile with:

error: type `qoi::decode::Bytes<'_>` is private
 --> src\main.rs:4:13
  |
4 |     let _ = qoi::Decoder::new(&arr[..]);
  |             ^^^^^^^^^^^^^^^^^^^^^^^^^^^ private type

error: could not compile `p3u7ftpu3tdlywtmcnkgtitjmhkqa` due to previous error

Possible edge case in decoder when very first OP is QOI_OP_RUN

There's an edge-case that currently is handled differently by various decoders. At a first glance it looks like this decoder may not be spec-conformant. The spec is not clearly worded in this case, but I have decided to interpret it in a particular way now. Sorry about that!

Please see the original issue here phoboslab/qoi#258 for the details.

Two tests fail on s390x

I am packaging qoi-rust for Fedora and as part of that, we try to run the test suite on all architectures that are available in the build system. On s390x, two tests fail:

failures:
---- test_encode_index_3ch stdout ----
thread 'test_encode_index_3ch' panicked at 'assertion failed: `(left == right)`
  left: `[254, 101, 102, 103, 254, 1, 2, 3, 254]`,
 right: `[254, 101, 102, 103, 254, 1, 2, 3, 51]`', tests/test_chunks.rs:26:5
note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
---- test_encode_index_4ch stdout ----
thread 'test_encode_index_4ch' panicked at 'assertion failed: `(left == right)`
  left: `[255, 101, 102, 103, 104, 255, 1, 2, 3, 4, 56]`,
 right: `[255, 101, 102, 103, 104, 255, 1, 2, 3, 4, 54]`', tests/test_chunks.rs:26:5
failures:
    test_encode_index_3ch
    test_encode_index_4ch

Possibly some endianness issue as it is the only big endian architecture that we have?