├── .editorconfig ├── LICENSE.md ├── README.md ├── frog-protocols-uninstalled.pc.in ├── frog-protocols.pc.in ├── frog-protocols ├── frog-color-management-v1.xml └── frog-fifo-v1.xml └── meson.build /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [*.xml] 4 | indent_style = space 5 | indent_size = 2 6 | tab_width = 8 7 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | The below is the version of the MIT "Expat" License used by X.org: 2 | 3 | Permission is hereby granted, free of charge, to any person obtaining a 4 | copy of this software and associated documentation files (the "Software"), 5 | to deal in the Software without restriction, including without limitation 6 | the rights to use, copy, modify, merge, publish, distribute, sublicense, 7 | and/or sell copies of the Software, and to permit persons to whom the 8 | Software is furnished to do so, subject to the following conditions: 9 | 10 | The above copyright notice and this permission notice (including the next 11 | paragraph) shall be included in all copies or substantial portions of the 12 | Software. 13 | 14 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 15 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 16 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 17 | THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 18 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 19 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 20 | DEALINGS IN THE SOFTWARE. 21 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Frog Protocols for Wayland 🐸 2 | 3 | **Let's create Wayland Protocols but much more iterative.** 4 | 5 | ## Manifesto 6 | 7 | Wayland Protocols has long had a problem with new protocols sitting for months, to years at a time for even basic functionality. 8 | 9 | This is hugely problematic when some protocols implement very primitive and basic functionality such as `frog-fifo-v1`, which is needed for VSync to not cause GPU starvation under Wayland and also fix the dreaded application freezing when windows are occluded with FIFO/VSync enabled. 10 | 11 | We **need** to get protocols into end-users hands quicker! The main reason many users are still using X11 is because of missing functionality that we can be shipping today, but is blocked for one reason or another. 12 | 13 | ## How do I submit a protocol? 14 | 15 | Basic ground rules: 16 | 17 | - Have a client 18 | - Have a server (compositor) 19 | - Protocols that could *potentially* apply to more than one client only 20 | - Eg. if this protocol is internal to a compositor and some debug client, it's probably not a good fit here. 21 | - Nobody is going to be super picky about this, just use common sense. 22 | 23 | We want this to be usable by clients, in the real world, so we need to lay out how we are going to iterate with that in mind: 24 | 25 | Because this is much more iterative, we won't replace protocols whenever we need to iterate, but simply add `method_v2` or `event_v2` and keep supporting both methods or events, and wrap old methods to new ones in the compositor. 26 | 27 | We will only add a whole new `protocol_v2` if something is totally broken beyond repair. We will never figure this out if we don't ship it and experiment! Not every client cares about every edge case or colour of bike shed. 28 | 29 | ### Support Guidance 30 | 31 | **As a server**: If you implemented a protocol for here, and it has been superceded by a protocol in [Wayland Protocols](https://gitlab.freedesktop.org/wayland/wayland-protocols), it is still advisable to keep the Frog Protocols variant implemented if possible, simply because it reduces the churn that end users might face while clients transition. 32 | 33 | **As a client**: You should never expect that any protocols in this repo are available. This rule will definitely get broken, but #IToldYouSo. 34 | - Definitely do not expect that for brand new protocols that might undergo rapid iterations. 35 | - Definitely do not expect that in your proprietary client. 36 | -------------------------------------------------------------------------------- /frog-protocols-uninstalled.pc.in: -------------------------------------------------------------------------------- 1 | pkgdatadir=@abs_top_srcdir@ 2 | 3 | Name: Frog Protocols 4 | Description: Frog Wayland protocol files (not installed) 5 | Version: @FROG_PROTOCOLS_VERSION@ 6 | -------------------------------------------------------------------------------- /frog-protocols.pc.in: -------------------------------------------------------------------------------- 1 | prefix=@prefix@ 2 | datarootdir=@datarootdir@ 3 | pkgdatadir=${pc_sysrootdir}${datarootdir}/@PACKAGE@ 4 | 5 | Name: Frog Protocols 6 | Description: Frog Wayland protocol files 7 | Version: @FROG_PROTOCOLS_VERSION@ 8 | -------------------------------------------------------------------------------- /frog-protocols/frog-color-management-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 5 | Copyright © 2023 Joshua Ashton for Valve Software 6 | Copyright © 2023 Xaver Hugl 7 | 8 | Permission is hereby granted, free of charge, to any person obtaining a 9 | copy of this software and associated documentation files (the "Software"), 10 | to deal in the Software without restriction, including without limitation 11 | the rights to use, copy, modify, merge, publish, distribute, sublicense, 12 | and/or sell copies of the Software, and to permit persons to whom the 13 | Software is furnished to do so, subject to the following conditions: 14 | 15 | The above copyright notice and this permission notice (including the next 16 | paragraph) shall be included in all copies or substantial portions of the 17 | Software. 18 | 19 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 22 | THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 | DEALINGS IN THE SOFTWARE. 26 | 27 | 28 | 29 | The aim of this color management extension is to get HDR games working quickly, 30 | and have an easy way to test implementations in the wild before the upstream 31 | protocol is ready to be merged. 32 | For that purpose it's intentionally limited and cut down and does not serve 33 | all uses cases. 34 | 35 | 36 | 37 | 38 | The color management factory singleton creates color managed surface objects. 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 49 | 51 | 52 | 53 | 54 | 55 | 56 | Interface for changing surface color management and HDR state. 57 | 58 | An implementation must: support every part of the version 59 | of the frog_color_managed_surface interface it exposes. 60 | Including all known enums associated with a given version. 61 | 62 | 63 | 64 | 65 | Destroying the color managed surface resets all known color 66 | state for the surface back to 'undefined' implementation-specific 67 | values. 68 | 69 | 70 | 71 | 72 | 73 | Extended information on the transfer functions described 74 | here can be found in the Khronos Data Format specification: 75 | 76 | https://registry.khronos.org/DataFormat/specs/1.3/dataformat.1.3.html 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | Extended information on render intents described 105 | here can be found in ICC.1:2022: 106 | 107 | https://www.color.org/specification/ICC.1-2022-05.pdf 108 | 109 | 110 | 111 | 112 | 113 | 114 | NOTE: On a surface with "perceptual" (default) render intent, handling of the container's color volume 115 | is implementation-specific, and may differ between different transfer functions it is paired with: 116 | ie. sRGB + 709 rendering may have it's primaries widened to more of the available display's gamut 117 | to be be more pleasing for the viewer. 118 | Compared to scRGB Linear + 709 being treated faithfully as 709 119 | (including utilizing negatives out of the 709 gamut triangle) 120 | 121 | 122 | 123 | 124 | 125 | 126 | Forwards HDR metadata from the client to the compositor. 127 | 128 | HDR Metadata Infoframe as per CTA 861.G spec. 129 | 130 | Usage of this HDR metadata is implementation specific and 131 | outside of the scope of this protocol. 132 | 133 | 134 | 135 | Mastering Red Color Primary X Coordinate of the Data. 136 | 137 | Coded as unsigned 16-bit values in units of 138 | 0.00002, where 0x0000 represents zero and 0xC350 139 | represents 1.0000. 140 | 141 | 142 | 143 | 144 | Mastering Red Color Primary Y Coordinate of the Data. 145 | 146 | Coded as unsigned 16-bit values in units of 147 | 0.00002, where 0x0000 represents zero and 0xC350 148 | represents 1.0000. 149 | 150 | 151 | 152 | 153 | Mastering Green Color Primary X Coordinate of the Data. 154 | 155 | Coded as unsigned 16-bit values in units of 156 | 0.00002, where 0x0000 represents zero and 0xC350 157 | represents 1.0000. 158 | 159 | 160 | 161 | 162 | Mastering Green Color Primary Y Coordinate of the Data. 163 | 164 | Coded as unsigned 16-bit values in units of 165 | 0.00002, where 0x0000 represents zero and 0xC350 166 | represents 1.0000. 167 | 168 | 169 | 170 | 171 | Mastering Blue Color Primary X Coordinate of the Data. 172 | 173 | Coded as unsigned 16-bit values in units of 174 | 0.00002, where 0x0000 represents zero and 0xC350 175 | represents 1.0000. 176 | 177 | 178 | 179 | 180 | Mastering Blue Color Primary Y Coordinate of the Data. 181 | 182 | Coded as unsigned 16-bit values in units of 183 | 0.00002, where 0x0000 represents zero and 0xC350 184 | represents 1.0000. 185 | 186 | 187 | 188 | 189 | Mastering White Point X Coordinate of the Data. 190 | 191 | These are coded as unsigned 16-bit values in units of 192 | 0.00002, where 0x0000 represents zero and 0xC350 193 | represents 1.0000. 194 | 195 | 196 | 197 | 198 | Mastering White Point Y Coordinate of the Data. 199 | 200 | These are coded as unsigned 16-bit values in units of 201 | 0.00002, where 0x0000 represents zero and 0xC350 202 | represents 1.0000. 203 | 204 | 205 | 206 | 207 | Max Mastering Display Luminance. 208 | This value is coded as an unsigned 16-bit value in units of 1 cd/m2, 209 | where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2. 210 | 211 | 212 | 213 | 214 | Min Mastering Display Luminance. 215 | This value is coded as an unsigned 16-bit value in units of 216 | 0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF 217 | represents 6.5535 cd/m2. 218 | 219 | 220 | 221 | 222 | Max Content Light Level. 223 | This value is coded as an unsigned 16-bit value in units of 1 cd/m2, 224 | where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2. 225 | 226 | 227 | 228 | 229 | Max Frame Average Light Level. 230 | This value is coded as an unsigned 16-bit value in units of 1 cd/m2, 231 | where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2. 232 | 233 | 234 | 235 | 236 | 237 | 238 | Current preferred metadata for a surface. 239 | The application should use this information to tone-map its buffers 240 | to this target before committing. 241 | 242 | This metadata does not necessarily correspond to any physical output, but 243 | rather what the compositor thinks would be best for a given surface. 244 | 245 | 246 | 247 | Specifies a known transfer function that corresponds to the 248 | output the surface is targeting. 249 | 250 | 251 | 252 | 253 | Output Red Color Primary X Coordinate of the Data. 254 | 255 | Coded as unsigned 16-bit values in units of 256 | 0.00002, where 0x0000 represents zero and 0xC350 257 | represents 1.0000. 258 | 259 | 260 | 261 | 262 | Output Red Color Primary Y Coordinate of the Data. 263 | 264 | Coded as unsigned 16-bit values in units of 265 | 0.00002, where 0x0000 represents zero and 0xC350 266 | represents 1.0000. 267 | 268 | 269 | 270 | 271 | Output Green Color Primary X Coordinate of the Data. 272 | 273 | Coded as unsigned 16-bit values in units of 274 | 0.00002, where 0x0000 represents zero and 0xC350 275 | represents 1.0000. 276 | 277 | 278 | 279 | 280 | Output Green Color Primary Y Coordinate of the Data. 281 | 282 | Coded as unsigned 16-bit values in units of 283 | 0.00002, where 0x0000 represents zero and 0xC350 284 | represents 1.0000. 285 | 286 | 287 | 288 | 289 | Output Blue Color Primary X Coordinate of the Data. 290 | 291 | Coded as unsigned 16-bit values in units of 292 | 0.00002, where 0x0000 represents zero and 0xC350 293 | represents 1.0000. 294 | 295 | 296 | 297 | 298 | Output Blue Color Primary Y Coordinate of the Data. 299 | 300 | Coded as unsigned 16-bit values in units of 301 | 0.00002, where 0x0000 represents zero and 0xC350 302 | represents 1.0000. 303 | 304 | 305 | 306 | 307 | Output White Point X Coordinate of the Data. 308 | 309 | These are coded as unsigned 16-bit values in units of 310 | 0.00002, where 0x0000 represents zero and 0xC350 311 | represents 1.0000. 312 | 313 | 314 | 315 | 316 | Output White Point Y Coordinate of the Data. 317 | 318 | These are coded as unsigned 16-bit values in units of 319 | 0.00002, where 0x0000 represents zero and 0xC350 320 | represents 1.0000. 321 | 322 | 323 | 324 | 325 | Max Output Luminance 326 | The max luminance in nits that the output is capable of rendering in small areas. 327 | Content should: not exceed this value to avoid clipping. 328 | 329 | This value is coded as an unsigned 16-bit value in units of 1 cd/m2, 330 | where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2. 331 | 332 | 333 | 334 | 335 | Min Output Luminance 336 | The min luminance that the output is capable of rendering. 337 | Content should: not exceed this value to avoid clipping. 338 | 339 | This value is coded as an unsigned 16-bit value in units of 340 | 0.0001 cd/m2, where 0x0001 represents 0.0001 cd/m2 and 0xFFFF 341 | represents 6.5535 cd/m2. 342 | 343 | 344 | 345 | 346 | Max Full Frame Luminance 347 | The max luminance in nits that the output is capable of rendering for the 348 | full frame sustained. 349 | 350 | This value is coded as an unsigned 16-bit value in units of 1 cd/m2, 351 | where 0x0001 represents 1 cd/m2 and 0xFFFF represents 65535 cd/m2. 352 | 353 | 354 | 355 | 356 | 357 | -------------------------------------------------------------------------------- /frog-protocols/frog-fifo-v1.xml: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | Copyright © 2023 Valve Corporation 5 | 6 | Permission is hereby granted, free of charge, to any person obtaining a 7 | copy of this software and associated documentation files (the "Software"), 8 | to deal in the Software without restriction, including without limitation 9 | the rights to use, copy, modify, merge, publish, distribute, sublicense, 10 | and/or sell copies of the Software, and to permit persons to whom the 11 | Software is furnished to do so, subject to the following conditions: 12 | 13 | The above copyright notice and this permission notice (including the next 14 | paragraph) shall be included in all copies or substantial portions of the 15 | Software. 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 20 | THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 22 | FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 23 | DEALINGS IN THE SOFTWARE. 24 | 25 | 26 | 27 | 28 | When a Wayland compositor considers applying a content update, 29 | it must ensure all the update's readiness constraints (fences, etc) 30 | are met. 31 | 32 | This protocol provides a way to use the completion of a display refresh 33 | cycle as an additional readiness constraint. 34 | 35 | Warning! The protocol described in this file is currently in the testing 36 | phase. Backward compatible changes may be added together with the 37 | corresponding interface version bump. Backward incompatible changes can 38 | only be done by creating a new major version of the extension. 39 | 40 | 41 | 42 | 43 | These fatal protocol errors may be emitted in response to 44 | illegal requests. 45 | 46 | 48 | 49 | 50 | 51 | 52 | Informs the server that the client will no longer be using 53 | this protocol object. Existing objects created by this object 54 | are not affected. 55 | 56 | 57 | 58 | 59 | 60 | Establish a fifo object for a surface that may be used to add 61 | display refresh constraints to content updates. 62 | 63 | Only one such object may exist for a surface and attempting 64 | to create more than one will result in a fifo_manager_already_exists 65 | protocol error. If a surface is acted on by multiple software 66 | components, general best practice is that only the component 67 | performing wl_surface.attach operations should use this protocol. 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | A fifo object for a surface that may be used to add 77 | display refresh constraints to content updates. 78 | 79 | 80 | 81 | 82 | These fatal protocol errors may be emitted in response to 83 | illegal requests. 84 | 85 | 87 | 88 | 89 | 90 | 91 | When the content update containing the "set_barrier" is applied, 92 | it sets a "fifo_barrier" condition on the surface associated with 93 | the fifo object. The condition is cleared immediately after the 94 | following latching deadline for non-tearing presentation. 95 | The condition needs to be cleared soon enough so that forward 96 | progress for the application is guaranteed. The exact rate at which 97 | that happens is implementation defined. 98 | 99 | To wait for this condition to clear, use the "wait_barrier" request. 100 | 101 | "set_barrier" is double-buffered state, see wl_surface.commit. 102 | 103 | Requesting set_barrier after the fifo object's surface is 104 | destroyed will generate a "surface_destroyed" error. 105 | 106 | 107 | 108 | 109 | 110 | Indicate that this content update is not ready while a 111 | "fifo_barrier" condition is present on the surface. 112 | 113 | This means that when the content update containing "set_barrier" 114 | was made active at a latching deadline, it will be active for 115 | at least one refresh cycle. A content update which is allowed to 116 | tear might become active after a latching deadline if no content 117 | update became active at the deadline. 118 | 119 | "wait_barrier" is double-buffered state, see wl_surface.commit. 120 | 121 | Requesting "wait_barrier" after the fifo object's surface is 122 | destroyed will generate a "surface_destroyed" error. 123 | 124 | 125 | 126 | 127 | 128 | Informs the server that the client will no longer be using 129 | this protocol object. 130 | 131 | Surface state changes previously made by this protocol are 132 | unaffected by this object's destruction. 133 | 134 | 135 | 136 | 137 | -------------------------------------------------------------------------------- /meson.build: -------------------------------------------------------------------------------- 1 | project('frog-protocols', 2 | 'c', 3 | version: '0.01', 4 | meson_version: '>= 0.55.0', 5 | license: 'MIT/Expat', 6 | ) 7 | 8 | frog_protocols_version = meson.project_version() 9 | 10 | fs = import('fs') 11 | 12 | frog_protocols = { 13 | 'frog-color-management': ['v1'], 14 | 'frog-fifo': ['v1'], 15 | } 16 | 17 | protocol_files = [] 18 | 19 | foreach name, versions : frog_protocols 20 | foreach version : versions 21 | if version == '' 22 | protocol_files += ['frog-protocols/@0@.xml'.format(name)] 23 | else 24 | protocol_files += ['frog-protocols/@0@-@1@.xml'.format(name, version)] 25 | endif 26 | endforeach 27 | endforeach 28 | 29 | foreach protocol_file : protocol_files 30 | protocol_install_dir = fs.parent(join_paths( 31 | get_option('datadir'), 32 | protocol_file, 33 | )) 34 | install_data( 35 | protocol_file, 36 | install_dir: protocol_install_dir, 37 | ) 38 | endforeach 39 | 40 | frog_protocols_srcdir = meson.current_source_dir() 41 | 42 | pkgconfig_configuration = configuration_data() 43 | pkgconfig_configuration.set('prefix', get_option('prefix')) 44 | pkgconfig_configuration.set('datarootdir', '${prefix}/@0@'.format(get_option('datadir'))) 45 | pkgconfig_configuration.set('abs_top_srcdir', frog_protocols_srcdir) 46 | pkgconfig_configuration.set('PACKAGE', 'frog-protocols') 47 | pkgconfig_configuration.set('FROG_PROTOCOLS_VERSION', frog_protocols_version) 48 | 49 | pkg_install_dir = join_paths(get_option('datadir'), 'pkgconfig') 50 | configure_file( 51 | input: 'frog-protocols.pc.in', 52 | output: 'frog-protocols.pc', 53 | configuration: pkgconfig_configuration, 54 | install_dir: pkg_install_dir, 55 | ) 56 | 57 | configure_file( 58 | input: 'frog-protocols-uninstalled.pc.in', 59 | output: 'frog-protocols-uninstalled.pc', 60 | configuration: pkgconfig_configuration, 61 | ) 62 | 63 | frog_protocols = declare_dependency( 64 | variables: { 65 | 'pkgdatadir': frog_protocols_srcdir, 66 | }, 67 | ) 68 | 69 | meson.override_dependency('frog-protocols', frog_protocols) 70 | --------------------------------------------------------------------------------