├── LICENSE ├── README.md ├── VERSION ├── flake.lock ├── flake.nix ├── hyprland-protocols.pc.in ├── meson.build ├── nix └── default.nix └── protocols ├── hyprland-ctm-control-v1.xml ├── hyprland-focus-grab-v1.xml ├── hyprland-global-shortcuts-v1.xml ├── hyprland-lock-notify-v1.xml ├── hyprland-surface-v1.xml ├── hyprland-toplevel-export-v1.xml └── hyprland-toplevel-mapping-v1.xml /LICENSE: -------------------------------------------------------------------------------- 1 | BSD 3-Clause License 2 | 3 | Copyright (c) 2022, Hypr Development 4 | All rights reserved. 5 | 6 | Redistribution and use in source and binary forms, with or without 7 | modification, are permitted provided that the following conditions are met: 8 | 9 | 1. Redistributions of source code must retain the above copyright notice, this 10 | list of conditions and the following disclaimer. 11 | 12 | 2. Redistributions in binary form must reproduce the above copyright notice, 13 | this list of conditions and the following disclaimer in the documentation 14 | and/or other materials provided with the distribution. 15 | 16 | 3. Neither the name of the copyright holder nor the names of its 17 | contributors may be used to endorse or promote products derived from 18 | this software without specific prior written permission. 19 | 20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 21 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 23 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 24 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 26 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 27 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 28 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # hyprland-protocols 2 | Wayland protocol extensions for Hyprland. 3 | 4 | This repository exists in an effort to bridge the gap between Hyprland and KDE/Gnome's functionality, 5 | as well as allow apps for some extra neat functionality under Hyprland. 6 | 7 | Since `wayland-protocols` is slow to change (on top of Hyprland not being allowed to contribute), we have to maintain 8 | a set of protocols Hyprland uses to plumb some things / add some useful features. 9 | 10 | Some of the protocols here also do not belong in w-p, as they are specific to Hyprland. 11 | 12 | # Finished protocols 13 | - `hyprland_toplevel_export` -> for exporting toplevel buffers (aka. windows) for screensharing 14 | - `hyprland_global_keybindings` -> for managing global keybinds via D-Bus. 15 | - `hyprland_focus_grab` -> for grabbing input focus, primarily for complex context menus. 16 | - `hyprland_ctm_control` -> for managing CTMs of displays. See [hyprsunset](https://github.com/hyprwm/hyprsunset) 17 | - `hyprland_surface` -> for setting hyprland specific wl_surface properties. 18 | - `hyprland_lock_notify` -> for notifying a client about the screen being locked and unlocked. 19 | - `hyprland_toplevel_mapping` -> for mapping toplevels to hyprland IDs. 20 | 21 | # Contributing 22 | Adding new protocols is *discouraged*, as most things you think of can already be done one way or another. 23 | However, if the protocol has a good reason to be, and you have an impl ready, feel free to make a PR. 24 | We're always up for a discussion to improve things! 25 | 26 | Fixing typos / adding explanations to existing protocols - welcome. 27 | 28 | Adding functionality to protocols / new revisions - welcome, if accompanied with a reason and an impl. 29 | 30 | -------------------------------------------------------------------------------- /VERSION: -------------------------------------------------------------------------------- 1 | 0.6.4 2 | -------------------------------------------------------------------------------- /flake.lock: -------------------------------------------------------------------------------- 1 | { 2 | "nodes": { 3 | "nixpkgs": { 4 | "locked": { 5 | "lastModified": 1721138476, 6 | "narHash": "sha256-+W5eZOhhemLQxelojLxETfbFbc19NWawsXBlapYpqIA=", 7 | "owner": "NixOS", 8 | "repo": "nixpkgs", 9 | "rev": "ad0b5eed1b6031efaed382844806550c3dcb4206", 10 | "type": "github" 11 | }, 12 | "original": { 13 | "owner": "NixOS", 14 | "ref": "nixos-unstable", 15 | "repo": "nixpkgs", 16 | "type": "github" 17 | } 18 | }, 19 | "root": { 20 | "inputs": { 21 | "nixpkgs": "nixpkgs", 22 | "systems": "systems" 23 | } 24 | }, 25 | "systems": { 26 | "locked": { 27 | "lastModified": 1689347949, 28 | "narHash": "sha256-12tWmuL2zgBgZkdoB6qXZsgJEH9LR3oUgpaQq2RbI80=", 29 | "owner": "nix-systems", 30 | "repo": "default-linux", 31 | "rev": "31732fcf5e8fea42e59c2488ad31a0e651500f68", 32 | "type": "github" 33 | }, 34 | "original": { 35 | "owner": "nix-systems", 36 | "repo": "default-linux", 37 | "type": "github" 38 | } 39 | } 40 | }, 41 | "root": "root", 42 | "version": 7 43 | } 44 | -------------------------------------------------------------------------------- /flake.nix: -------------------------------------------------------------------------------- 1 | { 2 | description = "Hyprland Protocols"; 3 | 4 | inputs = { 5 | nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable"; 6 | # 7 | systems.url = "github:nix-systems/default-linux"; 8 | }; 9 | 10 | outputs = { 11 | self, 12 | nixpkgs, 13 | systems, 14 | ... 15 | }: let 16 | inherit (nixpkgs) lib; 17 | eachSystem = lib.genAttrs (import systems); 18 | pkgsFor = eachSystem (system: 19 | import nixpkgs { 20 | localSystem = system; 21 | overlays = [self.overlays.hyprland-protocols]; 22 | }); 23 | mkDate = longDate: (lib.concatStringsSep "-" [ 24 | (builtins.substring 0 4 longDate) 25 | (builtins.substring 4 2 longDate) 26 | (builtins.substring 6 2 longDate) 27 | ]); 28 | version = lib.removeSuffix "\n" (builtins.readFile ./VERSION); 29 | in { 30 | overlays = { 31 | default = self.overlays.hyprland-protocols; 32 | hyprland-protocols = final: prev: { 33 | hyprland-protocols = final.callPackage ./nix/default.nix { 34 | version = version + "+date=" + (mkDate (self.lastModifiedDate or "19700101")) + "_" + (self.shortRev or "dirty"); 35 | }; 36 | }; 37 | }; 38 | 39 | packages = eachSystem (system: { 40 | inherit (pkgsFor.${system}) hyprland-protocols; 41 | default = self.packages.${system}.hyprland-protocols; 42 | }); 43 | 44 | formatter = eachSystem (system: nixpkgs.legacyPackages.${system}.alejandra); 45 | }; 46 | } 47 | -------------------------------------------------------------------------------- /hyprland-protocols.pc.in: -------------------------------------------------------------------------------- 1 | prefix=@prefix@ 2 | datarootdir=@datarootdir@ 3 | pkgdatadir=${pc_sysrootdir}${datarootdir}/@PACKAGE@ 4 | 5 | Name: Hyprland Protocols 6 | Description: Hyprland protocol files 7 | Version: @HYPRLAND_PROTOCOLS_VERSION@ 8 | -------------------------------------------------------------------------------- /meson.build: -------------------------------------------------------------------------------- 1 | project('hyprland-protocols', 2 | version: run_command('cat', 'VERSION', check: true).stdout().strip(), 3 | meson_version: '>= 0.60.3', 4 | ) 5 | 6 | hyprland_protocols_version = meson.project_version() 7 | 8 | fs = import('fs') 9 | 10 | protocols = { 11 | 'hyprland-toplevel-export': ['v1'], 12 | 'hyprland-toplevel-mapping': ['v1'], 13 | 'hyprland-global-shortcuts': ['v1'], 14 | 'hyprland-focus-grab': ['v1'], 15 | 'hyprland-ctm-control': ['v1'], 16 | 'hyprland-surface': ['v1'], 17 | 'hyprland-lock-notify': ['v1'], 18 | } 19 | 20 | protocol_files = [] 21 | 22 | foreach name : protocols.keys() 23 | foreach version : protocols.get(name) 24 | protocol_files += [ 25 | 'protocols/@0@-@1@.xml'.format(name, version) 26 | ] 27 | endforeach 28 | endforeach 29 | 30 | foreach protocol_file : protocol_files 31 | protocol_install_dir = fs.parent(join_paths( 32 | get_option('datadir'), 33 | 'hyprland-protocols', 34 | protocol_file, 35 | )) 36 | install_data( 37 | protocol_file, 38 | install_dir: protocol_install_dir, 39 | ) 40 | endforeach 41 | 42 | hyprland_protocols_srcdir = meson.current_source_dir() 43 | 44 | pkgconfig_configuration = configuration_data() 45 | pkgconfig_configuration.set('prefix', get_option('prefix')) 46 | pkgconfig_configuration.set('datarootdir', '${prefix}/@0@'.format(get_option('datadir'))) 47 | pkgconfig_configuration.set('abs_top_srcdir', hyprland_protocols_srcdir) 48 | pkgconfig_configuration.set('PACKAGE', 'hyprland-protocols') 49 | pkgconfig_configuration.set('HYPRLAND_PROTOCOLS_VERSION', hyprland_protocols_version) 50 | 51 | pkg_install_dir = join_paths(get_option('datadir'), 'pkgconfig') 52 | configure_file( 53 | input: 'hyprland-protocols.pc.in', 54 | output: 'hyprland-protocols.pc', 55 | configuration: pkgconfig_configuration, 56 | install_dir: pkg_install_dir, 57 | ) 58 | 59 | hyprland_protocols = declare_dependency( 60 | variables: { 61 | 'pkgdatadir': hyprland_protocols_srcdir, 62 | }, 63 | ) 64 | 65 | meson.override_dependency('hyprland-protocols', hyprland_protocols) 66 | -------------------------------------------------------------------------------- /nix/default.nix: -------------------------------------------------------------------------------- 1 | { 2 | lib, 3 | stdenv, 4 | meson, 5 | ninja, 6 | version, 7 | }: 8 | stdenv.mkDerivation { 9 | pname = "hyprland-protocols"; 10 | inherit version; 11 | 12 | src = ../.; 13 | 14 | nativeBuildInputs = [meson ninja]; 15 | 16 | meta = { 17 | homepage = "https://github.com/hyprwm/hyprland-protocols"; 18 | description = "Wayland protocol extensions for Hyprland"; 19 | license = lib.licenses.bsd3; 20 | platforms = lib.platforms.linux; 21 | }; 22 | } 23 | -------------------------------------------------------------------------------- /protocols/hyprland-ctm-control-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2024 Vaxry 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol allows a client to control outputs' color transform matrix (CTM). 35 | 36 | This protocol is privileged and should not be exposed to unprivileged clients. 37 | 38 | 39 | 40 | 41 | This object is a manager which offers requests to control CTMs. 42 | 43 | If any changes are done, once this object is destroyed, CTMs are reset back to 44 | an identity matrix. 45 | 46 | 47 | 48 | 49 | Set a CTM for a wl_output. 50 | 51 | This state is not applied immediately; clients must call .commit to 52 | apply any pending changes. 53 | 54 | The provided values describe a 3x3 Row-Major CTM with values in the range of [0, ∞) 55 | 56 | Passing values outside of the range will raise an invalid_matrix error. 57 | 58 | The default value of the CTM is an identity matrix. 59 | 60 | If an output doesn't get a CTM set with set_ctm_for_output and commit is called, 61 | that output will get its CTM reset to an identity matrix. 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | Commits the pending state(s) set by set_ctm_for_output. 78 | 79 | 80 | 81 | 82 | 83 | All objects created by the manager will still remain valid, until their 84 | appropriate destroy request has been called. 85 | 86 | The CTMs of all outputs will be reset to an identity matrix. 87 | 88 | 89 | 90 | 91 | 93 | 94 | 95 | 96 | 97 | This event is sent if another manager was bound by any client 98 | at the time the current manager was bound. 99 | Any set_ctm_for_output requests from a blocked manager will be 100 | silently ignored by the compositor. 101 | 102 | The client should destroy the manager after receiving this event. 103 | 104 | 105 | 106 | 107 | -------------------------------------------------------------------------------- /protocols/hyprland-focus-grab-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2024 outfoxxed 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol allows clients to limit input focus to a specific set 35 | of surfaces and receive a notification when the limiter is removed as 36 | detailed below. 37 | 38 | 39 | 40 | 41 | This interface allows a client to create surface grab objects. 42 | 43 | 44 | 45 | 46 | Create a surface grab object. 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | Destroy the focus grab manager. 55 | This doesn't destroy existing focus grab objects. 56 | 57 | 58 | 59 | 60 | 61 | 62 | This interface restricts input focus to a specified whitelist of 63 | surfaces as long as the focus grab object exists and has at least 64 | one comitted surface. 65 | 66 | Mouse and touch events inside a whitelisted surface will be passed 67 | to the surface normally, while events outside of a whitelisted surface 68 | will clear the grab object. Keyboard events will be passed to the client 69 | and a compositor-picked surface in the whitelist will receive a 70 | wl_keyboard::enter event if a whitelisted surface is not already entered. 71 | 72 | Upon meeting implementation-defined criteria usually meaning a mouse or 73 | touch input outside of any whitelisted surfaces, the compositor will 74 | clear the whitelist, rendering the grab inert and sending the cleared 75 | event. The same will happen if another focus grab or similar action 76 | is started at the compositor's discretion. 77 | 78 | 79 | 80 | 81 | Add a surface to the whitelist. Destroying the surface is treated the 82 | same as an explicit call to remove_surface and duplicate additions are 83 | ignored. 84 | 85 | Does not take effect until commit is called. 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | Remove a surface from the whitelist. Destroying the surface is treated 94 | the same as an explicit call to this function. 95 | 96 | If the grab was active and the removed surface was entered by the 97 | keyboard, another surface will be entered on commit. 98 | 99 | Does not take effect until commit is called. 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | Commit pending changes to the surface whitelist. 108 | 109 | If the list previously had no entries and now has at least one, the grab 110 | will start. If it previously had entries and now has none, the grab will 111 | become inert. 112 | 113 | 114 | 115 | 116 | 117 | Destroy the grab object and remove the grab if active. 118 | 119 | 120 | 121 | 122 | 123 | Sent when an active grab is cancelled by the compositor, 124 | regardless of cause. 125 | 126 | 127 | 128 | 129 | -------------------------------------------------------------------------------- /protocols/hyprland-global-shortcuts-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2022 Vaxry 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol allows a client to register triggerable actions, 35 | meant to be global shortcuts. 36 | 37 | 38 | 39 | 40 | This object is a manager which offers requests to create global shortcuts. 41 | 42 | 43 | 44 | 45 | Register a new global shortcut. 46 | 47 | A global shortcut is anonymous, meaning the app does not know what key(s) trigger it. 48 | 49 | The shortcut's keybinding shall be dealt with by the compositor. 50 | 51 | In the case of a duplicate app_id + id combination, the already_taken protocol error is raised. 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | All objects created by the manager will still remain valid, until their 63 | appropriate destroy request has been called. 64 | 65 | 66 | 67 | 68 | 70 | 71 | 72 | 73 | 74 | 75 | This object represents a single shortcut. 76 | 77 | 78 | 79 | 80 | The keystroke was pressed. 81 | 82 | tv_ values hold the timestamp of the occurrence. 83 | 84 | 86 | 88 | 90 | 91 | 92 | 93 | 94 | The keystroke was released. 95 | 96 | tv_ values hold the timestamp of the occurrence. 97 | 98 | 100 | 102 | 104 | 105 | 106 | 107 | 108 | Destroys the shortcut. Can be sent at any time by the client. 109 | 110 | 111 | 112 | 113 | -------------------------------------------------------------------------------- /protocols/hyprland-lock-notify-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2025 Maximilian Seidler 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | 35 | This interface allows clients to monitor whether the wayland session is 36 | locked or unlocked. 37 | 38 | 39 | 40 | 41 | Destroy the manager object. All objects created via this interface 42 | remain valid. 43 | 44 | 45 | 46 | 47 | 48 | Create a new lock notification object. 49 | 50 | If the session is already locked when calling this method, 51 | the locked event shall be sent immediately. 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | This interface is used by the compositor to send lock notification events 60 | to clients. 61 | 62 | Typically the "locked" and "unlocked" events are emitted when a client 63 | locks/unlocks the session via ext-session-lock, but the compositor may 64 | choose to send notifications for any other locking mechanisms. 65 | 66 | The compositor must notfiy after possible transition periods 67 | between locked and unlocked states of the session. 68 | In the context of ext-session-lock, that means the "locked" event is 69 | expected to be sent after the session-lock client has presented 70 | a lock screen frame on every output, which corresponds to the "locked" 71 | event of ext-session-lock. 72 | 73 | 74 | 75 | 76 | Destroy the notification object. 77 | 78 | 79 | 80 | 81 | 82 | This event is sent when the wayland session is locked. 83 | 84 | It's a compositor protocol error to send this event twice without an 85 | unlock event in-between. 86 | 87 | 88 | 89 | 90 | 91 | This event is sent when the wayland session is unlocked. 92 | 93 | It's a compositor protocol error to send this event twice without an 94 | locked event in-between. It's a compositor protocol error to send this 95 | event prior to any locked event. 96 | 97 | 98 | 99 | 100 | -------------------------------------------------------------------------------- /protocols/hyprland-surface-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2025 outfoxxed 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol exposes hyprland-specific wl_surface properties. 35 | 36 | 37 | 38 | 39 | This interface allows a client to create hyprland surface objects. 40 | 41 | 42 | 43 | 44 | Create a hyprland surface object for the given wayland surface. 45 | 46 | If the wl_surface already has an associated hyprland_surface_v1 object, 47 | even from a different manager, creation is a protocol error. 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | Destroy the surface manager. 57 | This does not destroy existing surface objects. 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | This interface allows access to hyprland-specific properties of a wl_surface. 69 | 70 | Once the wl_surface has been destroyed, the hyprland surface object must be 71 | destroyed as well. All other operations are a protocol error. 72 | 73 | 74 | 75 | 76 | Sets a multiplier for the overall opacity of the surface. 77 | This multiplier applies to visual effects such as blur behind the surface 78 | in addition to the surface's content. 79 | 80 | The default value is 1.0. 81 | Setting a value outside of the range 0.0 - 1.0 (inclusive) is a protocol error. 82 | Does not take effect until wl_surface.commit is called. 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | Destroy the hyprland surface object, resetting properties provided 91 | by this interface to their default values on the next wl_surface.commit. 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | This request sets the region of the surface that contains visible content. 103 | Visible content refers to content that has an alpha value greater than zero. 104 | 105 | The visible region is an optimization hint for the compositor that lets it 106 | avoid drawing parts of the surface that are not visible. Setting a visible region 107 | that does not contain all content in the surface may result in missing content 108 | not being drawn. 109 | 110 | The visible region is specified in buffer-local coordinates. 111 | 112 | The compositor ignores the parts of the visible region that fall outside of the surface. 113 | When all parts of the region fall outside of the buffer geometry, the compositor may 114 | avoid rendering the surface entirely. 115 | 116 | The initial value for the visible region is empty. Setting the 117 | visible region has copy semantics, and the wl_region object can be destroyed immediately. 118 | A NULL wl_region causes the visible region to be set to empty. 119 | 120 | Does not take effect until wl_surface.commit is called. 121 | 122 | 123 | 124 | 125 | 126 | 127 | -------------------------------------------------------------------------------- /protocols/hyprland-toplevel-export-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2022 Vaxry 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol allows clients to ask for exporting another toplevel's 35 | surface(s) to a buffer. 36 | 37 | Particularly useful for sharing a single window. 38 | 39 | 40 | 41 | 42 | This object is a manager which offers requests to start capturing from a 43 | source. 44 | 45 | 46 | 47 | 48 | Capture the next frame of a toplevel. (window) 49 | 50 | The captured frame will not contain any server-side decorations and will 51 | ignore the compositor-set geometry, like e.g. rounded corners. 52 | 53 | It will contain all the subsurfaces and popups, however the latter will be clipped 54 | to the geometry of the base surface. 55 | 56 | The handle parameter refers to the address of the window as seen in `hyprctl clients`. 57 | For example, for d161e7b0 it would be 3512854448. 58 | 59 | 60 | 62 | 63 | 64 | 65 | 66 | 67 | All objects created by the manager will still remain valid, until their 68 | appropriate destroy request has been called. 69 | 70 | 71 | 72 | 73 | 74 | 75 | Same as capture_toplevel, but with a zwlr_foreign_toplevel_handle_v1 handle. 76 | 77 | 78 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | This object represents a single frame. 88 | 89 | When created, a series of buffer events will be sent, each representing a 90 | supported buffer type. The "buffer_done" event is sent afterwards to 91 | indicate that all supported buffer types have been enumerated. The client 92 | will then be able to send a "copy" request. If the capture is successful, 93 | the compositor will send a "flags" followed by a "ready" event. 94 | 95 | wl_shm buffers are always supported, ie. the "buffer" event is guaranteed to be sent. 96 | 97 | If the capture failed, the "failed" event is sent. This can happen anytime 98 | before the "ready" event. 99 | 100 | Once either a "ready" or a "failed" event is received, the client should 101 | destroy the frame. 102 | 103 | 104 | 105 | 106 | Provides information about wl_shm buffer parameters that need to be 107 | used for this frame. This event is sent once after the frame is created 108 | if wl_shm buffers are supported. 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | Copy the frame to the supplied buffer. The buffer must have the 119 | correct size, see hyprland_toplevel_export_frame_v1.buffer and 120 | hyprland_toplevel_export_frame_v1.linux_dmabuf. The buffer needs to have a 121 | supported format. 122 | 123 | If the frame is successfully copied, a "flags" and a "ready" event is 124 | sent. Otherwise, a "failed" event is sent. 125 | 126 | This event will wait for appropriate damage to be copied, unless the ignore_damage 127 | arg is set to a non-zero value. 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | This event is sent right before the ready event when ignore_damage was 136 | not set. It may be generated multiple times for each copy 137 | request. 138 | 139 | The arguments describe a box around an area that has changed since the 140 | last copy request that was derived from the current screencopy manager 141 | instance. 142 | 143 | The union of all regions received between the call to copy 144 | and a ready event is the total damage since the prior ready event. 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 155 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | Provides flags about the frame. This event is sent once before the 166 | "ready" event. 167 | 168 | 169 | 170 | 171 | 172 | 173 | Called as soon as the frame is copied, indicating it is available 174 | for reading. This event includes the time at which presentation happened 175 | at. 176 | 177 | The timestamp is expressed as tv_sec_hi, tv_sec_lo, tv_nsec triples, 178 | each component being an unsigned 32-bit value. Whole seconds are in 179 | tv_sec which is a 64-bit value combined from tv_sec_hi and tv_sec_lo, 180 | and the additional fractional part in tv_nsec as nanoseconds. Hence, 181 | for valid timestamps tv_nsec must be in [0, 999999999]. The seconds part 182 | may have an arbitrary offset at start. 183 | 184 | After receiving this event, the client should destroy the object. 185 | 186 | 188 | 190 | 192 | 193 | 194 | 195 | 196 | This event indicates that the attempted frame copy has failed. 197 | 198 | After receiving this event, the client should destroy the object. 199 | 200 | 201 | 202 | 203 | 204 | Destroys the frame. This request can be sent at any time by the client. 205 | 206 | 207 | 208 | 209 | 210 | Provides information about linux-dmabuf buffer parameters that need to 211 | be used for this frame. This event is sent once after the frame is 212 | created if linux-dmabuf buffers are supported. 213 | 214 | 215 | 216 | 217 | 218 | 219 | 220 | 221 | This event is sent once after all buffer events have been sent. 222 | 223 | The client should proceed to create a buffer of one of the supported 224 | types, and send a "copy" request. 225 | 226 | 227 | 228 | 229 | -------------------------------------------------------------------------------- /protocols/hyprland-toplevel-mapping-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2025 WhySoBad 5 | All rights reserved. 6 | 7 | Redistribution and use in source and binary forms, with or without 8 | modification, are permitted provided that the following conditions are met: 9 | 10 | 1. Redistributions of source code must retain the above copyright notice, this 11 | list of conditions and the following disclaimer. 12 | 13 | 2. Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | 17 | 3. Neither the name of the copyright holder nor the names of its 18 | contributors may be used to endorse or promote products derived from 19 | this software without specific prior written permission. 20 | 21 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 22 | AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 23 | IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 24 | DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE 25 | FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 26 | DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 27 | SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 28 | CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29 | OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 30 | OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | 32 | 33 | 34 | This protocol allows clients to retrieve the mapping of toplevels to hyprland window addresses. 35 | 36 | 37 | 38 | 39 | This object is a manager which offers requests to retrieve a window address 40 | for a toplevel. 41 | 42 | 43 | 44 | 45 | Get the window address for a toplevel. 46 | 47 | 52 | 58 | 59 | 60 | 61 | 62 | Get the window address for a wlr toplevel. 63 | 64 | 69 | 75 | 76 | 77 | 78 | 79 | All objects created by the manager will still remain valid, until their appropriate destroy 80 | request has been called. 81 | 82 | 83 | 84 | 85 | 86 | 87 | This object represents a mapping of a (wlr) toplevel to a window address. 88 | 89 | Once created, the `window_address` event will be sent containing the address of the window 90 | associated with the toplevel. 91 | Should the mapping fail, the `failed` event will be sent. 92 | 93 | 94 | 95 | 96 | The full 64bit window address. The `address` field contains the lower 32 bits whilst the 97 | `address_hi` contains the upper 32 bits 98 | 99 | 104 | 109 | 110 | 111 | 112 | 113 | The mapping of the toplevel to a window address failed. Most likely the window does not 114 | exist (anymore). 115 | 116 | 117 | 118 | 119 | 120 | Destroy the handle. This request can be sent at any time by the client. 121 | 122 | 123 | 124 | --------------------------------------------------------------------------------