SchOS/projects/schcom/README.md

Schcom — the SchOS Compositor

Owns the display. Every pixel that reaches the screen goes through it.

Clients do not draw to the framebuffer; they draw into their own buffers and hand them over. Schcom decides what is on top of what, composites the result, and presents it. It also owns input: it reads the raw event devices and sends each event to whichever client should have it.

That is the whole job. Window placement is not part of it — that is SchWM's, and Schcom exposes a protocol for it rather than implementing policy itself.

Status

v0 runs. A client connects, is given a shared buffer, draws into it and commits; the result is composited and presented. Verified end to end by make schcom-test, which boots SchOS, runs the compositor and a client, then screendumps the framebuffer and asserts the pixels from the host — the compositor's own report that it composited something proves nothing. It runs two overlapping clients and checks that the newer one wins in the overlap: a compositor that cannot order two surfaces cannot host a window manager.

What exists:

• framebuffer output through /dev/fb0 and the fbdev ioctls, double-buffered
• a versioned protocol over a Unix socket, with a handshake that must come first
• shared-memory buffers, one per surface, owned by the compositor
• surface / attach / commit semantics: nothing is shown mid-draw
• input from /dev/input/eventN, routed to the topmost surface
• clients that die are cleaned up, including their shm segments
• multiple clients, composited bottom-to-top in creation order

What does not exist yet: damage tracking beyond "repaint everything", multiple outputs, subsurfaces, and any focus model beyond "topmost". Those are additions rather than rewrites, which is the reason for committing to the surface/commit model now instead of growing into it later.

Building

Not part of the OS build. Needs make ports first, for the sysroot's libc:

make projects        # builds and stages into sysroot/bin
make                 # rebuilds the image so the binaries are on it
make schcom-test     # boots it and checks the pixels

What it needs from the kernel

Need	State
Shared memory (shmget/shmat/shmdt)	done
mmap of /dev/fb0	done
Framebuffer geometry via the fbdev ioctls	done
Unix domain sockets	done
Raw input events — key down/up with modifiers	done
SCM_RIGHTS	done, and not yet used — see below
Mode setting and double buffering	partial — virtio-gpu binds, no modeset API yet

Design notes

• Buffers are shared memory, not pipes. A pipe means copying every frame; at 800×600×32 that is 1.9 MB per frame per client.
• The compositor owns the segment, not the client. It has to survive a client crashing mid-frame, and it must not be something a client can resize underneath the compositor.
• One protocol, versioned from the start. SchWM and SchDE are separate programs, so this is a real compatibility surface on day one. Every message carries its own length, so an unknown message is skipped rather than desynchronising the stream — that is what lets a v0 compositor survive a v1 client.
• Policy belongs to SchWM. If Schcom starts deciding where windows go, the split has already failed. CREATE_SURFACE carries x/y today only because there is no SchWM yet to ask.

On Wayland

The protocol is deliberately Wayland-shaped — surfaces rather than windows, buffers attached and made visible only on commit, and the compositor telling clients when to draw. Wayland is MIT-licensed, so it can be linked against without any conflict with Apache-2.0 (see docs/architecture/licensing.md), and supporting it later is intended.

The one place v0 knowingly diverges: a buffer handle is a System V shared memory id passed as an integer, where Wayland passes a file descriptor over SCM_RIGHTS. The kernel supports SCM_RIGHTS already; an integer simply needs no ancillary-data handling on either side. struct schcom_surface carries a handle_kind field precisely so that switching is a new value rather than a protocol break.