gif/reader/
mod.rs

Help
1use std::borrow::Cow;
2use std::io;
3use std::iter::FusedIterator;
4use std::mem;
5
6use std::io::prelude::*;
7use std::num::NonZeroU64;
8use std::convert::{TryFrom, TryInto};
9
10use crate::Repeat;
11use crate::common::{Block, Frame};
12
13mod decoder;
14mod converter;
15
16pub use self::decoder::{
17    PLTE_CHANNELS, StreamingDecoder, Decoded, DecodingError, DecodingFormatError,
18    Version, FrameDataType, OutputBuffer, FrameDecoder
19};
20
21use self::converter::PixelConverter;
22pub use self::converter::ColorOutput;
23
24#[derive(Clone, Debug)]
25/// The maximum amount of memory the decoder is allowed to use for each frame
26pub enum MemoryLimit {
27    /// Enforce no memory limit.
28    ///
29    /// If you intend to process images from unknown origins this is a potentially dangerous
30    /// constant to use, as your program could be vulnerable to decompression bombs. That is,
31    /// malicious images crafted specifically to require an enormous amount of memory to process
32    /// while having a disproportionately small file size.
33    ///
34    /// The risks for modern machines are a bit smaller as the size of each frame cannot
35    /// exceed 16GiB, but this is still a significant amount of memory.
36    Unlimited,
37    /// Limit the amount of memory that can be used for a single frame to this many bytes.
38    ///
39    /// It may not be enforced precisely due to allocator overhead
40    /// and the decoder potentially allocating small auxiliary buffers,
41    /// but it will precisely limit the size of the output buffer for each frame.
42    //
43    // The `NonZero` type is used to make FFI simpler.
44    // Due to the guaranteed niche optimization, `Unlimited` will be represented as `0`,
45    // and the whole enum as a simple `u64`.
46    Bytes(NonZeroU64),
47}
48
49impl MemoryLimit {
50    fn check_size(&self, size: usize) -> Result<(), DecodingError> {
51        match self {
52            MemoryLimit::Unlimited => Ok(()),
53            MemoryLimit::Bytes(limit) => {
54                if size as u64 <= limit.get() {
55                    Ok(())
56                } else {
57                    Err(DecodingError::format("memory limit reached"))
58                }
59            },
60        }
61    }
62
63    fn buffer_size(&self, color: ColorOutput, width: u16, height: u16) -> Option<usize> {
64        let pixels = u64::from(width) * u64::from(height);
65
66        let bytes_per_pixel = match color {
67            ColorOutput::Indexed => 1,
68            ColorOutput::RGBA => 4,
69        };
70
71        // This cannot overflow because the maximum possible value is 16GiB, well within u64 range
72        let total_bytes = pixels * bytes_per_pixel;
73
74        // On 32-bit platforms the size of the output buffer may not be representable
75        let usize_bytes = usize::try_from(total_bytes).ok()?;
76
77        match self {
78            MemoryLimit::Unlimited => Some(usize_bytes),
79            MemoryLimit::Bytes(limit) => {
80                if total_bytes > limit.get() {
81                    None
82                } else {
83                    Some(usize_bytes)
84                }
85            },
86        }
87    }
88}
89
90/// Options for opening a GIF decoder. [`DecodeOptions::read_info`] will start the decoder.
91#[derive(Clone, Debug)]
92pub struct DecodeOptions {
93    memory_limit: MemoryLimit,
94    color_output: ColorOutput,
95    check_frame_consistency: bool,
96    skip_frame_decoding: bool,
97    check_for_end_code: bool,
98    allow_unknown_blocks: bool,
99}
100
101impl Default for DecodeOptions {
102    fn default() -> Self {
103        Self::new()
104    }
105}
106
107impl DecodeOptions {
108    /// Creates a new decoder builder
109    #[must_use]
110    #[inline]
111    pub fn new() -> DecodeOptions {
112        DecodeOptions {
113            memory_limit: MemoryLimit::Bytes(50_000_000.try_into().unwrap()), // 50 MB
114            color_output: ColorOutput::Indexed,
115            check_frame_consistency: false,
116            skip_frame_decoding: false,
117            check_for_end_code: false,
118            allow_unknown_blocks: false,
119        }
120    }
121
122    /// Configure how color data is decoded.
123    #[inline]
124    pub fn set_color_output(&mut self, color: ColorOutput) {
125        self.color_output = color;
126    }
127
128    /// Configure a memory limit for decoding.
129    pub fn set_memory_limit(&mut self, limit: MemoryLimit) {
130        self.memory_limit = limit;
131    }
132
133    /// Configure if frames must be within the screen descriptor.
134    ///
135    /// The default is `false`.
136    ///
137    /// When turned on, all frame descriptors being read must fit within the screen descriptor or
138    /// otherwise an error is returned and the stream left in an unspecified state.
139    ///
140    /// When turned off, frames may be arbitrarily larger or offset in relation to the screen. Many
141    /// other decoder libraries handle this in highly divergent ways. This moves all checks to the
142    /// caller, for example to emulate a specific style.
143    pub fn check_frame_consistency(&mut self, check: bool) {
144        self.check_frame_consistency = check;
145    }
146
147    /// Configure whether to skip decoding frames.
148    ///
149    /// The default is false.
150    ///
151    /// When turned on, LZW decoding is skipped. [`Decoder::read_next_frame`] will return
152    /// compressed LZW bytes in frame's data.
153    /// [`Decoder::next_frame_info`] will return the metadata of the next frame as usual.
154    /// This is useful to count frames without incurring the overhead of decoding.
155    pub fn skip_frame_decoding(&mut self, skip: bool) {
156        self.skip_frame_decoding = skip;
157    }
158
159    /// Configure if LZW encoded blocks must end with a marker end code.
160    ///
161    /// The default is `false`.
162    ///
163    /// When turned on, all image data blocks—which are LZW encoded—must contain a special bit
164    /// sequence signalling the end of the data. LZW processing terminates when this code is
165    /// encountered. The specification states that it must be the last code output by the encoder
166    /// for an image.
167    ///
168    /// When turned off then image data blocks can simply end. Note that this might silently ignore
169    /// some bits of the last or second to last byte.
170    pub fn check_lzw_end_code(&mut self, check: bool) {
171        self.check_for_end_code = check;
172    }
173
174    /// Configure if unknown blocks are allowed to be decoded.
175    ///
176    /// The default is `false`.
177    ///
178    /// When turned on, the decoder will allow unknown blocks to be in the
179    /// `BlockStart` position.
180    ///
181    /// When turned off, decoded block starts must mark an `Image`, `Extension`,
182    /// or `Trailer` block. Otherwise, the decoded image will return an error.
183    /// If an unknown block error is returned from decoding, enabling this
184    /// setting may allow for a further state of decoding on the next attempt.
185    pub fn allow_unknown_blocks(&mut self, check: bool) {
186        self.allow_unknown_blocks = check;
187    }
188
189    /// Reads the logical screen descriptor including the global color palette
190    ///
191    /// Returns a [`Decoder`]. All decoder configuration has to be done beforehand.
192    pub fn read_info<R: Read>(self, r: R) -> Result<Decoder<R>, DecodingError> {
193        Decoder::with_no_init(r, StreamingDecoder::with_options(&self), self).init()
194    }
195}
196
197struct ReadDecoder<R: Read> {
198    reader: io::BufReader<R>,
199    decoder: StreamingDecoder,
200    at_eof: bool,
201}
202
203impl<R: Read> ReadDecoder<R> {
204    #[inline(never)]
205    fn decode_next(&mut self, write_into: &mut OutputBuffer<'_>) -> Result<Option<Decoded>, DecodingError> {
206        while !self.at_eof {
207            let (consumed, result) = {
208                let buf = self.reader.fill_buf()?;
209                if buf.is_empty() {
210                    return Err(io::ErrorKind::UnexpectedEof.into());
211                }
212
213                self.decoder.update(buf, write_into)?
214            };
215            self.reader.consume(consumed);
216            match result {
217                Decoded::Nothing => (),
218                Decoded::BlockStart(Block::Trailer) => {
219                    self.at_eof = true;
220                },
221                result => return Ok(Some(result))
222            }
223        }
224        Ok(None)
225    }
226
227    fn into_inner(self) -> io::BufReader<R> {
228        self.reader
229    }
230
231    fn decode_next_bytes(&mut self, out: &mut OutputBuffer<'_>) -> Result<usize, DecodingError> {
232        match self.decode_next(out)? {
233            Some(Decoded::BytesDecoded(len)) => Ok(len.get()),
234            Some(Decoded::DataEnd) => Ok(0),
235            _ => Err(DecodingError::format("unexpected data")),
236        }
237    }
238}
239
240#[allow(dead_code)]
241/// GIF decoder. Create [`DecodeOptions`] to get started, and call [`DecodeOptions::read_info`].
242pub struct Decoder<R: Read> {
243    decoder: ReadDecoder<R>,
244    pixel_converter: PixelConverter,
245    bg_color: Option<u8>,
246    repeat: Repeat,
247    current_frame: Frame<'static>,
248    current_frame_data_type: FrameDataType,
249}
250
251impl<R> Decoder<R> where R: Read {
252    /// Create a new decoder with default options.
253    #[inline]
254    pub fn new(reader: R) -> Result<Self, DecodingError> {
255        DecodeOptions::new().read_info(reader)
256    }
257
258    /// Return a builder that allows configuring limits etc.
259    #[must_use]
260    #[inline]
261    pub fn build() -> DecodeOptions {
262        DecodeOptions::new()
263    }
264
265    fn with_no_init(reader: R, decoder: StreamingDecoder, options: DecodeOptions) -> Decoder<R> {
266        Decoder {
267            decoder: ReadDecoder {
268                reader: io::BufReader::new(reader),
269                decoder,
270                at_eof: false,
271            },
272            bg_color: None,
273            pixel_converter: PixelConverter::new(options.color_output, options.memory_limit),
274            repeat: Repeat::default(),
275            current_frame: Frame::default(),
276            current_frame_data_type: FrameDataType::Pixels,
277        }
278    }
279
280    fn init(mut self) -> Result<Self, DecodingError> {
281        loop {
282            match self.decoder.decode_next(&mut OutputBuffer::None)? {
283                Some(Decoded::BackgroundColor(bg_color)) => {
284                    self.bg_color = Some(bg_color);
285                }
286                Some(Decoded::GlobalPalette(palette)) => {
287                    self.pixel_converter.set_global_palette(palette.into());
288                },
289                Some(Decoded::Repetitions(repeat)) => {
290                    self.repeat = repeat;
291                },
292                Some(Decoded::HeaderEnd) => {
293                    break
294                },
295                Some(_) => {
296                    // There will be extra events when parsing application extension
297                    continue
298                },
299                None => return Err(DecodingError::format(
300                    "file does not contain any image data"
301                ))
302            }
303        }
304        // If the background color is invalid, ignore it
305        if let Some(palette) = self.pixel_converter.global_palette() {
306            if self.bg_color.unwrap_or(0) as usize >= (palette.len() / PLTE_CHANNELS) {
307                self.bg_color = None;
308            }
309        }
310        Ok(self)
311    }
312
313    /// Returns the next frame info
314    pub fn next_frame_info(&mut self) -> Result<Option<&Frame<'static>>, DecodingError> {
315        loop {
316            match self.decoder.decode_next(&mut OutputBuffer::None)? {
317                Some(Decoded::FrameMetadata(frame_data_type)) => {
318                    self.current_frame = self.decoder.decoder.current_frame_mut().take();
319                    self.current_frame_data_type = frame_data_type;
320                    if self.current_frame.palette.is_none() && self.global_palette().is_none() {
321                        return Err(DecodingError::format(
322                            "no color table available for current frame",
323                        ));
324                    }
325                    break;
326                }
327                Some(_) => (),
328                None => return Ok(None),
329            }
330        }
331        Ok(Some(&self.current_frame))
332    }
333
334    /// Reads the next frame from the image.
335    ///
336    /// Do not call `Self::next_frame_info` beforehand.
337    /// Deinterlaces the result.
338    ///
339    /// You can also call `.into_iter()` on the decoder to use it as a regular iterator.
340    pub fn read_next_frame(&mut self) -> Result<Option<&Frame<'static>>, DecodingError> {
341        if let Some(_) = self.next_frame_info()? {
342            match self.current_frame_data_type {
343                FrameDataType::Pixels => {
344                    self.pixel_converter.read_frame(&mut self.current_frame, &mut |out| self.decoder.decode_next_bytes(out))?;
345                },
346                FrameDataType::Lzw { min_code_size } => {
347                    let mut vec = if matches!(self.current_frame.buffer, Cow::Owned(_)) {
348                        let mut vec = mem::replace(&mut self.current_frame.buffer, Cow::Borrowed(&[])).into_owned();
349                        vec.clear();
350                        vec
351                    } else {
352                        Vec::new()
353                    };
354                    // Guesstimate 2bpp
355                    vec.try_reserve(usize::from(self.current_frame.width) * usize::from(self.current_frame.height) / 4)
356                        .map_err(|_| io::Error::from(io::ErrorKind::OutOfMemory))?;
357                    self.copy_lzw_into_buffer(min_code_size, &mut vec)?;
358                    self.current_frame.buffer = Cow::Owned(vec);
359                },
360            }
361            Ok(Some(&self.current_frame))
362        } else {
363            Ok(None)
364        }
365    }
366
367    /// This is private for iterator's use
368    fn take_current_frame(&mut self) -> Option<Frame<'static>> {
369        if self.current_frame.buffer.is_empty() {
370            return None;
371        }
372        Some(self.current_frame.take())
373    }
374
375    /// Reads the data of the current frame into a pre-allocated buffer.
376    ///
377    /// `Self::next_frame_info` needs to be called beforehand.
378    /// The length of `buf` must be at least `Self::buffer_size`.
379    /// Deinterlaces the result.
380    pub fn read_into_buffer(&mut self, buf: &mut [u8]) -> Result<(), DecodingError> {
381        self.pixel_converter.read_into_buffer(&mut self.current_frame, buf, &mut |out| self.decoder.decode_next_bytes(out))
382    }
383
384    fn copy_lzw_into_buffer(&mut self, min_code_size: u8, buf: &mut Vec<u8>) -> Result<(), DecodingError> {
385        // `write_lzw_pre_encoded_frame` smuggles `min_code_size` in the first byte.
386        buf.push(min_code_size);
387        loop {
388            match self.decoder.decode_next(&mut OutputBuffer::Vec(buf))? {
389                Some(Decoded::LzwDataCopied(_len)) => {},
390                Some(Decoded::DataEnd) => return Ok(()),
391                _ => return Err(DecodingError::format("unexpected data")),
392            }
393        }
394    }
395
396    /// Reads data of the current frame into a pre-allocated buffer until the buffer has been
397    /// filled completely.
398    ///
399    /// The buffer length must be an even number of pixels (multiple of 4 if decoding RGBA).
400    ///
401    /// `Self::next_frame_info` needs to be called beforehand. Returns `true` if the supplied
402    /// buffer could be filled completely. Should not be called after `false` had been returned.
403    pub fn fill_buffer(&mut self, buf: &mut [u8]) -> Result<bool, DecodingError> {
404        self.pixel_converter.fill_buffer(&mut self.current_frame, buf, &mut |out| self.decoder.decode_next_bytes(out))
405    }
406
407    /// Output buffer size
408    pub fn buffer_size(&self) -> usize {
409        self.pixel_converter.buffer_size(&self.current_frame).unwrap()
410    }
411
412    /// Line length of the current frame
413    pub fn line_length(&self) -> usize {
414        self.pixel_converter.line_length(&self.current_frame)
415    }
416
417    /// Returns the color palette relevant for the frame that has been decoded
418    #[inline]
419    pub fn palette(&self) -> Result<&[u8], DecodingError> {
420        Ok(match self.current_frame.palette {
421            Some(ref table) => table,
422            None => self.global_palette().ok_or(DecodingError::format(
423                "no color table available for current frame",
424            ))?,
425        })
426    }
427
428    /// The global color palette
429    pub fn global_palette(&self) -> Option<&[u8]> {
430        self.pixel_converter.global_palette()
431    }
432
433    /// Width of the image
434    #[inline]
435    pub fn width(&self) -> u16 {
436        self.decoder.decoder.width()
437    }
438
439    /// Height of the image
440    #[inline]
441    pub fn height(&self) -> u16 {
442        self.decoder.decoder.height()
443    }
444
445    /// Abort decoding and recover the `io::Read` instance
446    pub fn into_inner(self) -> io::BufReader<R> {
447        self.decoder.into_inner()
448    }
449
450    /// Index of the background color in the global palette
451    ///
452    /// In practice this is not used, and the background is
453    /// always transparent
454    pub fn bg_color(&self) -> Option<usize> {
455        self.bg_color.map(|v| v as usize)
456    }
457
458    /// Number of loop repetitions
459    #[inline]
460    pub fn repeat(&self) -> Repeat {
461        self.repeat
462    }
463}
464
465impl<R: Read> IntoIterator for Decoder<R> {
466    type Item = Result<Frame<'static>, DecodingError>;
467    type IntoIter = DecoderIter<R>;
468
469    #[inline]
470    fn into_iter(self) -> Self::IntoIter {
471        DecoderIter {
472            inner: self,
473            ended: false,
474        }
475    }
476}
477
478/// Use `decoder.into_iter()` to iterate over the frames
479pub struct DecoderIter<R: Read> {
480    inner: Decoder<R>,
481    ended: bool,
482}
483
484impl<R: Read> DecoderIter<R> {
485    /// Abort decoding and recover the `io::Read` instance
486    ///
487    /// Use `for frame in iter.by_ref()` to be able to call this afterwards.
488    pub fn into_inner(self) -> io::BufReader<R> {
489        self.inner.into_inner()
490    }
491}
492
493impl<R: Read> FusedIterator for DecoderIter<R> {}
494
495impl<R: Read> Iterator for DecoderIter<R> {
496    type Item = Result<Frame<'static>, DecodingError>;
497
498    fn next(&mut self) -> Option<Self::Item> {
499        if !self.ended {
500            match self.inner.read_next_frame() {
501                Ok(Some(_)) => self.inner.take_current_frame().map(Ok),
502                Ok(None) => {
503                    self.ended = true;
504                    None
505                },
506                Err(err) => {
507                    self.ended = true;
508                    Some(Err(err))
509                },
510            }
511        } else {
512            None
513        }
514    }
515}
gif/reader/mod.rs

gif/reader/
mod.rs
