A modern X11 server for macOS, built in 30 days.

Shaped windows: oclock, xeyes, and friends

The SHAPE extension done right. Round windows, oval windows, and the Motif frame plays along.

Shaped windows: oclock, xeyes, and friends
oclock rendering as an actual circle on the Mac desktop. The SHAPE extension applied through the macOS window-clip path lets Finder show through the corners where there is no clock.

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 chrome plays along too: if a shaped client is wrapped in a Motif-style frame, the frame’s SetFrameShape policy reshapes the frame chrome to follow the client’s shape.

Why it matters

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.

More substantively, modern X clients still use SHAPE for tooltips, drop-down chrome, 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.