Debian Codegraph @

.cargo/vendor/image/src/lib.rs

raw
1 //! # Overview
2 //!
3 //! This crate provides native rust implementations of image encoding and decoding as well as some
4 //! basic image manipulation functions. Additional documentation can currently also be found in the
5 //! [README.md file which is most easily viewed on
6 //! github](https://github.com/image-rs/image/blob/main/README.md).
7 //!
8 //! There are two core problems for which this library provides solutions: a unified interface for image
9 //! encodings and simple generic buffers for their content. It's possible to use either feature
10 //! without the other. The focus is on a small and stable set of common operations that can be
11 //! supplemented by other specialized crates. The library also prefers safe solutions with few
12 //! dependencies.
13 //!
14 //! # High level API
15 //!
16 //! Load images using [`ImageReader`](crate::ImageReader):
17 //!
18 //! ```rust,no_run
19 //! use std::io::Cursor;
20 //! use image::ImageReader;
21 //! # fn main() -> Result<(), image::ImageError> {
22 //! # let bytes = vec![0u8];
23 //!
24 //! let img = ImageReader::open("myimage.png")?.decode()?;
25 //! let img2 = ImageReader::new(Cursor::new(bytes)).with_guessed_format()?.decode()?;
26 //! # Ok(())
27 //! # }
28 //! ```
29 //!
30 //! And save them using [`save`] or [`write_to`] methods:
31 //!
32 //! ```rust,no_run
33 //! # use std::io::{Write, Cursor};
34 //! # use image::{DynamicImage, ImageFormat};
35 //! # #[cfg(feature = "png")]
36 //! # fn main() -> Result<(), image::ImageError> {
37 //! # let img: DynamicImage = unimplemented!();
38 //! # let img2: DynamicImage = unimplemented!();
39 //! img.save("empty.jpg")?;
40 //!
41 //! let mut bytes: Vec<u8> = Vec::new();
42 //! img2.write_to(&mut Cursor::new(&mut bytes), image::ImageFormat::Png)?;
43 //! # Ok(())
44 //! # }
45 //! # #[cfg(not(feature = "png"))] fn main() {}
46 //! ```
47 //!
48 //! With default features, the crate includes support for [many common image formats](codecs/index.html#supported-formats).
49 //!
50 //! [`save`]: enum.DynamicImage.html#method.save
51 //! [`write_to`]: enum.DynamicImage.html#method.write_to
52 //! [`ImageReader`]: struct.Reader.html
53 //!
54 //! # Image buffers
55 //!
56 //! The two main types for storing images:
57 //! * [`ImageBuffer`] which holds statically typed image contents.
58 //! * [`DynamicImage`] which is an enum over the supported `ImageBuffer` formats
59 //! and supports conversions between them.
60 //!
61 //! As well as a few more specialized options:
62 //! * [`GenericImage`] trait for a mutable image buffer.
63 //! * [`GenericImageView`] trait for read only references to a `GenericImage`.
64 //! * [`flat`] module containing types for interoperability with generic channel
65 //! matrices and foreign interfaces.
66 //!
67 //! [`GenericImageView`]: trait.GenericImageView.html
68 //! [`GenericImage`]: trait.GenericImage.html
69 //! [`ImageBuffer`]: struct.ImageBuffer.html
70 //! [`DynamicImage`]: enum.DynamicImage.html
71 //! [`flat`]: flat/index.html
72 //!
73 //! # Low level encoding/decoding API
74 //!
75 //! Implementations of [`ImageEncoder`] provides low level control over encoding:
76 //! ```rust,no_run
77 //! # use std::io::Write;
78 //! # use image::DynamicImage;
79 //! # use image::ImageEncoder;
80 //! # #[cfg(feature = "jpeg")]
81 //! # fn main() -> Result<(), image::ImageError> {
82 //! # use image::codecs::jpeg::JpegEncoder;
83 //! # let img: DynamicImage = unimplemented!();
84 //! # let writer: Box<dyn Write> = unimplemented!();
85 //! let encoder = JpegEncoder::new_with_quality(&mut writer, 95);
86 //! img.write_with_encoder(encoder)?;
87 //! # Ok(())
88 //! # }
89 //! # #[cfg(not(feature = "jpeg"))] fn main() {}
90 //! ```
91 //! While [`ImageDecoder`] and [`ImageDecoderRect`] give access to more advanced decoding options:
92 //!
93 //! ```rust,no_run
94 //! # use std::io::{BufReader, Cursor};
95 //! # use image::DynamicImage;
96 //! # use image::ImageDecoder;
97 //! # #[cfg(feature = "png")]
98 //! # fn main() -> Result<(), image::ImageError> {
99 //! # use image::codecs::png::PngDecoder;
100 //! # let img: DynamicImage = unimplemented!();
101 //! # let reader: BufReader<Cursor<&[u8]>> = unimplemented!();
102 //! let decoder = PngDecoder::new(&mut reader)?;
103 //! let icc = decoder.icc_profile();
104 //! let img = DynamicImage::from_decoder(decoder)?;
105 //! # Ok(())
106 //! # }
107 //! # #[cfg(not(feature = "png"))] fn main() {}
108 //! ```
109 //!
110 //! [`DynamicImage::from_decoder`]: enum.DynamicImage.html#method.from_decoder
111 //! [`ImageDecoderRect`]: trait.ImageDecoderRect.html
112 //! [`ImageDecoder`]: trait.ImageDecoder.html
113 //! [`ImageEncoder`]: trait.ImageEncoder.html
114 #![warn(missing_docs)]
115 #![warn(unused_qualifications)]
116 #![deny(unreachable_pub)]
117 #![deny(deprecated)]
118 #![deny(missing_copy_implementations)]
119 #![cfg_attr(all(test, feature = "benchmarks"), feature(test))]
120 #![cfg_attr(docsrs, feature(doc_cfg))]
121
122 #[cfg(all(test, feature = "benchmarks"))]
123 extern crate test;
124
125 #[cfg(test)]
126 #[macro_use]
127 extern crate quickcheck;
128
129 pub use crate::color::{ColorType, ExtendedColorType};
130
131 pub use crate::color::{Luma, LumaA, Rgb, Rgba};
132
133 pub use crate::error::{ImageError, ImageResult};
134
135 pub use crate::images::generic_image::{GenericImage, GenericImageView, Pixels};
136
137 pub use crate::images::sub_image::SubImage;
138
139 pub use crate::images::buffer::{
140 ConvertColorOptions,
141 GrayAlphaImage,
142 GrayImage,
143 // Image types
144 ImageBuffer,
145 Rgb32FImage,
146 RgbImage,
147 Rgba32FImage,
148 RgbaImage,
149 };
150
151 pub use crate::flat::FlatSamples;
152
153 // Traits
154 pub use crate::traits::{EncodableLayout, Pixel, PixelWithColorType, Primitive};
155
156 // Opening and loading images
157 pub use crate::images::dynimage::{
158 image_dimensions, load_from_memory, load_from_memory_with_format, open,
159 write_buffer_with_format,
160 };
161 pub use crate::io::free_functions::{guess_format, load, save_buffer, save_buffer_with_format};
162
163 pub use crate::io::{
164 decoder::{AnimationDecoder, ImageDecoder, ImageDecoderRect},
165 encoder::ImageEncoder,
166 format::ImageFormat,
167 image_reader_type::ImageReader,
168 limits::{LimitSupport, Limits},
169 };
170
171 pub use crate::images::dynimage::DynamicImage;
172
173 pub use crate::animation::{Delay, Frame, Frames};
174
175 // More detailed error type
176 pub mod error;
177
178 /// Iterators and other auxiliary structure for the `ImageBuffer` type.
179 pub mod buffer {
180 // Only those not exported at the top-level
181 pub use crate::images::buffer::{
182 ConvertBuffer, EnumeratePixels, EnumeratePixelsMut, EnumerateRows, EnumerateRowsMut,
183 Pixels, PixelsMut, Rows, RowsMut,
184 };
185
186 #[cfg(feature = "rayon")]
187 pub use crate::images::buffer_par::*;
188 }
189
190 // Math utils
191 pub mod math;
192
193 // Image processing functions
194 pub mod imageops;
195
196 // Buffer representations for ffi.
197 pub use crate::images::flat;
198
199 /// Encoding and decoding for various image file formats.
200 ///
201 /// # Supported formats
202 ///
203 /// | Feature | Format | Notes
204 /// | ------- | -------- | -----
205 /// | `avif` | AVIF | Decoding requires the `avif-native` feature, uses the libdav1d C library.
206 /// | `bmp` | BMP |
207 /// | `dds` | DDS | Only decoding is supported.
208 /// | `exr` | OpenEXR |
209 /// | `ff` | Farbfeld |
210 /// | `gif` | GIF |
211 /// | `hdr` | HDR |
212 /// | `ico` | ICO |
213 /// | `jpeg` | JPEG |
214 /// | `png` | PNG |
215 /// | `pnm` | PNM |
216 /// | `qoi` | QOI |
217 /// | `tga` | TGA |
218 /// | `tiff` | TIFF |
219 /// | `webp` | WebP | Only lossless encoding is currently supported.
220 ///
221 /// ## A note on format specific features
222 ///
223 /// One of the main goals of `image` is stability, in runtime but also for programmers. This
224 /// ensures that performance as well as safety fixes reach a majority of its user base with little
225 /// effort. Re-exporting all details of its dependencies would run counter to this goal as it
226 /// linked _all_ major version bumps between them and `image`. As such, we are wary of exposing too
227 /// many details, or configuration options, that are not shared between different image formats.
228 ///
229 /// Nevertheless, the advantage of precise control is hard to ignore. We will thus consider
230 /// _wrappers_, not direct re-exports, in either of the following cases:
231 ///
232 /// 1. A standard specifies that configuration _x_ is required for decoders/encoders and there
233 /// exists an essentially canonical way to control it.
234 /// 2. At least two different implementations agree on some (sub-)set of features in practice.
235 /// 3. A technical argument including measurements of the performance, space benefits, or otherwise
236 /// objectively quantified benefits can be made, and the added interface is unlikely to require
237 /// breaking changes.
238 ///
239 /// Features that fulfill two or more criteria are preferred.
240 ///
241 /// Re-exports of dependencies that reach version `1` will be discussed when it happens.
242 pub mod codecs {
243 #[cfg(any(feature = "avif", feature = "avif-native"))]
244 pub mod avif;
245 #[cfg(feature = "bmp")]
246 pub mod bmp;
247 #[cfg(feature = "dds")]
248 pub mod dds;
249 #[cfg(feature = "ff")]
250 pub mod farbfeld;
251 #[cfg(feature = "gif")]
252 pub mod gif;
253 #[cfg(feature = "hdr")]
254 pub mod hdr;
255 #[cfg(feature = "ico")]
256 pub mod ico;
257 #[cfg(feature = "jpeg")]
258 pub mod jpeg;
259 #[cfg(feature = "exr")]
260 pub mod openexr;
261 #[cfg(feature = "png")]
262 pub mod png;
263 #[cfg(feature = "pnm")]
264 pub mod pnm;
265 #[cfg(feature = "qoi")]
266 pub mod qoi;
267 #[cfg(feature = "tga")]
268 pub mod tga;
269 #[cfg(feature = "tiff")]
270 pub mod tiff;
271 #[cfg(feature = "webp")]
272 pub mod webp;
273
274 #[cfg(feature = "dds")]
275 mod dxt;
276 }
277
278 mod animation;
279 mod color;
280 pub mod hooks;
281 mod images;
282 /// Deprecated io module the original io module has been renamed to `image_reader`.
283 /// This is going to be internal.
284 pub mod io;
285 pub mod metadata;
286 //TODO delete this module after a few releases
287 mod traits;
288 mod utils;
289
290 // Can't use the macro-call itself within the `doc` attribute. So force it to eval it as part of
291 // the macro invocation.
292 //
293 // The inspiration for the macro and implementation is from
294 // <https://github.com/GuillaumeGomez/doc-comment>
295 //
296 // MIT License
297 //
298 // Copyright (c) 2018 Guillaume Gomez
299 macro_rules! insert_as_doc {
300 { $content:expr } => {
301 #[allow(unused_doc_comments)]
302 #[doc = $content] extern "Rust" { }
303 }
304 }
305
306 // Provides the README.md as doc, to ensure the example works!
307 insert_as_doc!(include_str!("../README.md"));