third_party: Revise version 3 of remote shell protocol

third_party/wayland-protocols/unstable/remote-shell/remote-shell-unstable-v1.xml

 <?xml version="1.0" encoding="UTF-8"?>
 <protocol name="remote_shell_unstable_v1">
 
   <copyright>
     Copyright 2016 The Chromium Authors.
 
     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,
@@ skipping 20 matching lines @@
     Warning! The protocol described in this file is experimental and backward
     incompatible changes may be made. Backward compatible changes may be added
     together with the corresponding interface version bump. Backward
     incompatible changes are done by bumping the version number in the protocol
     and interface names and resetting the interface version. Once the protocol
     is to be declared stable, the 'z' prefix and the version number in the
     protocol and interface names are removed and the interface version number is
     reset.
   </description>
 
-  <interface name="zcr_remote_shell_v1" version="2">
+  <interface name="zcr_remote_shell_v1" version="3">
     <description summary="remote_shell">
       The global interface that allows clients to turn a wl_surface into a
       "real window" which is remotely managed but can be stacked, activated
       and made fullscreen by the user.
     </description>
 
     <enum name="container">
       <description summary="containers for remote surfaces">
         Determine how a remote surface should be stacked relative to other
         shell surfaces.
@@ skipping 67 matching lines @@
         Creates a notification_surface for the given surface, gives it the
         notification_surface role and associated it with a notification id.
       </description>
       <arg name="id" type="new_id" interface="zcr_notification_surface_v1"/>
       <arg name="surface" type="object" interface="wl_surface"/>
       <arg name="notification_id" type="string" />
     </request>
 
     <event name="configuration_changed">
       <description summary="suggests a re-configuration of remote shell">
-        Suggests a re-configuration of remote shell.
+        Deprecated. Suggests a re-configuration of remote shell.
       </description>
       <arg name="width" type="int"/>
       <arg name="height" type="int"/>
       <arg name="transform" type="int"/>
       <arg name="scale_factor" type="fixed"/>
       <arg name="work_area_inset_left" type="int"/>
       <arg name="work_area_inset_top" type="int"/>
       <arg name="work_area_inset_right" type="int"/>
       <arg name="work_area_inset_bottom" type="int"/>
       <arg name="layout_mode" type="uint"/>
     </event>
+
+    <!-- Version 3 additions -->
+
+    <event name="workspace" version="3">
+      <description summary="area of remote shell">
+        Defines an area of the remote shell used for layout.
+      </description>
+      <arg name="id" type="uint"/>
+      <arg name="x" type="int"/>
+      <arg name="y" type="int"/>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+      <arg name="inset_left" type="int"/>
+      <arg name="inset_top" type="int"/>
+      <arg name="inset_right" type="int"/>
+      <arg name="inset_bottom" type="int"/>
+    </event>

[reveman, 2016/10/26 15:13:44]

I understand that inset is the workspace but what is x, y, width, height? does
wl_output::geometry already provide that information?

how does the client know that it received all workspace events? wl_output::done?


fyi, I'd like to make remote-shell more appropriately layered on top of existing
extensions in the near future. aura_shell extends xdg_shell with minimal changes
and aura_output extends wl_output, etc.

[Dominik Laskowski, 2016/10/26 19:53:10]

Bounds of the workspace in virtual coordinates, i.e. within the display defined
by the subsequent "configure" event. wl_output doesn't map very well to our
concept of virtual displays. wl_output::geometry provides position (though in
compositor space, i.e. screen coordinates) and wl_output::mode provides
resolution. However, the other arguments are inapplicable, and workspaces also
require an ID and insets.

The "workspace" events are always terminated by a "configure" event.

Unless we migrate all window management to the server, I'm not sure how this
layering would work, because in certain cases the upstream interfaces are
incompatible with the hybrid window management.

[reveman, 2016/11/11 01:36:13]

Ok, makes sense.
Got it. A short comment about that in the event description would be nice.
aura_output extending wl_output doesn't make sense know that I better understand
the difference between wl_output and the workspace we need here. However,
remote_shell becoming an interface layered on top of xdg_shell is something we
want to do in the near future but no need to worry about that now.

+
+    <event name="configure" version="3">
+      <description summary="suggests configuration of remote shell">
+        Suggests a new configuration of the remote shell. Preceded by a series
+        of "workspace" events.
+      </description>
+      <arg name="width" type="int"/>
+      <arg name="height" type="int"/>
+      <arg name="transform" type="int"/>
+      <arg name="scale_factor" type="fixed"/>
+      <arg name="layout_mode" type="uint"/>
+    </event>
   </interface>
 
   <interface name="zcr_remote_surface_v1" version="2">
     <description summary="A desktop window">
       An interface that may be implemented by a wl_surface, for
       implementations that provide a desktop-style user interface
       and allows for remotely managed windows.
 
       It provides requests to treat surfaces like windows, allowing to set
       properties like app id and geometry.
@@ skipping 256 matching lines @@
     </description>
 
     <request name="destroy" type="destructor">
       <description summary="Destroy the notification_surface">
         Unmap and destroy the notification surface.
       </description>
     </request>
   </interface>
 
 </protocol>