Previous: Showing Images, Up: Images

38.16.11 Image Cache

Emacs caches images so that it can display them again more efficiently. When Emacs displays an image, it searches the image cache for an existing image specification equal to the desired specification. If a match is found, the image is displayed from the cache; otherwise, Emacs loads the image normally.

Occasionally, you may need to tell Emacs to refresh the images associated with a given image specification. For example, suppose you display an image using a specification that contains a :file property. The image is automatically cached, and subsequent displays of that image, with the same image specification, will use the image cache. If the image file changes in the meantime, Emacs would be displaying the old version of the image. In such a situation, you can “refresh” the image by calling image-refresh.

In Emacs' current implementation, each graphical terminal possesses an image cache, which is shared by all the frames on that terminal (see Multiple Terminals). Thus, refreshing an image in one frame also refreshes it in all other frames on the same terminal.

— Function: image-refresh spec &optional frame

This function refreshes any images with image specifications equal to spec on frame frame. If frame is nil, it defaults to the selected frame. If frame is t, the refresh is applied to all existing frames.

— Function: clear-image-cache &optional filter

This function clears an image cache, removing all the images stored in it. If filter is omitted or nil, it clears the cache for the selected frame. If filter is a frame, it clears the cache for that frame. If filter is t, all image caches are cleared. Otherwise, filter is taken to be a file name, and all images associated with that file name are removed from all image caches.

If an image in the image cache has not been displayed for a specified period of time, Emacs removes it from the cache and frees the associated memory.

— Variable: image-cache-eviction-delay

This variable specifies the number of seconds an image can remain in the cache without being displayed. When an image is not displayed for this length of time, Emacs removes it from the image cache.

If the value is nil, Emacs does not remove images from the cache except when you explicitly clear it. This mode can be useful for debugging.