Commit eea14f31 authored by Glenn Morris's avatar Glenn Morris

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.
parent 204e728d
2012-02-03 Glenn Morris <rgm@gnu.org> 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 * display.texi (Image Formats): Remove oddly specific information
on versions of image libraries. on versions of image libraries.
(GIF Images, TIFF Images): Minor rephrasing. (GIF Images, TIFF Images): Minor rephrasing.
......
...@@ -4134,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}). ...@@ -4134,6 +4134,7 @@ displayed (@pxref{Display Feature Testing}).
* Other Image Types:: Various other formats are supported. * Other Image Types:: Various other formats are supported.
* Defining Images:: Convenient ways to define an image for later use. * Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once it is defined. * 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. * Image Cache:: Internal mechanisms of image display.
@end menu @end menu
...@@ -4472,30 +4473,10 @@ specifies the actual color to use for displaying that name. ...@@ -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 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 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 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 @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 @node TIFF Images
@subsection TIFF Images @subsection TIFF Images
@cindex TIFF @cindex TIFF
...@@ -4855,6 +4836,39 @@ cache, it can always be displayed, even if the value of ...@@ -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}). @var{max-image-size} is subsequently changed (@pxref{Image Cache}).
@end defvar @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 @node Image Cache
@subsection Image Cache @subsection Image Cache
@cindex image cache @cindex image cache
......
...@@ -1351,6 +1351,7 @@ Images ...@@ -1351,6 +1351,7 @@ Images
* Defining Images:: Convenient ways to define an image for later use. * Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once * Showing Images:: Convenient ways to display an image once
it is defined. it is defined.
* Animated Images:: Some image formats can be animated.
* Image Cache:: Internal mechanisms of image display. * Image Cache:: Internal mechanisms of image display.
Buttons Buttons
......
...@@ -1372,6 +1372,7 @@ Images ...@@ -1372,6 +1372,7 @@ Images
* Defining Images:: Convenient ways to define an image for later use. * Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once * Showing Images:: Convenient ways to display an image once
it is defined. it is defined.
* Animated Images:: Some image formats can be animated.
* Image Cache:: Internal mechanisms of image display. * Image Cache:: Internal mechanisms of image display.
Buttons Buttons
......
...@@ -1371,6 +1371,7 @@ Images ...@@ -1371,6 +1371,7 @@ Images
* Defining Images:: Convenient ways to define an image for later use. * Defining Images:: Convenient ways to define an image for later use.
* Showing Images:: Convenient ways to display an image once * Showing Images:: Convenient ways to display an image once
it is defined. it is defined.
* Animated Images:: Some image formats can be animated.
* Image Cache:: Internal mechanisms of image display. * Image Cache:: Internal mechanisms of image display.
Buttons Buttons
......
...@@ -1323,12 +1323,16 @@ i.e. via menu entries of the form `(menu-item "--")'. ...@@ -1323,12 +1323,16 @@ i.e. via menu entries of the form `(menu-item "--")'.
** Image API ** Image API
+++
*** Animated images support (currently animated gifs only). *** Animated images support (currently animated gifs only).
+++
**** `image-animated-p' returns non-nil if an image can be animated. **** `image-animated-p' returns non-nil if an image can be animated.
+++
**** `image-animate' animates a supplied image spec. **** `image-animate' animates a supplied image spec.
+++
**** `image-animate-timer' returns the timer object for an image that **** `image-animate-timer' returns the timer object for an image that
is being animated. 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> 2012-02-02 Glenn Morris <rgm@gnu.org>
* server.el (server-auth-dir): Doc fix. * server.el (server-auth-dir): Doc fix.
......
...@@ -557,13 +557,15 @@ the image by calling `image-mode'." ...@@ -557,13 +557,15 @@ the image by calling `image-mode'."
;;; Animated images ;;; Animated images
(defcustom image-animate-loop nil (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 :type 'boolean
:version "24.1" :version "24.1"
:group 'image) :group 'image)
(defun image-toggle-animation () (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) (interactive)
(let ((image (image-get-display-property)) (let ((image (image-get-display-property))
animation) animation)
......
...@@ -595,13 +595,15 @@ Example: ...@@ -595,13 +595,15 @@ Example:
"List of supported animated image types.") "List of supported animated image types.")
(defun image-animated-p (image) (defun image-animated-p (image)
"Return non-nil if image can be animated. "Return non-nil if IMAGE can be animated.
Actually, the return value is a cons (NIMAGES . DELAY), where To be capable of being animated, an image must be of a type
NIMAGES is the number of sub-images in the animated image and listed in `image-animated-types', and contain more than one
DELAY is the delay in second until the next sub-image shall be sub-image, with a specified animation delay. The actual return
displayed." 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 (cond
((eq (plist-get (cdr image) :type) 'gif) ((memq (plist-get (cdr image) :type) image-animated-types)
(let* ((metadata (image-metadata image)) (let* ((metadata (image-metadata image))
(images (plist-get metadata 'count)) (images (plist-get metadata 'count))
(delay (plist-get metadata 'delay))) (delay (plist-get metadata 'delay)))
...@@ -609,6 +611,7 @@ displayed." ...@@ -609,6 +611,7 @@ displayed."
(if (< delay 0) (setq delay 0.1)) (if (< delay 0) (setq delay 0.1))
(cons images delay)))))) (cons images delay))))))
;; "Destructively"?
(defun image-animate (image &optional index limit) (defun image-animate (image &optional index limit)
"Start animating IMAGE. "Start animating IMAGE.
Animation occurs by destructively altering the IMAGE spec list. Animation occurs by destructively altering the IMAGE spec list.
...@@ -639,16 +642,20 @@ number, play until that number of seconds has elapsed." ...@@ -639,16 +642,20 @@ number, play until that number of seconds has elapsed."
(setq timer nil))) (setq timer nil)))
timer)) 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) (defun image-animate-timeout (image n count time-elapsed limit)
"Display animation frame N of IMAGE. "Display animation frame N of IMAGE.
N=0 refers to the initial animation frame. N=0 refers to the initial animation frame.
COUNT is the total number of frames in the animation. 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 TIME-ELAPSED is the total time that has elapsed since
`image-animate-start' was called. `image-animate-start' was called.
LIMIT determines when to stop. If t, loop forever. If nil, stop LIMIT determines when to stop. If t, loop forever. If nil, stop
after displaying the last animation frame. Otherwise, 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) (plist-put (cdr image) :index n)
(force-window-update) (force-window-update)
(setq n (1+ n)) (setq n (1+ n))
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment