Debian Codegraph @

.cargo/vendor/zune-jpeg-0.4.21/README.md

raw
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