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.

FILE-OR-DATA is an image file name or image data.

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. 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.

Image file names that are not absolute are searched for in the
"images" sub-directory of data-directory and
x-bitmap-file-path (in that order).

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.
FILE-OR-DATA is an image file name or image data.

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'.  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'.

Image file names that are not absolute are searched for in the
\"images\" sub-directory of `data-directory' and
`x-bitmap-file-path' (in that order)."
  (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 'png
            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)))