stereo-declare

For programmers: tell the desktop, with one call, that your window shows a 3D picture, and it reaches every kind of 3D screen.

Your program hands the desktop both eyes side by side, the left eye first, each at the resolution it has, and declares the window once. Stereo KWin, the compositor of Sparky Stereo OS, then shows each eye to its eye: on a 3D television's own 3D modes, as anaglyph on any monitor with red-cyan glasses, on interleaved and frame-sequential displays, or in a headset. The program never needs to know which screen it is on. On X11, where a window's buffer is its own pixmap, a program whose views are shown at another size than their resolution (the two 1920x540 views of a half top-and-bottom video, shown at 1920x1080) also declares the size one view is shown at, so the compositor still resizes them once (since 1.4.0).

It is a small C library (MIT) for X11 and Wayland, used by the edition's mpv, VLC, Qt Multimedia, MpvQt, Kdenlive, Marble, QEMU, SPICE and others.

Status: version 1.7.0, a stable C API with semantic versioning; it works with Stereo KWin in Sparky Stereo OS, Daniel Ramos's edition of SparkyLinux (by Paweł "pavroo" Pijanowski). On other desktops the calls return -ENOTSUP, nothing is sent, and the window stays an ordinary 2D window.

Start here

• The API, with one example per platform: API.md.
• Complete programs: examples/declare-wayland.c and examples/declare-x11.c.
• Build and install:

cmake -S . -B build -DCMAKE_INSTALL_PREFIX=/usr
cmake --build build
ctest --test-dir build
cmake --install build

Then pkg-config --cflags --libs stereo-declare, or in CMake find_package(StereoDeclare 1.1 CONFIG REQUIRED) and StereoDeclare::stereo-declare. It needs Xlib, libwayland-client, wayland-scanner, wayland-protocols (for content-type-v1) and the kde-stereo-content-v1.xml protocol at version 3, which a release carries in protocol/ as Stereo KWin carries it.

From Python

python/stereo_declare.py calls the same library for programs that cannot link C: a launcher, a game manager. It is installed as stereo_declare (the Debian package python3-stereo-declare) and needs python3-xlib and libstereo-declare.so.1. See "Python" in API.md.

Where it comes from

Written by Daniel Campos Ramos with AI assistance, for Sparky Stereo OS. The protocol it speaks, kde-stereo-content-v1, lives in the edition's fork of KDE's plasma-wayland-protocols; the kind of content goes through wp_content_type_v1 from wayland-protocols (by Emmanuel Gil Peyrot and Xaver Hugl). The one-value shape of the declaration follows the review of Emmanuel Gil Peyrot (linkmauve) on wayland-protocols !533.

Licence: MIT, see LICENSE.