{"id":25323774,"url":"https://github.com/madlittlemods/zig-x-compositing-manager","last_synced_at":"2025-04-07T23:14:03.378Z","repository":{"id":276899063,"uuid":"864215299","full_name":"MadLittleMods/zig-x-compositing-manager","owner":"MadLittleMods","description":"A basic \"compositing manager\" for the X Window System written in Zig","archived":false,"fork":false,"pushed_at":"2025-02-11T02:41:15.000Z","size":219,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-07T23:13:52.778Z","etag":null,"topics":["compositing-manager","compositor","window-manager","x-composite-extension","x-compositing-manager","x-window-manager","x-window-system","x11","xephyr","xvfb","zig","ziglang"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MadLittleMods.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-27T17:56:10.000Z","updated_at":"2025-02-12T04:56:13.000Z","dependencies_parsed_at":"2025-02-11T03:37:39.922Z","dependency_job_id":null,"html_url":"https://github.com/MadLittleMods/zig-x-compositing-manager","commit_stats":null,"previous_names":["madlittlemods/zig-x-compositing-manager"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLittleMods%2Fzig-x-compositing-manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLittleMods%2Fzig-x-compositing-manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLittleMods%2Fzig-x-compositing-manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadLittleMods%2Fzig-x-compositing-manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MadLittleMods","download_url":"https://codeload.github.com/MadLittleMods/zig-x-compositing-manager/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247744333,"owners_count":20988783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["compositing-manager","compositor","window-manager","x-composite-extension","x-compositing-manager","x-window-manager","x-window-system","x11","xephyr","xvfb","zig","ziglang"],"created_at":"2025-02-14T00:26:02.171Z","updated_at":"2025-04-07T23:14:03.370Z","avatar_url":"https://github.com/MadLittleMods.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# X Compositing Manager written in Zig\n\nA basic \"compositing manager\" (aka compositor) for the X Window System that adds transparency/alpha\nblending (compositing) to windows.\n\nNormally, you'd get this same functionality for free via your desktop environment's\nwindow manager which probably includes a \"compositing manager\".\n\nThis project is useful when you're running in a virtual X environment like `Xvfb` (X\nvirtual framebuffer) or `Xephyr` and need to work with multiple windows that overlay on\ntop of each other.\n\nTo paraphrase from the [*Adding\nTransparency*](https://magcius.github.io/xplain/article/composite.html) page in the\nXplain series by Jasper St. Pierre; a \"compositing manager\" is needed because by\ndefault, every pixel on the screen is owned by a single window at a time. At any given\npoint in time, you can point to a pixel, and the X server can tell you which window is\nresponsible for painting it. Windows in the X11 protocol sense, aren't a tangible thing.\nThey simply make their mark on the X server's front \"root\" buffer, as a series of pixels\nwhich they own. The issue is that when the bottommost window is being clipped by another\nwindow on top, we don't have access to the pixels that are being occluded at all; they\nsimply don't exist anymore. The topmost window owns that pixel.\n\nTo accomplish transparency, we redirect the output of all windows to off-screen buffers\nand then composite them together to form the final image.\n\n![Demo with three transparent overlapping windows traveling in a circle as they scale up and down (`DISPLAY=:99 zig build test --summary all -Dtest-filter=\"demo\"`)](https://github.com/user-attachments/assets/2132fa0a-33fa-4283-9597-5a9b799ba8d7)\n\n\n## Install:\n\nTested with Zig 0.11.0\n\n 1. Update your `build.zig.zon` to add the dependency:\n    ```zig\n    .{\n        .name = \"my-foo-project\",\n        .version = \"0.0.0\",\n        .dependencies = .{\n            .@\"zig-x-compositing-manager\" = .{\n                .url = \"https://github.com/MadLittleMods/zig-x-compositing-manager/archive/\u003csome-commit-hash-abcde\u003e.tar.gz\",\n                .hash = \"1220416f31bac21c9f69c2493110064324b2ba9e0257ce0db16fb4f94657124d7abc\",\n            },\n        },\n    }\n    ```\n 1. Update your `build.zig` to include the module:\n    ```zig\n    const x_compositing_manager_pkg = b.dependency(\"zig-x-compositing-manager\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n    const x_compositing_manager_mod = x_compositing_manager_pkg.module(\"zig-x-compositing-manager\");\n    // Make the `zig-x-compositing-manager` module available to be imported via `@import(\"zig-x-compositing-manager\")`\n    exe.addModule(\"zig-x-compositing-manager\", x_compositing_manager_mod);\n    exe_tests.addModule(\"zig-x-compositing-manager\", x_compositing_manager_mod);\n    ```\n\n## Usage:\n\nTODO\n\n\n## Building\n\n```sh\nzig build run-main\n```\n\n```sh\nzig build run-test_window -- 50 0 0x88ff0000\n```\n\n\n## Testing\n\n\u003e [!NOTE]\n\u003e\n\u003e Ideally, the tests should be self-contained and runnable without requiring additional\n\u003e setup, such as manually creating and configuring a display of the correct size. By\n\u003e default, it should just run in a headless environment and we'd have `Xvfb` as a\n\u003e dependency that we'd automatically build ourselves to run the tests. I hate when\n\u003e projects require you to install extra system dependencies to get things working. The\n\u003e only thing you should need is the right version of Zig.\n\nLaunch Xephyr (virtual X server that we can run our tests in):\n\n```\nXephyr :99 -screen 1920x1080x24 -retro\n```\n\n - `:99` specifies the display number to create/use in your virtual environment (you can use\n   any number that doesn't collide with an existing display on your system)\n - `-screen 1920x1080x24` creates a 1920x1080 display with 24-bit color depth\n - `-retro` makes the cursor always visible\n\nRun the tests:\n\n```sh\nDISPLAY=:99 zig build test --summary all\n```\n\nFilter down to only run specific tests:\n\n```sh\nDISPLAY=:99 zig build test --summary all -Dtest-filter=\"end-to-end\"\n```\n\nIf you're running into timeout errors and the Xehpyr screen is black instead of the\nretro checkerboard, it probably means our composite manager process was accidentally\nleft running after the test ended and you just need to restart Xephyr to get a clean\ntest environment again.\n\n![Three transparent windows overlapping each other with text updating to show how long each window has been running for. An end-to-end demonstration of the X compositing manager.](https://github.com/user-attachments/assets/887289ac-21d9-4213-accf-45da13ac1dcc)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadlittlemods%2Fzig-x-compositing-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadlittlemods%2Fzig-x-compositing-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadlittlemods%2Fzig-x-compositing-manager/lists"}