| 1 |
# Zune-JPEG |
| 2 |
|
| 3 |
A fast, correct and safe jpeg decoder in pure Rust. |
| 4 |
|
| 5 |
## Usage |
| 6 |
|
| 7 |
The library provides a simple-to-use API for jpeg decoding |
| 8 |
and an ability to add options to influence decoding. |
| 9 |
|
| 10 |
### Example |
| 11 |
|
| 12 |
```Rust |
| 13 |
// Import the library |
| 14 |
use zune_jpeg::JpegDecoder; |
| 15 |
use std::fs::read; |
| 16 |
|
| 17 |
fn main()->Result<(),DecoderErrors> { |
| 18 |
// load some jpeg data |
| 19 |
let data = read("cat.jpg").unwrap(); |
| 20 |
// create a decoder |
| 21 |
let mut decoder = JpegDecoder::new(&data); |
| 22 |
// decode the file |
| 23 |
let pixels = decoder.decode()?; |
| 24 |
} |
| 25 |
``` |
| 26 |
|
| 27 |
The decoder supports more manipulations via `DecoderOptions`, |
| 28 |
see additional documentation in the library. |
| 29 |
|
| 30 |
## Goals |
| 31 |
|
| 32 |
The implementation aims to have the following goals achieved, |
| 33 |
in order of importance |
| 34 |
|
| 35 |
1. Safety - Do not segfault on errors or invalid input. Panics are okay, but |
| 36 |
should be fixed when reported. `unsafe` is only used for SIMD intrinsics, |
| 37 |
and can be turned off entirely both at compile time and at runtime. |
| 38 |
2. Speed - Get the data as quickly as possible, which means |
| 39 |
1. Platform intrinsics code where justifiable |
| 40 |
2. Carefully written platform independent code that allows the |
| 41 |
compiler to vectorize it. |
| 42 |
3. Regression tests. |
| 43 |
4. Watch the memory usage of the program |
| 44 |
3. Usability - Provide utility functions like different color conversions functions. |
| 45 |
|
| 46 |
## Non-Goals |
| 47 |
|
| 48 |
- Bit identical results with libjpeg/libjpeg-turbo will never be an aim of this library. |
| 49 |
Jpeg is a lossy format with very few parts specified by the standard |
| 50 |
(i.e it doesn't give a reference upsampling and color conversion algorithm) |
| 51 |
|
| 52 |
## Features |
| 53 |
|
| 54 |
- [x] A Pretty fast 8*8 integer IDCT. |
| 55 |
- [x] Fast Huffman Decoding |
| 56 |
- [x] Fast color convert functions. |
| 57 |
- [x] Support for extended colorspaces like GrayScale and RGBA |
| 58 |
- [X] Single-threaded decoding. |
| 59 |
- [X] Support for four component JPEGs, and esoteric color schemes like CYMK |
| 60 |
- [X] Support for `no_std` |
| 61 |
- [X] BGR/BGRA decoding support. |
| 62 |
|
| 63 |
## Crate Features |
| 64 |
|
| 65 |
| feature | on | Capabilities | |
| 66 |
|---------|-----|---------------------------------------------------------------------------------------------| |
| 67 |
| `x86` | yes | Enables `x86` specific instructions, specifically `avx` and `sse` for accelerated decoding. | |
| 68 |
| `std` | yes | Enable linking to the `std` crate | |
| 69 |
|
| 70 |
Note that the `x86` features are automatically disabled on platforms that aren't x86 during compile |
| 71 |
time hence there is no need to disable them explicitly if you are targeting such a platform. |
| 72 |
|
| 73 |
## Using in a `no_std` environment |
| 74 |
|
| 75 |
The crate can be used in a `no_std` environment with the `alloc` feature. |
| 76 |
|
| 77 |
But one is required to link to a working allocator for whatever environment the decoder |
| 78 |
will be running on |
| 79 |
|
| 80 |
## Debug vs release |
| 81 |
|
| 82 |
The decoder heavily relies on platform specific intrinsics, namely AVX2 and SSE to gain speed-ups in decoding, |
| 83 |
but they [perform poorly](https://godbolt.org/z/vPq57z13b) in debug builds. To get reasonable performance even |
| 84 |
when compiling your program in debug mode, add this to your `Cargo.toml`: |
| 85 |
|
| 86 |
```toml |
| 87 |
# `zune-jpeg` package will be always built with optimizations |
| 88 |
[profile.dev.package.zune-jpeg] |
| 89 |
opt-level = 3 |
| 90 |
``` |
| 91 |
|
| 92 |
## Benchmarks |
| 93 |
|
| 94 |
The library tries to be at fast as [libjpeg-turbo] while being as safe as possible. |
| 95 |
Platform specific intrinsics help get speed up intensive operations ensuring we can almost |
| 96 |
match [libjpeg-turbo] speeds but speeds are always +- 10 ms of this library. |
| 97 |
|
| 98 |
For more up-to-date benchmarks, see the online repo with |
| 99 |
benchmarks [here](https://etemesi254.github.io/assets/criterion/report/index.html) |
| 100 |
|
| 101 |
|
| 102 |
[libjpeg-turbo]:https://github.com/libjpeg-turbo/libjpeg-turbo/ |
| 103 |
|
| 104 |
[image-rs/jpeg-decoder]:https://github.com/image-rs/jpeg-decoder/tree/master/src |