zune_jpeg/lib.rs
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]
167extern crate alloc;
168extern crate core;
169
170pub use zune_core;
171
172pub use crate::components::SampleRatios;
173pub use crate::decoder::{ImageInfo, JpegDecoder};
174pub use crate::marker::Marker;
175mod bitstream;
176mod color_convert;
177mod components;
178mod decoder;
179pub mod errors;
180mod headers;
181mod huffman;
182#[cfg(not(fuzzing))]
183mod idct;
184#[cfg(fuzzing)]
185pub mod idct;
186mod marker;
187mod mcu;
188mod mcu_prog;
189mod misc;
190mod unsafe_utils;
191mod unsafe_utils_avx2;
192mod unsafe_utils_neon;
193mod upsampler;
194mod worker;