A modern X11 server for macOS, built in 30 days by a seasoned programmer and Agentic AI

Shaped windows: oclock, xeyes, and friends

Round windows and oval windows that stay round at Retina device scale. The SHAPE mask gets traced to a CGPath and rasterized at the window's actual backing resolution, so the edges of oclock and xeyes don't stairstep. The Motif frame plays along.

Shaped windows: oclock, xeyes, and friends
xeyes with the optional Motif title bar above, peering down at an xterm. The two oval eyes are real shaped windows; the terminal's file listing shows through the corners around them, no painted-on background.

What it does

macXserver implements the X11 SHAPE extension (major opcode 128). Clients that use SHAPE to give themselves a non-rectangular outline render with that outline:

  • oclock renders as an actual circle.
  • xeyes renders as a bare oval with no surrounding rectangle.
  • xclock -shape if you ask for it.
  • Any other client that builds itself a shaped top-level via XShapeCombineMask or XShapeCombineRectangles.

The optional Motif frame plays along too: if a shaped client is wrapped in a Motif-style frame, the frame’s SetFrameShape policy reshapes the frame to follow the client’s shape.

The two canonical SHAPE clients are oclock and xeyes, both old X.org demos. They’re not heavily-used, but they’re nearly universally recognized as “the things X can do that other window systems can’t” demos. An X server that displays oclock as a square clock or xeyes as a rectangle with white corners is visibly wrong in a way that anyone who’s used X11 will spot immediately.

oclock rendered as a circle with the optional Motif title bar above it, floating over an Excel window. Excel's toolbar and cells are visible through the corners outside the circular clock face.
oclock with the optional Motif title bar, floating over Excel. The SHAPE mask becomes the NSWindow's opaque region, so Excel's toolbar shows through the corners where the clock face isn't drawn — the transparency is real, not a painted background.

More substantively, modern X clients still use SHAPE for tooltips, drop-down menus, and various floating widgets. Without SHAPE, those render with rectangular halos around them.

Technical detail

SHAPE has three logical pieces: the bounding shape (the outline of the window), the clip shape (the region within the bounding shape that’s drawable), and per-window shape (the same but for child windows). macXserver implements all three; the bounding shape on top-levels is the visually most important and is fully integrated with the AppKit window system.

The trick on the Mac side: NSWindow doesn’t natively support non-rectangular window shapes. The implementation:

  1. The X client sends XShapeCombineMask with a 1-bit pixmap.
  2. The server converts the mask region to a CGPath.
  3. The NSWindow opaque region gets set to that path so the window background shows through outside the shape.
  4. The window’s NSView honors the same path as its mask so drawing is clipped to the shape too.

For descendant windows (children of a shaped top-level), the same clipping is applied through the server’s ClipListEngine rather than AppKit, so the X clipping semantics match the spec exactly.

  • The SHAPE extension shipped Day 24 .
  • Motif-frame integration with SetFrameShape policy shipped same day.
  • SHAPE on descendant windows via clipList shipped Day 28 .