Debian Codegraph @

.cargo/vendor/zune-jpeg/src/lib.rs

raw
1 /*
2 * Copyright (c) 2023.
3 *
4 * This software is free software;
5 *
6 * You can redistribute it or modify it under terms of the MIT, Apache License or Zlib license
7 */
8
9 //!This crate provides a library for decoding valid
10 //! ITU-T Rec. T.851 (09/2005) ITU-T T.81 (JPEG-1) or JPEG images.
11 //!
12 //!
13 //!
14 //! # Features
15 //! - SSE and AVX accelerated functions to speed up certain decoding operations
16 //! - FAST and accurate 32 bit IDCT algorithm
17 //! - Fast color convert functions
18 //! - RGBA and RGBX (4-Channel) color conversion functions
19 //! - YCbCr to Luma(Grayscale) conversion.
20 //!
21 //! # Usage
22 //! Add zune-jpeg to the dependencies in the project Cargo.toml
23 //!
24 //! ```toml
25 //! [dependencies]
26 //! zune_jpeg = "0.5"
27 //! ```
28 //! # Examples
29 //!
30 //! ## Decode a JPEG file with default arguments.
31 //!```no_run
32 //! use std::fs::read;
33 //! use std::io::BufReader;
34 //! use zune_jpeg::JpegDecoder;
35 //! let file_contents = BufReader::new(std::fs::File::open("a_jpeg.file").unwrap());
36 //! let mut decoder = JpegDecoder::new(file_contents);
37 //! let mut pixels = decoder.decode().unwrap();
38 //! ```
39 //!
40 //! ## Migrating from version 0.4--
41 //!
42 //! ### Motivation
43 //! zune v 0.5 reworks mainly the internal architecture of how we perform I/O
44 //! ,before the decoder accepted byte slices that represent the whole data as contiguous
45 //! but that was not ideal for all use cases, increasing memory e.g on massive files that had
46 //! to be read to memory.
47 //!
48 //! With v 0.5 a new I/O system is introduced, which generally introduces mechanisms to process
49 //! `std::io::Read + std::io::Seek` type of data feeds, (but which works in no-std), which means...
50 //!
51 //! ### What changes
52 //!
53 //! I/O code that looked like this
54 //!
55 //!```ignore
56 //! use zune_core::colorspace::ColorSpace;
57 //! use zune_jpeg::JpegDecoder;
58 //! // Read file into memory
59 //! let image = std::fs::read("image.jpg").unwrap();
60 //! // Make a decoder from the slice
61 //! let mut decoder = JpegDecoder::new(&image);
62 //! // decode
63 //! decoder.decode().unwrap();
64 //! ```
65 //!
66 //! Now can be rewritten in two ways.
67 //!
68 //! 1. File I/O (Using bufreader)
69 //!
70 //!```no_run
71 //! use std::io::BufReader;
72 //! use zune_core::colorspace::ColorSpace;
73 //! use zune_jpeg::JpegDecoder;
74 //!
75 //! let image = BufReader::new(std::fs::File::open("image.jpg").unwrap());
76 //! let mut decoder = JpegDecoder::new(image);
77 //! // decode
78 //! decoder.decode().unwrap();
79 //! ```
80 //!
81 //! 2. Reading to memory (but wrapping it in a Cursor like object)
82 //!```no_run
83 //! use zune_core::bytestream::ZCursor;
84 //! use zune_jpeg::JpegDecoder;
85 //!
86 //! let image_data =std::fs::read("image.jpg").unwrap();
87 //! // Alternatively, you can use std::io::Cursor,
88 //! // but it is better speed wise to use ZCursor, and it also works in
89 //! // no-std environments
90 //! let mut cursor = ZCursor::new(image_data);
91 //! // use the wrapped item
92 //! let mut decoder = JpegDecoder::new(cursor);
93 //! // decode
94 //! decoder.decode().unwrap();
95 //! ```
96 //!
97 //! 3. Anything that implements [ZByteReaderTrait](zune_core::bytestream::traits::ZByteReaderTrait)
98 //!
99 //! ## Decode a JPEG file to RGBA format
100 //!
101 //! - Other (limited) supported formats are and BGR, BGRA
102 //!
103 //!```no_run
104 //! use zune_core::bytestream::ZCursor;
105 //! use zune_core::colorspace::ColorSpace;
106 //! use zune_core::options::DecoderOptions;
107 //! use zune_jpeg::JpegDecoder;
108 //!
109 //! let mut options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA);
110 //!
111 //! let mut decoder = JpegDecoder::new_with_options(ZCursor::new(&[]),options);
112 //! let pixels = decoder.decode().unwrap();
113 //! ```
114 //!
115 //! ## Decode an image and get its width and height.
116 //!```no_run
117 //! use zune_core::bytestream::ZCursor;
118 //! use zune_jpeg::JpegDecoder;
119 //!
120 //! let mut decoder = JpegDecoder::new(ZCursor::new(&[]));
121 //! decoder.decode_headers().unwrap();
122 //! let image_info = decoder.info().unwrap();
123 //! println!("{},{}",image_info.width,image_info.height)
124 //! ```
125 //! # Crate features.
126 //! This crate tries to be as minimal as possible while being extensible
127 //! enough to handle the complexities arising from parsing different types
128 //! of jpeg images.
129 //!
130 //! Safety is a top concern that is why we provide both static ways to disable unsafe code,
131 //! disabling x86 feature, and dynamic ,by using [`DecoderOptions::set_use_unsafe(false)`],
132 //! both of these disable platform specific optimizations, which reduce the speed of decompression.
133 //!
134 //! Please do note that careful consideration has been taken to ensure that the unsafe paths
135 //! are only unsafe because they depend on platform specific intrinsics, hence no need to disable them
136 //!
137 //! The crate tries to decode as many images as possible, as a best effort, even those violating the standard
138 //! , this means a lot of images may get silent warnings and wrong output, but if you are sure you will be handling
139 //! images that follow the spec, set `ZuneJpegOptions::set_strict` to true.
140 //!
141 //![`DecoderOptions::set_use_unsafe(false)`]: https://docs.rs/zune-core/latest/zune_core/options/struct.DecoderOptions.html#method.set_use_unsafe
142
143 #![warn(
144 clippy::correctness,
145 clippy::perf,
146 clippy::pedantic,
147 clippy::inline_always,
148 clippy::missing_errors_doc,
149 clippy::panic
150 )]
151 #![allow(
152 clippy::needless_return,
153 clippy::similar_names,
154 clippy::inline_always,
155 clippy::similar_names,
156 clippy::doc_markdown,
157 clippy::module_name_repetitions,
158 clippy::missing_panics_doc,
159 clippy::missing_errors_doc
160 )]
161 // no_std compatibility
162 #![deny(clippy::std_instead_of_alloc, clippy::alloc_instead_of_core)]
163 #![cfg_attr(not(any(feature = "x86", feature = "neon")), forbid(unsafe_code))]
164 #![cfg_attr(not(feature = "std"), no_std)]
165 #![cfg_attr(feature = "portable_simd", feature(portable_simd))]
166 #![macro_use]
167 extern crate alloc;
168 extern crate core;
169
170 pub use zune_core;
171
172 pub use crate::decoder::{ImageInfo, JpegDecoder};
173 pub use crate::marker::Marker;
174 mod bitstream;
175 mod color_convert;
176 mod components;
177 mod decoder;
178 pub mod errors;
179 mod headers;
180 mod huffman;
181 #[cfg(not(fuzzing))]
182 mod idct;
183 #[cfg(fuzzing)]
184 pub mod idct;
185 mod marker;
186 mod mcu;
187 mod mcu_prog;
188 mod misc;
189 mod unsafe_utils;
190 mod unsafe_utils_avx2;
191 mod unsafe_utils_neon;
192 mod upsampler;
193 mod worker;