animage.el -- animated image support in Emacs

[storm@cua.dk (Kim F. Storm)]

Below you will find animage.el which enables Emacs to show animated GIF
files using the following code:

(require 'animage)
(setq anim (create-animated-image "/your/animated/image.gif" 'gif nil))
(insert-image anim)

You can start and stop animation with

(image-animate-start anim)
(image-animate-stop anim)


As a pre-requisite for the animated image support, I have already
installed a few trivial changes to Emacs core.

In image.el, I have split out most of the code in `create-image' into a new
function `image-type' which other functions like `create-animated-image'
can use.

In image.c, I have fixed an ugly bug in four_corners_best, and added a
new function image-extension-data which returns a raw representation
of the extension data of a given (sub)image [when available].

For a GIF image, the extension-data contains information about
animation timing, which is interpreted by the code below.

The code is just 100+ lines, so it could be added directly to image.el,
but I have placed it in a separate file named animage.el:

;;; animage.el --- animated image API

;; Copyright (C) 2006 Free Software Foundation, Inc.

;; Maintainer: FSF
;; Keywords: multimedia

;; This file is part of GNU Emacs.

;; GNU Emacs is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 2, or (at your option)
;; any later version.

;; GNU Emacs is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;; GNU General Public License for more details.

;; You should have received a copy of the GNU General Public License
;; along with GNU Emacs; see the file COPYING.  If not, write to the
;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.

;;; Commentary:

;;; Code:

(require 'image)

(defcustom image-animate-max-time 30
  "Time in seconds to animate images."
  :type 'integer
  :version "22.1"
  :group 'image)

(defconst image-animated-types '(gif)
  "List of supported animated image types.")

;;;###autoload
(defun create-animated-image (file-or-data &optional type data-p &rest props)
  "Create an animated image.
FILE-OR-DATA is an image file name or image data.
Optional TYPE is a symbol describing the image type.  If TYPE is omitted
or nil, try to determine the image type from its first few bytes
of image data.  If that doesn't work, and FILE-OR-DATA is a file name,
use its file extension as image type.
Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data.
Optional PROPS are additional image attributes to assign to the image,
like, e.g. `:mask MASK'.
Value is the image created, or nil if images of type TYPE are not supported.

Images should not be larger than specified by `max-image-size'."
  (setq type (image-type file-or-data type data-p))
  (when (image-type-available-p type)
    (let* ((animate (memq type image-animated-types))
	   (image
	    (append (list 'image :type type (if data-p :data :file) file-or-data)
		    (if animate '(:index 0 :mask heuristic))
		    props)))
      (if animate
	  (image-animate-start image))
      image)))

(defun image-animate-timer (image)
  "Return the animation timer for image IMAGE."
  ;; See cancel-function-timers
  (let ((tail timer-list) timer)
    (while tail
      (setq timer (car tail)
	    tail (cdr tail))
      (if (and (eq (aref timer 5) #'image-animate-timeout)
	       (consp (aref timer 6))
	       (eq (car (aref timer 6)) image))
	  (setq tail nil)
	(setq timer nil)))
    timer))

(defun image-animate-start (image &optional max-time)
  "Start animation of image IMAGE.
Optional second arg MAX-TIME is number of seconds to animate image,
or t to animate infinitely."
  (let ((anim (image-animated-p image))
	timer tmo)
    (when anim
      (if (setq timer (image-animate-timer image))
	  (setcar (nthcdr 3 (aref timer 6)) max-time)
	(setq tmo (* (cdr anim) 0.01))
	(setq max-time (or max-time image-animate-max-time))
	(run-with-timer tmo nil #'image-animate-timeout
			image 1 (car anim)
			(if (numberp max-time)
			    (- max-time tmo)
			  max-time))))))

(defun image-animate-stop (image)
  "Stop animation of image."
  (let ((timer (image-animate-timer image)))
    (when timer
      (cancel-timer timer))))

(defun image-animate-timeout (image ino count time-left)
  (if (>= ino count)
      (setq ino 0))
  (plist-put (cdr image) :index ino)
  (force-window-update)
  (let ((anim (image-animated-p image)) tmo)
    (when anim
      (setq tmo (* (cdr anim) 0.01))
      (unless (and (= ino 0) (numberp time-left) (< time-left tmo))
	(run-with-timer tmo nil #'image-animate-timeout
			image (1+ ino) count
			(if (numberp time-left)
			    (- time-left tmo)
			  time-left))))))

(defun image-animated-p (image)
  "Return non-nil if image is animated.
Actually, return value is a cons (IMAGES . DELAY) where IMAGES
is the number of sub-images in the animated image, and DELAY
is the delay in 100ths of a second until the next sub-image
shall be displayed."
  (cond
   ((eq (plist-get (cdr image) :type) 'gif)
    (let* ((extdata (image-extension-data image))
	   (images (plist-get extdata 'count))
	   (anim (plist-get extdata #xF9)))
      (and (integerp images) (> images 1)
	   (stringp anim) (>= (length anim) 4)
	   (cons images (+ (aref anim 1) (* (aref anim 2) 256))))))))


(provide 'animage)

;;; animage.el ends here

--
Kim F. Storm <storm@cua.dk> http://www.cua.dk