Merge branch 'surface-invalidation' into 'main'

surface-invalidation-v1: new protocol

See merge request wayland/wayland-protocols!180

meson.build

@@ -67,6 +67,7 @@ staging_protocols = {
 	'pointer-warp': ['v1'],
 	'security-context': ['v1'],
 	'single-pixel-buffer': ['v1'],
+	'surface-invalidation': ['v1'],
 	'tearing-control': ['v1'],
 	'xdg-activation': ['v1'],
 	'xdg-dialog': ['v1'],

staging/surface-invalidation/README

@@ -0,0 +1,4 @@
+Surface invalidation protocol
+
+Maintainers:
+Simon Ser <contact@emersion.fr>

staging/surface-invalidation/surface-invalidation-v1.xml

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<protocol name="surface_invalidation_v1">
+  <copyright>
+    Copyright © 2022 Simon Ser
+
+    Permission is hereby granted, free of charge, to any person obtaining a
+    copy of this software and associated documentation files (the "Software"),
+    to deal in the Software without restriction, including without limitation
+    the rights to use, copy, modify, merge, publish, distribute, sublicense,
+    and/or sell copies of the Software, and to permit persons to whom the
+    Software is furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice (including the next
+    paragraph) shall be included in all copies or substantial portions of the
+    Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL
+    THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+    DEALINGS IN THE SOFTWARE.
+  </copyright>
+
+  <description summary="surface invalidation">
+    This protocol allows compositors to invalidate surfaces. Clients are
+    required to submit a new buffer after the compositor invalidates a surface.
+    Compositors might take advantage of this protocol to recover from GPU
+    resets.
+
+    Warning! The protocol described in this file is currently in the testing
+    phase. Backward compatible changes may be added together with the
+    corresponding interface version bump. Backward incompatible changes can
+    only be done by creating a new major version of the extension.
+  </description>
+
+  <interface name="wp_surface_invalidation_manager_v1" version="1">
+    <description summary="surface invalidation manager">
+      A factory interface to create surface invalidation objects.
+    </description>
+
+    <enum name="error">
+      <entry name="already_constructed" value="1"
+        summary="a surface invalidation object has already been constructed"/>
+    </enum>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the manager">
+        Destroy the wp_surface_invalidation_manager_v1 object.
+
+        The child objects created via this interface are unaffected.
+      </description>
+    </request>
+
+    <request name="get_surface_invalidation">
+      <description summary="extend surface interface for invalidation">
+        Create a wl_surface extension for invalidation.
+
+        Clients must create at most one wp_surface_invalidation_v1 per
+        wl_surface object, otherwise the already_constructed protocol
+        error is sent.
+      </description>
+      <arg name="id" type="new_id" interface="wp_surface_invalidation_v1"/>
+      <arg name="surface" type="object" interface="wl_surface"/>
+    </request>
+  </interface>
+
+  <interface name="wp_surface_invalidation_v1" version="1">
+    <description summary="surface invalidation">
+      An add-on interface for wl_surface to handle invalidation events.
+
+      Creating this object signals to the compositor that the client
+      supports invalidation events on this surface.
+    </description>
+
+    <enum name="error">
+      <entry name="unresponsive" value="1"
+        summary="client didn't ack an invalidated event in time"/>
+      <entry name="invalid_serial" value="2"
+        summary="client acked an invalid serial"/>
+    </enum>
+
+    <event name="invalidated">
+      <description summary="surface has been invalidated">
+        Sent by the compositor when the surface has been invalidated.
+
+        The client is required to handle the invalidated event by
+        attaching a new buffer on the surface, sending an ack request
+        with the same serial as the event, and then committing the
+        surface.
+
+        A compositor may raise an unresponsive protocol error to clients
+        that does not acknowledge an invalidation event in time. The
+        timeout used is up to the compositor.
+      </description>
+      <arg name="serial" type="uint" summary="invalidation serial"/>
+    </event>
+
+    <request name="ack">
+      <description summary="acknowledge surface invalidation">
+        Acknowledge a surface invalidation event.
+
+        This event must be paired with a request to attach a new buffer
+        on the surface, and needs to be followed by a surface commit to
+        be applied.
+
+        If the serial doesn't match a previous invalidated event, or if
+        the same serial is acked twice, the invalid_serial protocol
+        error is raised.
+      </description>
+      <arg name="serial" type="uint" summary="invalidation serial"/>
+    </request>
+
+    <request name="destroy" type="destructor">
+      <description summary="destroy the surface invalidation object">
+        Destroy the surface invalidation object.
+      </description>
+    </request>
+  </interface>
+</protocol>