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.3"
27//! ```
28//! # Examples
29//!
30//! ## Decode a JPEG file with default arguments.
31//!```no_run
32//! use std::fs::read;
33//! use zune_jpeg::JpegDecoder;
34//! let file_contents = read("a_jpeg.file").unwrap();
35//! let mut decoder = JpegDecoder::new(&file_contents);
36//! let mut pixels = decoder.decode().unwrap();
37//! ```
38//!
39//! ## Decode a JPEG file to RGBA format
40//!
41//! - Other (limited) supported formats are and BGR, BGRA
42//!
43//!```no_run
44//! use zune_core::colorspace::ColorSpace;
45//! use zune_core::options::DecoderOptions;
46//! use zune_jpeg::JpegDecoder;
47//!
48//! let mut options = DecoderOptions::default().jpeg_set_out_colorspace(ColorSpace::RGBA);
49//!
50//! let mut decoder = JpegDecoder::new_with_options(&[],options);
51//! let pixels = decoder.decode().unwrap();
52//! ```
53//!
54//! ## Decode an image and get it's width and height.
55//!```no_run
56//! use zune_jpeg::JpegDecoder;
57//!
58//! let mut decoder = JpegDecoder::new(&[]);
59//! decoder.decode_headers().unwrap();
60//! let image_info = decoder.info().unwrap();
61//! println!("{},{}",image_info.width,image_info.height)
62//! ```
63//! # Crate features.
64//! This crate tries to be as minimal as possible while being extensible
65//! enough to handle the complexities arising from parsing different types
66//! of jpeg images.
67//!
68//! Safety is a top concern that is why we provide both static ways to disable unsafe code,
69//! disabling x86 feature, and dynamic ,by using [`DecoderOptions::set_use_unsafe(false)`],
70//! both of these disable platform specific optimizations, which reduce the speed of decompression.
71//!
72//! Please do note that careful consideration has been taken to ensure that the unsafe paths
73//! are only unsafe because they depend on platform specific intrinsics, hence no need to disable them
74//!
75//! The crate tries to decode as many images as possible, as a best effort, even those violating the standard
76//! , this means a lot of images may get silent warnings and wrong output, but if you are sure you will be handling
77//! images that follow the spec, set `ZuneJpegOptions::set_strict` to true.
78//!
79//![`DecoderOptions::set_use_unsafe(false)`]: https://docs.rs/zune-core/0.2.1/zune_core/options/struct.DecoderOptions.html#method.set_use_unsafe
80
81#![warn(
82 clippy::correctness,
83 clippy::perf,
84 clippy::pedantic,
85 clippy::inline_always,
86 clippy::missing_errors_doc,
87 clippy::panic
88)]
89#![allow(
90 clippy::needless_return,
91 clippy::similar_names,
92 clippy::inline_always,
93 clippy::similar_names,
94 clippy::doc_markdown,
95 clippy::module_name_repetitions,
96 clippy::missing_panics_doc,
97 clippy::missing_errors_doc
98)]
99// no_std compatibility
100#![deny(clippy::std_instead_of_alloc, clippy::alloc_instead_of_core)]
101#![cfg_attr(not(feature = "x86"), forbid(unsafe_code))]
102#![cfg_attr(not(feature = "std"), no_std)]
103#![macro_use]
104extern crate alloc;
105extern crate core;
106
107pub use zune_core;
108
109pub use crate::decoder::{ImageInfo, JpegDecoder};
110
111mod bitstream;
112mod color_convert;
113mod components;
114mod decoder;
115pub mod errors;
116mod headers;
117mod huffman;
118#[cfg(not(fuzzing))]
119mod idct;
120#[cfg(fuzzing)]
121pub mod idct;
122mod marker;
123mod mcu;
124mod mcu_prog;
125mod misc;
126mod unsafe_utils;
127mod unsafe_utils_avx2;
128mod unsafe_utils_neon;
129mod upsampler;
130mod worker;