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 — sendmsg/recvmsg, see docs/architecture/networking.md
A shareable memory object	missing. A Wayland buffer is a descriptor for memory; a System V segment id is not one. Item 2 of docs/plan/foundations.md, and the one thing now standing between this directory and a Wayland compositor.
Mode setting and double buffering	partial — virtio-gpu binds, no modeset API yet

The v0 protocol below is superseded and the code is frozen. It runs, and it is kept because it is the only thing in the tree that has ever composited anything — but nothing more will be added to it. SchWM and SchDE are referred to throughout and both have been deleted; read those mentions as "the policy module" and "a layer-shell client". See docs/plan/wayland.md.

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

Decided: Schcom moves onto Wayland, replacing the protocol below while keeping the architecture. See docs/plan/wayland.md.

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 GPL-2.0-or-later (see docs/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. struct schcom_surface carries a handle_kind field precisely so that switching would be a new value rather than a protocol break.

That field could not have saved us. Wayland's wl_shm_create_pool passes a descriptor with no alternative form, so our protocol being the flexible one was never the flexibility that was needed — and for a long time this README claimed SCM_RIGHTS was done when there was no sendmsg/recvmsg in the kernel at all. An entire GUI plan was drawn on top of that line.

It is true now. Item 1 of docs/plan/foundations.md is built and tested; what a buffer still needs is item 2, a shareable memory object, because a descriptor for a System V segment is not a thing that exists.