Debian Codegraph @

.cargo/vendor/gif/src/lib.rs

raw
1 #![forbid(unsafe_code)]
2 //! # GIF en- and decoding library [![Build Status](https://github.com/image-rs/image-gif/workflows/Rust%20CI/badge.svg)](https://github.com/image-rs/image-gif/actions)
3 //!
4 //! GIF en- and decoder written in Rust ([API Documentation](https://docs.rs/gif)).
5 //!
6 //! # GIF encoding and decoding library
7 //!
8 //! This library provides all functions necessary to de- and encode GIF files.
9 //!
10 //! ## High level interface
11 //!
12 //! The high level interface consists of the two types
13 //! [`Encoder`](struct.Encoder.html) and [`Decoder`](struct.Decoder.html).
14 //!
15 //! ### Decoding GIF files
16 //!
17 //! ```rust
18 //! // Open the file
19 //! use std::fs::File;
20 //! let mut decoder = gif::DecodeOptions::new();
21 //! // Configure the decoder such that it will expand the image to RGBA.
22 //! decoder.set_color_output(gif::ColorOutput::RGBA);
23 //! // Read the file header
24 //! let file = File::open("tests/samples/sample_1.gif").unwrap();
25 //! let mut decoder = decoder.read_info(file).unwrap();
26 //! while let Some(frame) = decoder.read_next_frame().unwrap() {
27 //! // Process every frame
28 //! }
29 //! ```
30 //!
31 //!
32 //!
33 //! ### Encoding GIF files
34 //!
35 //! The encoder can be used so save simple computer generated images:
36 //!
37 //! ```rust
38 //! use gif::{Frame, Encoder, Repeat};
39 //! use std::fs::File;
40 //! use std::borrow::Cow;
41 //!
42 //! let color_map = &[0xFF, 0xFF, 0xFF, 0, 0, 0];
43 //! let (width, height) = (6, 6);
44 //! let mut beacon_states = [[
45 //! 0, 0, 0, 0, 0, 0,
46 //! 0, 1, 1, 0, 0, 0,
47 //! 0, 1, 1, 0, 0, 0,
48 //! 0, 0, 0, 1, 1, 0,
49 //! 0, 0, 0, 1, 1, 0,
50 //! 0, 0, 0, 0, 0, 0,
51 //! ], [
52 //! 0, 0, 0, 0, 0, 0,
53 //! 0, 1, 1, 0, 0, 0,
54 //! 0, 1, 0, 0, 0, 0,
55 //! 0, 0, 0, 0, 1, 0,
56 //! 0, 0, 0, 1, 1, 0,
57 //! 0, 0, 0, 0, 0, 0,
58 //! ]];
59 //! let mut image = File::create("tests/samples/beacon.gif").unwrap();;
60 //! let mut encoder = Encoder::new(&mut image, width, height, color_map).unwrap();
61 //! encoder.set_repeat(Repeat::Infinite).unwrap();
62 //! for state in &beacon_states {
63 //! let mut frame = Frame::default();
64 //! frame.width = width;
65 //! frame.height = height;
66 //! frame.buffer = Cow::Borrowed(&*state);
67 //! encoder.write_frame(&frame).unwrap();
68 //! }
69 //! ```
70 //!
71 //! [`Frame::from_*`](struct.Frame.html) can be used to convert a true color image to a paletted
72 //! image with a maximum of 256 colors:
73 //!
74 //! ```rust
75 //! # #[cfg(feature = "color_quant")] {
76 //! use std::fs::File;
77 //!
78 //! // Get pixel data from some source
79 //! let mut pixels: Vec<u8> = vec![0; 30_000];
80 //! // Create frame from data
81 //! let frame = gif::Frame::from_rgb(100, 100, &mut *pixels);
82 //! // Create encoder
83 //! let mut image = File::create("target/indexed_color.gif").unwrap();
84 //! let mut encoder = gif::Encoder::new(&mut image, frame.width, frame.height, &[]).unwrap();
85 //! // Write frame to file
86 //! encoder.write_frame(&frame).unwrap();
87 //! # }
88 //! ```
89
90 // TODO: make this compile
91 // ```rust
92 // use gif::{Frame, Encoder};
93 // use std::fs::File;
94 // let color_map = &[0, 0, 0, 0xFF, 0xFF, 0xFF];
95 // let mut frame = Frame::default();
96 // // Generate checkerboard lattice
97 // for (i, j) in (0..10).zip(0..10) {
98 // frame.buffer.push(if (i * j) % 2 == 0 {
99 // 1
100 // } else {
101 // 0
102 // })
103 // }
104 // # (|| {
105 // {
106 // let mut file = File::create("test.gif")?;
107 // let mut encoder = Encoder::new(&mut file, 100, 100);
108 // encoder.write_global_palette(color_map)?.write_frame(&frame)
109 // }
110 // # })().unwrap();
111 // ```
112 #![deny(missing_docs)]
113 #![cfg(feature = "std")]
114 #![allow(unknown_lints)] // Certain lints only apply to later versions of Rust
115 #![allow(clippy::manual_range_contains)]
116 #![allow(clippy::new_without_default)]
117 #![deny(clippy::alloc_instead_of_core)]
118 #![deny(clippy::std_instead_of_alloc)]
119 #![deny(clippy::std_instead_of_core)]
120 #![no_std]
121
122 #[macro_use]
123 extern crate alloc;
124 extern crate std;
125
126 mod common;
127 mod encoder;
128 mod reader;
129 mod traits;
130
131 pub use crate::common::{AnyExtension, DisposalMethod, Extension, Frame};
132
133 pub use crate::reader::{ColorOutput, MemoryLimit};
134 pub use crate::reader::{DecodeOptions, Decoder, Version};
135 pub use crate::reader::{DecodingError, DecodingFormatError};
136
137 pub use crate::encoder::{Encoder, EncodingError, EncodingFormatError, ExtensionData, Repeat};
138
139 /// Low-level, advanced decoder. Prefer [`Decoder`] instead, which can stream frames too.
140 pub mod streaming_decoder {
141 pub use crate::common::Block;
142 pub use crate::reader::{Decoded, FrameDataType, FrameDecoder, OutputBuffer, StreamingDecoder};
143 }
144
145 #[cfg(feature = "color_quant")]
146 macro_rules! insert_as_doc {
147 { $content:expr } => {
148 #[allow(unused_doc_comments)]
149 #[doc = $content] extern "C" { }
150 }
151 }
152
153 // Provides the README.md as doc, to ensure the example works!
154 #[cfg(feature = "color_quant")]
155 insert_as_doc!(include_str!("../README.md"));