picom-motion

A note before you read on

picom has been built over more than twenty years by about a hundred people, from xcompmgr and compton to picom today, and its maintainers have kept it working with care for all of that time. This project is a few weeks old, and its code was written with AI. I am an experienced software engineer, but not a C programmer: AI coding agents did most of the research and the implementation. I set the goals, tested every change, judged the results on a real screen, and run it every day. That is a careful process, but it is not the same as code written by people who know picom inside out, and I don't want it taken for that.

It is also large: about 21,000 new lines next to picom's 44,000, nearly half of them tests. This is what the fork holds today, by what it is for:

what every workspace switch style uses: 1,700 lines;
the 3D styles, such as the cube: 2,300;
the overview and the switches that pass workspaces: 4,300, most of it tests;
fixes for problems I ran into along the way: 1,100;
a frame timing log, used to measure all of this: 1,600;
the window animations: 10,100.

None of this is decided. Whether any of it belongs in picom, in this shape or another, is for picom's maintainers to say. If they're interested, I'd start with the smallest part, offer it one or two small PRs at a time, each with its tests and a note on how it was written, and go no further than they want. Anything can be reshaped or declined, and what picom doesn't take stays in the fork.

What this is

picom draws the animations, and its animation scripts decide how they look. But picom doesn't know about workspaces, or why a window moved; the window manager knows that. Two plugins fill that gap, on a fork of picom that adds what they need. Each change in the fork is its own commit, so picom can look at each one on its own, and take it or leave it. The two parts are of very different size.

Workspace transitions: the smaller part

A workspace switch animates the way it went, up or down, left or right, on each monitor, in a style you choose: a slide, a card push, a fold, a turning cube. The ws-direction plugin tells picom's animation scripts which way the switch went and where each workspace lies. It reads only the standard window manager properties (EWMH), so it isn't tied to i3.

This is the smaller part, and the one I'd ask picom about first. Every switch style uses five changes to picom:

variables that plugins give animation scripts, proposed to picom as #1550, and a small xrender fix, #1551;
three fixes to script expressions;
functions in scripts, such as min, max, sin and cos;
scripts that can read the state an interrupted animation left, so a switch during a switch keeps its speed.

#1550 and #1551 are open; the other three are written and tested in the fork. The 3D styles, such as the cube, also use windows drawn in perspective: three more changes. The overview, and the switches that pass several workspaces, use kept pictures of hidden windows and a few more general hooks: twelve more. If picom is interested, I'd offer them one or two at a time, with the fixes found along the way. See the backlog.

A workspace switch on two monitors under i3, in the slide style. It goes sideways on the portrait monitor and up and down on the landscape one, and back the other way. Recorded on a real screen. Pauses between switches are trimmed to the same length; the animations themselves are unedited. Workspace styles

Window animations: the hard part

Animating the windows themselves, as they open, close, move, go fullscreen or float, is much harder. picom sees a window move, but not why. Only the window manager knows that, so the win-cause plugin talks to i3 directly: it asks i3 to say when each change is done, and gives every move its reason, so each reason can have its own animation. That ties it to i3.

The pictures are the other hard part. When a window gets a new size, its program draws the new picture a moment later, and until then picom must show something right, without stretching anything. That took deeper machinery in picom: knowing exactly when a program has drawn, waiting for a window's first picture, keeping old pictures at their own size, filling with the colour of the content, renaming moves, shows and hides, and holding animations so that the windows of one change stay on one clock.

That machinery lives in the fork. Much of it exists for one window manager's sake, so whether picom wants it is an open question. How the pictures are kept right

Windows that open, close, move, go fullscreen and float under i3, on a 16:9 and a 9:16 monitor, in the tile style with the curved way. Each window moves as a rectangle, on one curve and one clock with its neighbours. Its picture is never stretched. Recorded on a real screen. Pauses between steps are trimmed to the same length; the animations themselves are unedited. Fifteen window styles

Three goals

Make it work now. Every workspace and window animation a user or developer might want. When something is in the way, I work around it, in the fork or in a plugin, rather than ask anyone else to hurry.
Offer it where it belongs. Where a change could serve another project, picom, i3 or another window manager, or X, offer it there, and let that project decide. What is the plugins' own job stays in the plugins. The workspace transitions and the fixes would come first; the window animations stay in the fork and the plugin. The backlog shows two sides of each item: what makes it work today, and where it could go. See the backlog.
Do it properly. Animations that fully work, run smoothly and are built cleanly. The owner of the machine, user or developer, chooses which animations run and how they look.

A record of what it takes

This site records what it took to make animations work well on X11, as far as I got. I tried what I could, down to how picom waits for the X server and the driver while it draws a frame. How the code was written is in the note at the top.

What works

Workspace switches that go the right way on each monitor, styles that show the workspaces a switch passes, such as a turning cube, and an overview of all workspaces.
Window animations for every change i3 makes: open, close, fullscreen, floating, resize, swap, move and layout. The windows of one change move together, and a change during a change goes on from where everything is.
Pictures that stay right: a window switches to its new picture at a moment it can't be seen, an opening waits for the program's first picture, and windows covered by a fullscreen window stay in place.
Fewer late frames on NVIDIA, from changes to how picom binds window pictures and when it waits for the X server, and from giving picom's GPU work priority over the programs' drawing.

What X still limits

picom can't use a window's new picture until the program's GPU work on it is done, and X has no signal for when that is. On NVIDIA that wait can take tens of milliseconds.
Every frame, picom asks the X server whether it has finished drawing, and waits for the answer.
Resizing programs step by step during an animation can't be made smooth on X. I tried it and dropped it: every size in between costs the program a redraw and picom a new picture. One resize at the start, with only the box animating, is much smoother.

The details and numbers are under Under the hood.

After this month

I work on this actively for about a month, from November 2026. After that I keep using it and fix what I contributed, but I won't drive new features or an agenda. The fork is a place to keep changes while the projects involved look at them, at their pace, not a picom of its own. The window animations need it for as long as picom has no place for their machinery. Other window managers get support only where that is easy: ws-direction reads plain EWMH properties, while win-cause needs i3.

It is there for picom and its community to use as they see fit, and for anyone who wants to pick up a part of it.