// Copyright 2011 The Go Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

// Package gif implements a GIF image decoder and encoder. // // The GIF specification is at https://www.w3.org/Graphics/GIF/spec-gif89a.txt.
package gif import ( ) var ( errNotEnough = errors.New("gif: not enough image data") errTooMuch = errors.New("gif: too much image data") errBadPixel = errors.New("gif: invalid pixel value") ) // If the io.Reader does not also have ReadByte, then decode will introduce its own buffering. type reader interface { io.Reader io.ByteReader } // Masks etc. const ( // Fields. fColorTable = 1 << 7 fInterlace = 1 << 6 fColorTableBitsMask = 7 // Graphic control flags. gcTransparentColorSet = 1 << 0 gcDisposalMethodMask = 7 << 2 ) // Disposal Methods. const ( DisposalNone = 0x01 DisposalBackground = 0x02 DisposalPrevious = 0x03 ) // Section indicators. const ( sExtension = 0x21 sImageDescriptor = 0x2C sTrailer = 0x3B ) // Extensions. const ( eText = 0x01 // Plain Text eGraphicControl = 0xF9 // Graphic Control eComment = 0xFE // Comment eApplication = 0xFF // Application ) func readFull( io.Reader, []byte) error { , := io.ReadFull(, ) if == io.EOF { = io.ErrUnexpectedEOF } return } func readByte( io.ByteReader) (byte, error) { , := .ReadByte() if == io.EOF { = io.ErrUnexpectedEOF } return , } // decoder is the type used to decode a GIF file. type decoder struct { r reader // From header. vers string width int height int loopCount int delayTime int backgroundIndex byte disposalMethod byte // From image descriptor. imageFields byte // From graphics control. transparentIndex byte hasTransparentIndex bool // Computed. globalColorTable color.Palette // Used when decoding. delay []int disposal []byte image []*image.Paletted tmp [1024]byte // must be at least 768 so we can read color table } // blockReader parses the block structure of GIF image data, which comprises // (n, (n bytes)) blocks, with 1 <= n <= 255. It is the reader given to the // LZW decoder, which is thus immune to the blocking. After the LZW decoder // completes, there will be a 0-byte block remaining (0, ()), which is // consumed when checking that the blockReader is exhausted. // // To avoid the allocation of a bufio.Reader for the lzw Reader, blockReader // implements io.ReadByte and buffers blocks into the decoder's "tmp" buffer. type blockReader struct { d *decoder i, j uint8 // d.tmp[i:j] contains the buffered bytes err error } func ( *blockReader) () { if .err != nil { return } .j, .err = readByte(.d.r) if .j == 0 && .err == nil { .err = io.EOF } if .err != nil { return } .i = 0 .err = readFull(.d.r, .d.tmp[:.j]) if .err != nil { .j = 0 } } func ( *blockReader) () (byte, error) { if .i == .j { .fill() if .err != nil { return 0, .err } } := .d.tmp[.i] .i++ return , nil } // blockReader must implement io.Reader, but its Read shouldn't ever actually // be called in practice. The compress/lzw package will only call ReadByte. func ( *blockReader) ( []byte) (int, error) { if len() == 0 || .err != nil { return 0, .err } if .i == .j { .fill() if .err != nil { return 0, .err } } := copy(, .d.tmp[.i:.j]) .i += uint8() return , nil } // close primarily detects whether or not a block terminator was encountered // after reading a sequence of data sub-blocks. It allows at most one trailing // sub-block worth of data. I.e., if some number of bytes exist in one sub-block // following the end of LZW data, the very next sub-block must be the block // terminator. If the very end of LZW data happened to fill one sub-block, at // most one more sub-block of length 1 may exist before the block-terminator. // These accommodations allow us to support GIFs created by less strict encoders. // See https://golang.org/issue/16146. func ( *blockReader) () error { if .err == io.EOF { // A clean block-sequence terminator was encountered while reading. return nil } else if .err != nil { // Some other error was encountered while reading. return .err } if .i == .j { // We reached the end of a sub block reading LZW data. We'll allow at // most one more sub block of data with a length of 1 byte. .fill() if .err == io.EOF { return nil } else if .err != nil { return .err } else if .j > 1 { return errTooMuch } } // Part of a sub-block remains buffered. We expect that the next attempt to // buffer a sub-block will reach the block terminator. .fill() if .err == io.EOF { return nil } else if .err != nil { return .err } return errTooMuch } // decode reads a GIF image from r and stores the result in d. func ( *decoder) ( io.Reader, , bool) error { // Add buffering if r does not provide ReadByte. if , := .(reader); { .r = } else { .r = bufio.NewReader() } .loopCount = -1 := .readHeaderAndScreenDescriptor() if != nil { return } if { return nil } for { , := readByte(.r) if != nil { return fmt.Errorf("gif: reading frames: %v", ) } switch { case sExtension: if = .readExtension(); != nil { return } case sImageDescriptor: if = .readImageDescriptor(); != nil { return } case sTrailer: if len(.image) == 0 { return fmt.Errorf("gif: missing image data") } return nil default: return fmt.Errorf("gif: unknown block type: 0x%.2x", ) } } } func ( *decoder) () error { := readFull(.r, .tmp[:13]) if != nil { return fmt.Errorf("gif: reading header: %v", ) } .vers = string(.tmp[:6]) if .vers != "GIF87a" && .vers != "GIF89a" { return fmt.Errorf("gif: can't recognize format %q", .vers) } .width = int(.tmp[6]) + int(.tmp[7])<<8 .height = int(.tmp[8]) + int(.tmp[9])<<8 if := .tmp[10]; &fColorTable != 0 { .backgroundIndex = .tmp[11] // readColorTable overwrites the contents of d.tmp, but that's OK. if .globalColorTable, = .readColorTable(); != nil { return } } // d.tmp[12] is the Pixel Aspect Ratio, which is ignored. return nil } func ( *decoder) ( byte) (color.Palette, error) { := 1 << (1 + uint(&fColorTableBitsMask)) := readFull(.r, .tmp[:3*]) if != nil { return nil, fmt.Errorf("gif: reading color table: %s", ) } , := 0, make(color.Palette, ) for := range { [] = color.RGBA{.tmp[+0], .tmp[+1], .tmp[+2], 0xFF} += 3 } return , nil } func ( *decoder) () error { , := readByte(.r) if != nil { return fmt.Errorf("gif: reading extension: %v", ) } := 0 switch { case eText: = 13 case eGraphicControl: return .readGraphicControl() case eComment: // nothing to do but read the data. case eApplication: , := readByte(.r) if != nil { return fmt.Errorf("gif: reading extension: %v", ) } // The spec requires size be 11, but Adobe sometimes uses 10. = int() default: return fmt.Errorf("gif: unknown extension 0x%.2x", ) } if > 0 { if := readFull(.r, .tmp[:]); != nil { return fmt.Errorf("gif: reading extension: %v", ) } } // Application Extension with "NETSCAPE2.0" as string and 1 in data means // this extension defines a loop count. if == eApplication && string(.tmp[:]) == "NETSCAPE2.0" { , := .readBlock() if != nil { return fmt.Errorf("gif: reading extension: %v", ) } if == 0 { return nil } if == 3 && .tmp[0] == 1 { .loopCount = int(.tmp[1]) | int(.tmp[2])<<8 } } for { , := .readBlock() if != nil { return fmt.Errorf("gif: reading extension: %v", ) } if == 0 { return nil } } } func ( *decoder) () error { if := readFull(.r, .tmp[:6]); != nil { return fmt.Errorf("gif: can't read graphic control: %s", ) } if .tmp[0] != 4 { return fmt.Errorf("gif: invalid graphic control extension block size: %d", .tmp[0]) } := .tmp[1] .disposalMethod = ( & gcDisposalMethodMask) >> 2 .delayTime = int(.tmp[2]) | int(.tmp[3])<<8 if &gcTransparentColorSet != 0 { .transparentIndex = .tmp[4] .hasTransparentIndex = true } if .tmp[5] != 0 { return fmt.Errorf("gif: invalid graphic control extension block terminator: %d", .tmp[5]) } return nil } func ( *decoder) ( bool) error { , := .newImageFromDescriptor() if != nil { return } := .imageFields&fColorTable != 0 if { .Palette, = .readColorTable(.imageFields) if != nil { return } } else { if .globalColorTable == nil { return errors.New("gif: no color table") } .Palette = .globalColorTable } if .hasTransparentIndex { if ! { // Clone the global color table. .Palette = append(color.Palette(nil), .globalColorTable...) } if := int(.transparentIndex); < len(.Palette) { .Palette[] = color.RGBA{} } else { // The transparentIndex is out of range, which is an error // according to the spec, but Firefox and Google Chrome // seem OK with this, so we enlarge the palette with // transparent colors. See golang.org/issue/15059. := make(color.Palette, +1) copy(, .Palette) for := len(.Palette); < len(); ++ { [] = color.RGBA{} } .Palette = } } , := readByte(.r) if != nil { return fmt.Errorf("gif: reading image data: %v", ) } if < 2 || > 8 { return fmt.Errorf("gif: pixel size in decode out of range: %d", ) } // A wonderfully Go-like piece of magic. := &blockReader{d: } := lzw.NewReader(, lzw.LSB, int()) defer .Close() if = readFull(, .Pix); != nil { if != io.ErrUnexpectedEOF { return fmt.Errorf("gif: reading image data: %v", ) } return errNotEnough } // In theory, both lzwr and br should be exhausted. Reading from them // should yield (0, io.EOF). // // The spec (Appendix F - Compression), says that "An End of // Information code... must be the last code output by the encoder // for an image". In practice, though, giflib (a widely used C // library) does not enforce this, so we also accept lzwr returning // io.ErrUnexpectedEOF (meaning that the encoded stream hit io.EOF // before the LZW decoder saw an explicit end code), provided that // the io.ReadFull call above successfully read len(m.Pix) bytes. // See https://golang.org/issue/9856 for an example GIF. if , := .Read(.tmp[256:257]); != 0 || ( != io.EOF && != io.ErrUnexpectedEOF) { if != nil { return fmt.Errorf("gif: reading image data: %v", ) } return errTooMuch } // In practice, some GIFs have an extra byte in the data sub-block // stream, which we ignore. See https://golang.org/issue/16146. if := .close(); == errTooMuch { return errTooMuch } else if != nil { return fmt.Errorf("gif: reading image data: %v", ) } // Check that the color indexes are inside the palette. if len(.Palette) < 256 { for , := range .Pix { if int() >= len(.Palette) { return errBadPixel } } } // Undo the interlacing if necessary. if .imageFields&fInterlace != 0 { uninterlace() } if || len(.image) == 0 { .image = append(.image, ) .delay = append(.delay, .delayTime) .disposal = append(.disposal, .disposalMethod) } // The GIF89a spec, Section 23 (Graphic Control Extension) says: // "The scope of this extension is the first graphic rendering block // to follow." We therefore reset the GCE fields to zero. .delayTime = 0 .hasTransparentIndex = false return nil } func ( *decoder) () (*image.Paletted, error) { if := readFull(.r, .tmp[:9]); != nil { return nil, fmt.Errorf("gif: can't read image descriptor: %s", ) } := int(.tmp[0]) + int(.tmp[1])<<8 := int(.tmp[2]) + int(.tmp[3])<<8 := int(.tmp[4]) + int(.tmp[5])<<8 := int(.tmp[6]) + int(.tmp[7])<<8 .imageFields = .tmp[8] // The GIF89a spec, Section 20 (Image Descriptor) says: "Each image must // fit within the boundaries of the Logical Screen, as defined in the // Logical Screen Descriptor." // // This is conceptually similar to testing // frameBounds := image.Rect(left, top, left+width, top+height) // imageBounds := image.Rect(0, 0, d.width, d.height) // if !frameBounds.In(imageBounds) { etc } // but the semantics of the Go image.Rectangle type is that r.In(s) is true // whenever r is an empty rectangle, even if r.Min.X > s.Max.X. Here, we // want something stricter. // // Note that, by construction, left >= 0 && top >= 0, so we only have to // explicitly compare frameBounds.Max (left+width, top+height) against // imageBounds.Max (d.width, d.height) and not frameBounds.Min (left, top) // against imageBounds.Min (0, 0). if + > .width || + > .height { return nil, errors.New("gif: frame bounds larger than image bounds") } return image.NewPaletted(image.Rectangle{ Min: image.Point{, }, Max: image.Point{ + , + }, }, nil), nil } func ( *decoder) () (int, error) { , := readByte(.r) if == 0 || != nil { return 0, } if := readFull(.r, .tmp[:]); != nil { return 0, } return int(), nil } // interlaceScan defines the ordering for a pass of the interlace algorithm. type interlaceScan struct { skip, start int } // interlacing represents the set of scans in an interlaced GIF image. var interlacing = []interlaceScan{ {8, 0}, // Group 1 : Every 8th. row, starting with row 0. {8, 4}, // Group 2 : Every 8th. row, starting with row 4. {4, 2}, // Group 3 : Every 4th. row, starting with row 2. {2, 1}, // Group 4 : Every 2nd. row, starting with row 1. } // uninterlace rearranges the pixels in m to account for interlaced input. func uninterlace( *image.Paletted) { var []uint8 := .Bounds().Dx() := .Bounds().Dy() = make([]uint8, *) := 0 // steps through the input by sequential scan lines. for , := range interlacing { := .start * // steps through the output as defined by pass. for := .start; < ; += .skip { copy([:+], .Pix[:+]) += += * .skip } } .Pix = } // Decode reads a GIF image from r and returns the first embedded // image as an image.Image. func ( io.Reader) (image.Image, error) { var decoder if := .decode(, false, false); != nil { return nil, } return .image[0], nil } // GIF represents the possibly multiple images stored in a GIF file. type GIF struct { Image []*image.Paletted // The successive images. Delay []int // The successive delay times, one per frame, in 100ths of a second. // LoopCount controls the number of times an animation will be // restarted during display. // A LoopCount of 0 means to loop forever. // A LoopCount of -1 means to show each frame only once. // Otherwise, the animation is looped LoopCount+1 times. LoopCount int // Disposal is the successive disposal methods, one per frame. For // backwards compatibility, a nil Disposal is valid to pass to EncodeAll, // and implies that each frame's disposal method is 0 (no disposal // specified). Disposal []byte // Config is the global color table (palette), width and height. A nil or // empty-color.Palette Config.ColorModel means that each frame has its own // color table and there is no global color table. Each frame's bounds must // be within the rectangle defined by the two points (0, 0) and // (Config.Width, Config.Height). // // For backwards compatibility, a zero-valued Config is valid to pass to // EncodeAll, and implies that the overall GIF's width and height equals // the first frame's bounds' Rectangle.Max point. Config image.Config // BackgroundIndex is the background index in the global color table, for // use with the DisposalBackground disposal method. BackgroundIndex byte } // DecodeAll reads a GIF image from r and returns the sequential frames // and timing information. func ( io.Reader) (*GIF, error) { var decoder if := .decode(, false, true); != nil { return nil, } := &GIF{ Image: .image, LoopCount: .loopCount, Delay: .delay, Disposal: .disposal, Config: image.Config{ ColorModel: .globalColorTable, Width: .width, Height: .height, }, BackgroundIndex: .backgroundIndex, } return , nil } // DecodeConfig returns the global color model and dimensions of a GIF image // without decoding the entire image. func ( io.Reader) (image.Config, error) { var decoder if := .decode(, true, false); != nil { return image.Config{}, } return image.Config{ ColorModel: .globalColorTable, Width: .width, Height: .height, }, nil } func init() { image.RegisterFormat("gif", "GIF8?a", Decode, DecodeConfig) }