From eea14f31d16a37857c02c5404056a657775a1949 Mon Sep 17 00:00:00 2001 From: Glenn Morris Date: Fri, 3 Feb 2012 00:44:30 -0800 Subject: [PATCH] Document animated image API * doc/lispref/display.texi (GIF Images): Mention animation. Remove commented-out old example of animation. (Animated Images): New subsection. * doc/lispref/elisp.texi (Top): * doc/lispref/vol1.texi (Top): * doc/lispref/vol2.texi (Top): Add Animated Images menu entry. * lisp/image-mode.el (image-animate-loop, image-toggle-animation): Doc fixes. * lisp/image.el (image-animated-p): Doc fix. Use image-animated-types. (image-animate-timeout): Doc fix. * etc/NEWS: Markup. --- doc/lispref/ChangeLog | 7 +++++ doc/lispref/display.texi | 58 +++++++++++++++++++++++++--------------- doc/lispref/elisp.texi | 1 + doc/lispref/vol1.texi | 1 + doc/lispref/vol2.texi | 1 + etc/NEWS | 4 +++ lisp/ChangeLog | 7 +++++ lisp/image-mode.el | 6 +++-- lisp/image.el | 23 ++++++++++------ 9 files changed, 76 insertions(+), 32 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 35e7a15ed4..45dc767321 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,5 +1,12 @@ 2012-02-03 Glenn Morris + * display.texi (GIF Images): Mention animation. + Remove commented-out old example of animation. + (Animated Images): New subsection. + * elisp.texi (Top): + * vol1.texi (Top): + * vol2.texi (Top): Add Animated Images menu entry. + * display.texi (Image Formats): Remove oddly specific information on versions of image libraries. (GIF Images, TIFF Images): Minor rephrasing. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 39c5da631c..e97e6c264a 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -4134,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}). * Other Image Types:: Various other formats are supported. * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. @end menu @@ -4472,30 +4473,10 @@ specifies the actual color to use for displaying that name. You can use @code{:index} to specify image number @var{index} from a GIF file that contains more than one image. If the GIF file doesn't contain an image with the specified index, the image displays as a -hollow box. +hollow box. GIF files with more than one image can be animated, +@pxref{Animated Images}. @end table -@ignore -This could be used to implement limited support for animated GIFs. -For example, the following function displays a multi-image GIF file -at point-min in the current buffer, switching between sub-images -every 0.1 seconds. - -(defun show-anim (file max) - "Display multi-image GIF file FILE which contains MAX subimages." - (display-anim (current-buffer) file 0 max t)) - -(defun display-anim (buffer file idx max first-time) - (when (= idx max) - (setq idx 0)) - (let ((img (create-image file nil :image idx))) - (with-current-buffer buffer - (goto-char (point-min)) - (unless first-time (delete-char 1)) - (insert-image img)) - (run-with-timer 0.1 nil 'display-anim buffer file (1+ idx) max nil))) -@end ignore - @node TIFF Images @subsection TIFF Images @cindex TIFF @@ -4855,6 +4836,39 @@ cache, it can always be displayed, even if the value of @var{max-image-size} is subsequently changed (@pxref{Image Cache}). @end defvar +@node Animated Images +@subsection Animated Images + +@cindex animation +@cindex image animation +Some image files can contain more than one image. This can be used to +create animation. Currently, Emacs only supports animated GIF files. +The following functions related to animated images are available. + +@defun image-animated-p image +This function returns non-nil if @var{image} can be animated. +The actual return value is a cons @code{(@var{nimages} . @var{delay})}, +where @var{nimages} is the number of frames and @var{delay} is the +delay in seconds between them. +@end defun + +@defun image-animate image &optional index limit +This function animates @var{image}. The optional integer @var{index} +specifies the frame from which to start (default 0). The optional +argument @var{limit} controls the length of the animation. If omitted +or @code{nil}, the image animates once only; if @code{t} it loops +forever; if a number animation stops after that many seconds. +@end defun + +@noindent Animation operates by means of a timer. Note that Emacs imposes a +minimum frame delay of 0.01 seconds. + +@defun image-animate-timer image +This function returns the timer responsible for animating @var{image}, +if there is one. +@end defun + + @node Image Cache @subsection Image Cache @cindex image cache diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 31e887ea68..b20ac1a944 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1351,6 +1351,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index 95f9f7f4d2..3a2f4723b0 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -1372,6 +1372,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index 08ea022f6a..41558549da 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -1371,6 +1371,7 @@ Images * Defining Images:: Convenient ways to define an image for later use. * Showing Images:: Convenient ways to display an image once it is defined. +* Animated Images:: Some image formats can be animated. * Image Cache:: Internal mechanisms of image display. Buttons diff --git a/etc/NEWS b/etc/NEWS index 39bc51206b..f58ffcdfa5 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1323,12 +1323,16 @@ i.e. via menu entries of the form `(menu-item "--")'. ** Image API ++++ *** Animated images support (currently animated gifs only). ++++ **** `image-animated-p' returns non-nil if an image can be animated. ++++ **** `image-animate' animates a supplied image spec. ++++ **** `image-animate-timer' returns the timer object for an image that is being animated. diff --git a/lisp/ChangeLog b/lisp/ChangeLog index 4497b398db..8a08e3d2a0 100644 --- a/lisp/ChangeLog +++ b/lisp/ChangeLog @@ -1,3 +1,10 @@ +2012-02-03 Glenn Morris + + * image.el (image-animated-p): Doc fix. Use image-animated-types. + (image-animate-timeout): Doc fix. + + * image-mode.el (image-animate-loop, image-toggle-animation): Doc fixes. + 2012-02-02 Glenn Morris * server.el (server-auth-dir): Doc fix. diff --git a/lisp/image-mode.el b/lisp/image-mode.el index 953cb9e94a..ba1fadf2c1 100644 --- a/lisp/image-mode.el +++ b/lisp/image-mode.el @@ -557,13 +557,15 @@ the image by calling `image-mode'." ;;; Animated images (defcustom image-animate-loop nil - "Whether to play animated images on a loop in Image mode." + "Non-nil means animated images loop forever, rather than playing once." :type 'boolean :version "24.1" :group 'image) (defun image-toggle-animation () - "Start or stop animating the current image." + "Start or stop animating the current image. +If `image-animate-loop' is non-nil, animation loops forever. +Otherwise it plays once, then stops." (interactive) (let ((image (image-get-display-property)) animation) diff --git a/lisp/image.el b/lisp/image.el index 15b82d12dc..24089b0c7c 100644 --- a/lisp/image.el +++ b/lisp/image.el @@ -595,13 +595,15 @@ Example: "List of supported animated image types.") (defun image-animated-p (image) - "Return non-nil if image can be animated. -Actually, the return value is a cons (NIMAGES . DELAY), where -NIMAGES is the number of sub-images in the animated image and -DELAY is the delay in second until the next sub-image shall be -displayed." + "Return non-nil if IMAGE can be animated. +To be capable of being animated, an image must be of a type +listed in `image-animated-types', and contain more than one +sub-image, with a specified animation delay. The actual return +value is a cons (NIMAGES . DELAY), where NIMAGES is the number +of sub-images in the animated image and DELAY is the delay in +seconds until the next sub-image should be displayed." (cond - ((eq (plist-get (cdr image) :type) 'gif) + ((memq (plist-get (cdr image) :type) image-animated-types) (let* ((metadata (image-metadata image)) (images (plist-get metadata 'count)) (delay (plist-get metadata 'delay))) @@ -609,6 +611,7 @@ displayed." (if (< delay 0) (setq delay 0.1)) (cons images delay)))))) +;; "Destructively"? (defun image-animate (image &optional index limit) "Start animating IMAGE. Animation occurs by destructively altering the IMAGE spec list. @@ -639,16 +642,20 @@ number, play until that number of seconds has elapsed." (setq timer nil))) timer)) +;; FIXME? The delay may not be the same for different sub-images, +;; hence we need to call image-animated-p to return it. +;; But it also returns count, so why do we bother passing that as an +;; argument? (defun image-animate-timeout (image n count time-elapsed limit) "Display animation frame N of IMAGE. N=0 refers to the initial animation frame. COUNT is the total number of frames in the animation. -DELAY is the time between animation frames, in seconds. TIME-ELAPSED is the total time that has elapsed since `image-animate-start' was called. LIMIT determines when to stop. If t, loop forever. If nil, stop after displaying the last animation frame. Otherwise, stop - after LIMIT seconds have elapsed." + after LIMIT seconds have elapsed. +The minimum delay between successive frames is 0.01s." (plist-put (cdr image) :index n) (force-window-update) (setq n (1+ n)) -- 2.20.1