PALE: Picture & Animation Library for Emacs

This a graphics programmers’ nightmare. It is an attempt to do real-time graphics in Emacs buffers. The library aims to provide an API that can be used by anything else that intends to draw inside Emacs (buffers).

It supports raw PPM binary data, i.e., it is provided with image data in PPM format and the library will efficiently display and manipulate it inside Emacs. The library can also display videos by calling `ffmpeg` in an UNIX pipe and then rendering the frames as PPMs.

Dependencies

The only thing this package depends on GNU/Linux is EGL and OpenGL, it uses both of them in a headless manner so none of the "toolkits" of OpenGL are necessary, your GNU/Linux distribution should already have them through Mesa.

When using this library on MacOS systems, it relies on Metal since Apple has deprecated OpenGL since MacOS 10.14.

Installation

Since this is not yet packaged for any of the package repositories, you have to manually fetch it with package-vc:

  (use-package pale
    :vc (:url "https://codeberg.org/pale/pale"
         :make "all"))

The package right now has been tested on MacOS and GNU/Linux, we shall work more on portability in the near future.

Development testing

make pale-module.so

on GNU Linux and

make pale-module.dylib

wil create the dynamic module. You should call load-file on the two before you load pale.el.

Testing

You can verify that the system is set up correctly by evaluating in e.g. a scratch buffer

  (defun test-pale()
	""
	(interactive)
	(setq pale-video-canvas (pale-image-create 1280 720 256))
	(switch-to-buffer "*pale-video*")
	(pale-display pale-video-canvas)
	;Place a path to a local video here
	(setq player (pale-video-play pale-video-canvas "<REPLACE ME>")))

and then running the interactive command test-pale anywhere in Emacs. If you don't see a full video, you can check the diagnostics buffer and report the issue here.

Architecture

PALE is built as a dynamic module package + library for Emacs. It’s goal is to render and manipulate high-resolution images inside Emacs buffers, and provide an API for other packages that require such image manipulation.

PALE is hardware-accelerated, i.e. it uses the GPU to render textures and then fetch the RGB pixels and package them as PPM tiles. Tiling is one of the core architectures of the library, since Emacs really struggles when displaying huge images we split the image into small tiles and then put those tiles in a pixel-perfect manner in the buffer.

The process of tiling an image and producing PPM for each tile is done by the GPU, all Emacs cares about is displaying those small tiles. And since they are pretty small, Emacs doesn’t have much of an issue with it.

Damage tracking

For animation, we don’t have to update the entire big image, we track certain "dirty tiles" which need to be updated and then change the PPM data for their corresponding overlays. This allows us to swiftly mimic animation without passing the same high-resolution image through Emacs’ garbage collector again and again.

For video, we ask ffmpeg to give us RGB24 pixel data for each frame, which we then upload to the GPU for texture rendering and then as above get the pixels turn them into PPM tiles and display.

To see PALE in action, check out the videos in this thread.

History

This library was created in order to support the Emacs Reader package, a general purpose document reader inside Emacs. The author was frustrated while developing Reader in the myriad hacks one has to try for smoothly drawing into Emacs. This library is a collection of such hacks, with a neat API for others to use.

The library shouldn’t actually exist, and Emacs should by default provide such facilities out of the box in its image creation and manipulation functions, but it doesn’t. If you’re interested in following that discussion on emacs-devel, check here:

• https://lists.gnu.org/archive/html/emacs-devel/2025-08/msg00255.html
• https://lists.gnu.org/archive/html/emacs-devel/2025-12/msg00135.html