* 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.
2012-02-03 Glenn Morris <rgm@gnu.org>
+ * 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.
* 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
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
@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
* 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
* 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
* 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
** 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.
+2012-02-03 Glenn Morris <rgm@gnu.org>
+
+ * 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 <rgm@gnu.org>
* server.el (server-auth-dir): Doc fix.
;;; 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)
"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)))
(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.
(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))
projects / emacs.git / commitdiff