| 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; |