Function: create-image

create-image is an autoloaded and byte-compiled function defined in image.el.gz.

Signature

(create-image FILE-OR-DATA &optional TYPE DATA-P &rest PROPS)

Documentation

Create an image from FILE-OR-DATA.

FILE-OR-DATA is an image file name or image data. If it is a relative file name, the function will look for it along image-load-path.

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. See Info node (elisp)Image Descriptors for the list of supported properties; see the nodes following that node for properties specific to certain image types.

If the property :scale is not given and the display has a high resolution (more exactly, when the average width of a character in the default font is more than 10 pixels), the image is automatically scaled up in proportion to the default font.

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.

View in manual

Probably introduced at or before Emacs version 21.1.

Source Code

;; Defined in /usr/src/emacs/lisp/image.el.gz
;;;###autoload
(defun create-image (file-or-data &optional type data-p &rest props)
  "Create an image from FILE-OR-DATA.
FILE-OR-DATA is an image file name or image data.  If it is a relative
file name, the function will look for it along `image-load-path'.

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'.  See Info node `(elisp)Image Descriptors' for
the list of supported properties; see the nodes following that node
for properties specific to certain image types.

If the property `:scale' is not given and the display has a high
resolution (more exactly, when the average width of a character
in the default font is more than 10 pixels), the image is
automatically scaled up in proportion to the default font.

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'."
  (let ((data-format
         ;; Pass the image format, if any, if this is data.
         (and data-p (or (plist-get props :format) t))))
    ;; It is x_find_image_file in image.c that sets the search path.
    (setq type (ignore-error unknown-image-type
                 (image-type file-or-data type data-format)))
    ;; If we have external image conversion switched on (for exotic,
    ;; non-native image formats), then we convert the file.
    (when (eq type 'image-convert)
      (require 'image-converter)
      (setq file-or-data (image-convert file-or-data data-format)
            type (intern image-convert-to-format)
            data-p t)))
  (when (image-type-available-p type)
    (let ((image
           (append (list 'image :type type (if data-p :data :file)
                         file-or-data)
                   (and (not (plist-get props :scale))
                        ;; Add default scaling.
                        (list :scale
                              (image-compute-scaling-factor
                               image-scaling-factor)))
                   props)))
      ;; Add default smoothing.
      (unless (plist-member props :transform-smoothing)
        (setq image (nconc image
                           (list :transform-smoothing
                                 (pcase image-transform-smoothing
                                   ('t t)
                                   ('nil nil)
                                   (func (funcall func image)))))))
      image)))