Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-gif

Source of release 0.3.0

0.3.0 / src / gif / module.lucb

#==============================================================================================
#
#   gif - GIF decoding: still pictures and animations
#
#   DESCRIPTION:
#       Reads GIF87a and GIF89a: global and local palettes, LZW image data, interlacing,
#       the Graphics Control Extension (delay, disposal, transparency) and the
#       NETSCAPE2.0 / ANIMEXTS1.0 loop count; comments, plain text and other application
#       extensions are skipped. `info` reads the size, frame count and loop count;
#       `decode_rgba8` gives the first frame as 8-bit straight RGBA; an `Animation`
#       gives every frame as a whole canvas with the frames before it composited under
#       it, disposal and transparency applied, as a browser shows it.
#
#       Damaged files are handled as browsers handle them: a file that ends early keeps
#       the frames it holds (the last one drawn as far as its data goes), an invalid LZW
#       code ends its frame's pixels, bytes that are not a block end the file, the first
#       frame widens a logical screen too small for it, and frames outside the screen
#       are clipped. Decoding is bounded: no input makes it trap, loop without end or
#       allocate past `Options.max_pixels`.
#
#       Fragments, in ORDER:
#
#       module.lucb     the public API: errors, Info, Frame, Options, info, decode_rgba8
#       walk.lucb       the block walker: header, screen, extensions, image descriptors
#       lzw.lucb        the LZW decoder, bounded against bad codes
#       paint.lucb      drawing a frame's pixels onto a canvas, interlaced or not
#       animation.lucb  Animation: frames composited one after another
#
#==============================================================================================

import memory

# mark: Errors ================================================================================

## The bytes are not a GIF, or are damaged before the first image.
pub let corrupt: ErrorCode = ErrorCode.package(1)

## A limit in `Options` was reached: the canvas has more pixels than `max_pixels`.
pub let limit: ErrorCode = ErrorCode.package(2)

## The caller's request cannot be met: an output buffer too small, a frame index past
## the last frame.
pub let invalid: ErrorCode = ErrorCode.package(3)

# mark: Information ===========================================================================

## A GIF's canvas, frames and looping.
pub struct Info:
    ## The canvas: the logical screen, widened to hold the first frame where the file
    ## declares a screen too small for it (as Chrome does).
    pub var width: usize
    pub var height: usize
    ## The frames: the image descriptors whose header (and local palette) the file holds
    ## in full.
    pub var frame_count: usize
    ## How many times the animation repeats after its first play, as the NETSCAPE2.0
    ## (or ANIMEXTS1.0) extension says; 0 repeats forever, and none means the file has no
    ## such extension.
    pub var loop_count: u32?
    ## 87 or 89, from the signature.
    pub var version: u32 = 89
    ## Whether any frame has a transparent colour, or leaves part of the canvas
    ## undrawn.
    pub var alpha: bool

    ## How many times a browser plays the animation in all: 0 forever, 1 without a loop
    ## extension, else the written count and the first play.
    pub func plays() -> u32:
        if let count = self.loop_count:
            if count == 0:
                return 0
            return count + 1
        return 1

    ## Whether the GIF is an animation: more than one frame.
    pub func animated() -> bool:
        return self.frame_count > 1

## What becomes of a frame's area before the next frame is drawn.
pub enum Disposal:
    ## It stays (disposal 0, "unspecified", 1, and the undefined 5 to 7).
    keep
    ## It is cleared to transparent (2: browsers clear rather than paint the background
    ## colour).
    background
    ## It is restored to what was there before the frame was drawn (3, and 4, which
    ## some encoders write for it).
    previous

## One frame: where it is drawn, for how long, and what happens to it after.
pub struct Frame:
    ## The image's rectangle as the file gives it; the part outside the canvas is not
    ## drawn.
    pub var left: usize
    pub var top: usize
    pub var width: usize
    pub var height: usize
    ## Its rows are stored in the four interlace passes.
    pub var interlaced: bool
    ## The delay as written, in hundredths of a second.
    pub var delay: u32
    ## How long browsers show the frame, in milliseconds: the delay, or 100 where the
    ## delay is 10 ms or less (as Chrome and Firefox do).
    pub var duration: u32
    ## What becomes of its area before the next frame is drawn.
    pub var disposal: Disposal = Disposal.keep
    ## The palette index drawn as transparent, if any.
    pub var transparent: u8?
    ## Where the frame's LZW minimum code size byte is in the file; 0 when the file
    ## ends before it.
    var data: usize
    ## Where its palette is (the local one, or the global), and how many colours.
    var palette: usize
    var colors: usize

## How a decode runs.
pub struct Options:
    ## The most pixels a canvas may have. An `Animation` holds one canvas, and for
    ## frames disposed "previous" a second.
    pub var max_pixels: usize = 268435456

# mark: Decoding ==============================================================================

## The canvas size, frame count and loop count of the GIF in `data`.
pub func info(data: const u8[]) -> Info!:
    var walker = try Walker.start(data)
    while let frame = walker.next():
        _ = frame
    return walker.info

## Decode the first frame into `out`, `width * height * 4` bytes of straight RGBA; what
## the frame does not cover is transparent. Fails when the GIF has no frame.
pub func decode_rgba8(data: const u8[], out: u8[], options: Options = Options()) -> !:
    var walker = try Walker.start(data)
    let first = walker.next() else error(corrupt, "GIF has no image")
    while let frame = walker.next():
        _ = frame
    let width = walker.info.width
    let height = walker.info.height
    try check_canvas(width, height, options)
    if out.length < width * height * 4:
        error(invalid, "GIF output buffer is smaller than the picture")
    memory.set(out[..<width * height * 4], 0)
    draw(data, &first, out, width, height)

## Fail when a `width` by `height` canvas is over the limit.
func check_canvas(width: usize, height: usize, options: Options) -> !:
    if width != 0 and height > options.max_pixels // width:
        error(limit, "GIF canvas has more pixels than allowed")

## The lesser of `a` and `b`.
func least(a: usize, b: usize) -> usize:
    return a if a < b else b