lisp/image.el

   1 ;;; image.el --- image API
   2
   3 ;; Copyright (C) 1998, 99, 2000, 01, 04 Free Software Foundation, Inc.
   4
   5 ;; Maintainer: FSF
   6 ;; Keywords: multimedia
   7
   8 ;; This file is part of GNU Emacs.
   9
  10 ;; GNU Emacs is free software; you can redistribute it and/or modify
  11 ;; it under the terms of the GNU General Public License as published by
  12 ;; the Free Software Foundation; either version 2, or (at your option)
  13 ;; any later version.
  14
  15 ;; GNU Emacs is distributed in the hope that it will be useful,
  16 ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  17 ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18 ;; GNU General Public License for more details.
  19
  20 ;; You should have received a copy of the GNU General Public License
  21 ;; along with GNU Emacs; see the file COPYING.  If not, write to the
  22 ;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  23 ;; Boston, MA 02111-1307, USA.
  24
  25 ;;; Commentary:
  26
  27 ;;; Code:
  28
  29
  30 (defgroup image ()
  31   "Image support."
  32   :group 'multimedia)
  33
  34
  35 (defconst image-type-regexps
  36   '(("\\`/[\t\n\r ]*\\*.*XPM.\\*/" . xpm)
  37     ("\\`P[1-6]" . pbm)
  38     ("\\`GIF8" . gif)
  39     ("\\`\211PNG\r\n" . png)
  40     ("\\`[\t\n\r ]*#define" . xbm)
  41     ("\\`\\(MM\0\\*\\|II\\*\0\\)" . tiff)
  42     ("\\`[\t\n\r ]*%!PS" . postscript)
  43     ("\\`\xff\xd8" . (image-jpeg-p . jpeg)))
  44   "Alist of (REGEXP . IMAGE-TYPE) pairs used to auto-detect image types.
  45 When the first bytes of an image file match REGEXP, it is assumed to
  46 be of image type IMAGE-TYPE if IMAGE-TYPE is a symbol.  If not a symbol,
  47 IMAGE-TYPE must be a pair (PREDICATE . TYPE).  PREDICATE is called
  48 with one argument, a string containing the image data.  If PREDICATE returns
  49 a non-nil value, TYPE is the image's type.")
  50
  51 ;;;###autoload
  52 (defvar image-library-alist nil
  53   "Alist of image types vs external libraries needed to display them.
  54
  55 Each element is a list (IMAGE-TYPE LIBRARY...), where the car is a symbol
  56 representing a supported image type, and the rest are strings giving
  57 alternate filenames for the corresponding external libraries.
  58
  59 Emacs tries to load the libraries in the order they appear on the
  60 list; if none is loaded, the running session of Emacs won't
  61 support the image type.  Types 'pbm and 'xbm don't need to be
  62 listed; they're always supported.")
  63 ;;;###autoload (put 'image-library-alist 'risky-local-variable t)
  64
  65 (defun image-jpeg-p (data)
  66   "Value is non-nil if DATA, a string, consists of JFIF image data.
  67 We accept the tag Exif because that is the same format."
  68   (when (string-match "\\`\xff\xd8" data)
  69     (catch 'jfif
  70       (let ((len (length data)) (i 2))
  71         (while (< i len)
  72           (when (/= (aref data i) #xff)
  73             (throw 'jfif nil))
  74           (setq i (1+ i))
  75           (when (>= (+ i 2) len)
  76             (throw 'jfif nil))
  77           (let ((nbytes (+ (lsh (aref data (+ i 1)) 8)
  78                            (aref data (+ i 2))))
  79                 (code (aref data i)))
  80             (when (and (>= code #xe0) (<= code #xef))
  81               ;; APP0 LEN1 LEN2 "JFIF\0"
  82               (throw 'jfif
  83                      (string-match "JFIF\\|Exif"
  84                                    (substring data i (min (+ i nbytes) len)))))
  85             (setq i (+ i 1 nbytes))))))))
  86
  87
  88 ;;;###autoload
  89 (defun image-type-from-data (data)
  90   "Determine the image type from image data DATA.
  91 Value is a symbol specifying the image type or nil if type cannot
  92 be determined."
  93   (let ((types image-type-regexps)
  94         type)
  95     (while (and types (null type))
  96       (let ((regexp (car (car types)))
  97             (image-type (cdr (car types))))
  98         (when (or (and (symbolp image-type)
  99                        (string-match regexp data))
 100                   (and (consp image-type)
 101                        (funcall (car image-type) data)
 102                        (setq image-type (cdr image-type))))
 103           (setq type image-type))
 104         (setq types (cdr types))))
 105     type))
 106
 107
 108 ;;;###autoload
 109 (defun image-type-from-file-header (file)
 110   "Determine the type of image file FILE from its first few bytes.
 111 Value is a symbol specifying the image type, or nil if type cannot
 112 be determined."
 113   (unless (file-name-directory file)
 114     (setq file (expand-file-name file data-directory)))
 115   (setq file (expand-file-name file))
 116   (let ((header (with-temp-buffer
 117                   (set-buffer-multibyte nil)
 118                   (insert-file-contents-literally file nil 0 256)
 119                   (buffer-string))))
 120     (image-type-from-data header)))
 121
 122
 123 ;;;###autoload
 124 (defun image-type-available-p (type)
 125   "Value is non-nil if image type TYPE is available.
 126 Image types are symbols like `xbm' or `jpeg'."
 127   (and (fboundp 'init-image-library)
 128        (init-image-library type image-library-alist)))
 129
 130 ;;;###autoload
 131 (defun create-image (file-or-data &optional type data-p &rest props)
 132   "Create an image.
 133 FILE-OR-DATA is an image file name or image data.
 134 Optional TYPE is a symbol describing the image type.  If TYPE is omitted
 135 or nil, try to determine the image type from its first few bytes
 136 of image data.  If that doesn't work, and FILE-OR-DATA is a file name,
 137 use its file extension as image type.
 138 Optional DATA-P non-nil means FILE-OR-DATA is a string containing image data.
 139 Optional PROPS are additional image attributes to assign to the image,
 140 like, e.g. `:mask MASK'.
 141 Value is the image created, or nil if images of type TYPE are not supported."
 142   (when (and (not data-p) (not (stringp file-or-data)))
 143     (error "Invalid image file name `%s'" file-or-data))
 144   (cond ((null data-p)
 145          ;; FILE-OR-DATA is a file name.
 146          (unless (or type
 147                      (setq type (image-type-from-file-header file-or-data)))
 148            (let ((extension (file-name-extension file-or-data)))
 149              (unless extension
 150                (error "Cannot determine image type"))
 151              (setq type (intern extension)))))
 152         (t
 153          ;; FILE-OR-DATA contains image data.
 154          (unless type
 155            (setq type (image-type-from-data file-or-data)))))
 156   (unless type
 157     (error "Cannot determine image type"))
 158   (unless (symbolp type)
 159     (error "Invalid image type `%s'" type))
 160   (when (image-type-available-p type)
 161     (append (list 'image :type type (if data-p :data :file) file-or-data)
 162             props)))
 163
 164
 165 ;;;###autoload
 166 (defun put-image (image pos &optional string area)
 167   "Put image IMAGE in front of POS in the current buffer.
 168 IMAGE must be an image created with `create-image' or `defimage'.
 169 IMAGE is displayed by putting an overlay into the current buffer with a
 170 `before-string' STRING that has a `display' property whose value is the
 171 image.  STRING is defaulted if you omit it.
 172 POS may be an integer or marker.
 173 AREA is where to display the image.  AREA nil or omitted means
 174 display it in the text area, a value of `left-margin' means
 175 display it in the left marginal area, a value of `right-margin'
 176 means display it in the right marginal area."
 177   (unless string (setq string "x"))
 178   (let ((buffer (current-buffer)))
 179     (unless (eq (car-safe image) 'image)
 180       (error "Not an image: %s" image))
 181     (unless (or (null area) (memq area '(left-margin right-margin)))
 182       (error "Invalid area %s" area))
 183     (setq string (copy-sequence string))
 184     (let ((overlay (make-overlay pos pos buffer))
 185           (prop (if (null area) image (list (list 'margin area) image))))
 186       (put-text-property 0 (length string) 'display prop string)
 187       (overlay-put overlay 'put-image t)
 188       (overlay-put overlay 'before-string string))))
 189
 190
 191 ;;;###autoload
 192 (defun insert-image (image &optional string area slice)
 193   "Insert IMAGE into current buffer at point.
 194 IMAGE is displayed by inserting STRING into the current buffer
 195 with a `display' property whose value is the image.  STRING is
 196 defaulted if you omit it.
 197 AREA is where to display the image.  AREA nil or omitted means
 198 display it in the text area, a value of `left-margin' means
 199 display it in the left marginal area, a value of `right-margin'
 200 means display it in the right marginal area.
 201 SLICE specifies slice of IMAGE to insert.  SLICE nil or omitted
 202 means insert whole image.  SLICE is a list (X Y WIDTH HEIGHT)
 203 specifying the X and Y positions and WIDTH and HEIGHT of image area
 204 to insert.  A float value 0.0 - 1.0 means relative to the width or
 205 height of the image; integer values are taken as pixel values."
 206   ;; Use a space as least likely to cause trouble when it's a hidden
 207   ;; character in the buffer.
 208   (unless string (setq string " "))
 209   (unless (eq (car-safe image) 'image)
 210     (error "Not an image: %s" image))
 211   (unless (or (null area) (memq area '(left-margin right-margin)))
 212     (error "Invalid area %s" area))
 213   (if area
 214       (setq image (list (list 'margin area) image))
 215     ;; Cons up a new spec equal but not eq to `image' so that
 216     ;; inserting it twice in a row (adjacently) displays two copies of
 217     ;; the image.  Don't try to avoid this by looking at the display
 218     ;; properties on either side so that we DTRT more often with
 219     ;; cut-and-paste.  (Yanking killed image text next to another copy
 220     ;; of it loses anyway.)
 221     (setq image (cons 'image (cdr image))))
 222   (let ((start (point)))
 223     (insert string)
 224     (add-text-properties start (point)
 225                          `(display ,(if slice
 226                                         (list (cons 'slice slice) image)
 227                                       image) rear-nonsticky (display)))))
 228
 229
 230 (defun insert-sliced-image (image &optional string area rows cols)
 231   "Insert IMAGE into current buffer at point.
 232 IMAGE is displayed by inserting STRING into the current buffer
 233 with a `display' property whose value is the image.  STRING is
 234 defaulted if you omit it.
 235 AREA is where to display the image.  AREA nil or omitted means
 236 display it in the text area, a value of `left-margin' means
 237 display it in the left marginal area, a value of `right-margin'
 238 means display it in the right marginal area.
 239 The image is automatically split into ROW x COLS slices."
 240   (unless string (setq string " "))
 241   (unless (eq (car-safe image) 'image)
 242     (error "Not an image: %s" image))
 243   (unless (or (null area) (memq area '(left-margin right-margin)))
 244     (error "Invalid area %s" area))
 245   (if area
 246       (setq image (list (list 'margin area) image))
 247     ;; Cons up a new spec equal but not eq to `image' so that
 248     ;; inserting it twice in a row (adjacently) displays two copies of
 249     ;; the image.  Don't try to avoid this by looking at the display
 250     ;; properties on either side so that we DTRT more often with
 251     ;; cut-and-paste.  (Yanking killed image text next to another copy
 252     ;; of it loses anyway.)
 253     (setq image (cons 'image (cdr image))))
 254   (let ((x 0.0) (dx (/ 1.0001 (or cols 1)))
 255          (y 0.0) (dy (/ 1.0001 (or rows 1))))
 256     (while (< y 1.0)
 257       (while (< x 1.0)
 258         (let ((start (point)))
 259           (insert string)
 260           (add-text-properties start (point)
 261                                `(display ,(list (list 'slice x y dx dy) image)
 262                                          rear-nonsticky (display)))
 263           (setq x (+ x dx))))
 264       (setq x 0.0
 265             y (+ y dy))
 266       (insert (propertize "\n" 'line-height t)))))
 267
 268
 269
 270 ;;;###autoload
 271 (defun remove-images (start end &optional buffer)
 272   "Remove images between START and END in BUFFER.
 273 Remove only images that were put in BUFFER with calls to `put-image'.
 274 BUFFER nil or omitted means use the current buffer."
 275   (unless buffer
 276     (setq buffer (current-buffer)))
 277   (let ((overlays (overlays-in start end)))
 278     (while overlays
 279       (let ((overlay (car overlays)))
 280         (when (overlay-get overlay 'put-image)
 281           (delete-overlay overlay)))
 282       (setq overlays (cdr overlays)))))
 283
 284
 285 ;;;###autoload
 286 (defun find-image (specs)
 287   "Find an image, choosing one of a list of image specifications.
 288
 289 SPECS is a list of image specifications.
 290
 291 Each image specification in SPECS is a property list.  The contents of
 292 a specification are image type dependent.  All specifications must at
 293 least contain the properties `:type TYPE' and either `:file FILE' or
 294 `:data DATA', where TYPE is a symbol specifying the image type,
 295 e.g. `xbm', FILE is the file to load the image from, and DATA is a
 296 string containing the actual image data.  The specification whose TYPE
 297 is supported, and FILE exists, is used to construct the image
 298 specification to be returned.  Return nil if no specification is
 299 satisfied.
 300
 301 The image is looked for first on `load-path' and then in `data-directory'."
 302   (let (image)
 303     (while (and specs (null image))
 304       (let* ((spec (car specs))
 305              (type (plist-get spec :type))
 306              (data (plist-get spec :data))
 307              (file (plist-get spec :file))
 308              found)
 309         (when (image-type-available-p type)
 310           (cond ((stringp file)
 311                  (let ((path load-path))
 312                    (while (and (not found) path)
 313                      (let ((try-file (expand-file-name file (car path))))
 314                        (when (file-readable-p try-file)
 315                          (setq found try-file)))
 316                      (setq path (cdr path)))
 317                    (unless found
 318                      (let ((try-file (expand-file-name file data-directory)))
 319                        (if (file-readable-p try-file)
 320                            (setq found try-file))))
 321                    (if found
 322                        (setq image
 323                              (cons 'image (plist-put (copy-sequence spec)
 324                                                      :file found))))))
 325                 ((not (null data))
 326                  (setq image (cons 'image spec)))))
 327         (setq specs (cdr specs))))
 328     image))
 329
 330
 331 ;;;###autoload
 332 (defmacro defimage (symbol specs &optional doc)
 333   "Define SYMBOL as an image.
 334
 335 SPECS is a list of image specifications.  DOC is an optional
 336 documentation string.
 337
 338 Each image specification in SPECS is a property list.  The contents of
 339 a specification are image type dependent.  All specifications must at
 340 least contain the properties `:type TYPE' and either `:file FILE' or
 341 `:data DATA', where TYPE is a symbol specifying the image type,
 342 e.g. `xbm', FILE is the file to load the image from, and DATA is a
 343 string containing the actual image data.  The first image
 344 specification whose TYPE is supported, and FILE exists, is used to
 345 define SYMBOL.
 346
 347 Example:
 348
 349    (defimage test-image ((:type xpm :file \"~/test1.xpm\")
 350                          (:type xbm :file \"~/test1.xbm\")))"
 351   `(defvar ,symbol (find-image ',specs) ,doc))
 352
 353
 354 (provide 'image)
 355
 356 ;;; arch-tag: 8e76a07b-eb48-4f3e-a7a0-1a7ba9f096b3
 357 ;;; image.el ends here