[RFC PATCH v3] Add xdg-output protocol

Fri Jul 14 08:45:21 UTC 2017

On Thu, Jul 06, 2017 at 04:01:25PM +0200, Olivier Fourdan wrote:
> This protocol aims at describing outputs in way which is more in line
> with the concept of an output on desktop oriented systems.
> 
> Some information are more specific to the concept of an output for a
> desktop oriented system and may not make sense in other applications,
> such as IVI systems for example.
> 
> The goal is to gradually move the desktop specific concepts out of the
> core wl_output protocol.
> 
> For now it just features the position and logical size which describe
> the output position and size in the global compositor space.
> 
> Signed-off-by: Olivier Fourdan <ofourdan at redhat.com>

This one is 

Reviewed-by: Jonas Ådahl <jadahl at gmail.com>

but I'll wait with landing to see whether a consensus can be reached in
the E-mail thread.

Jonas

> ---
>  v2: use "destroy" instead of "release" for destructor
>  v3: adopt a more conventional global factory interface with a 
>      get_xdg_output() method, add some clarification and example.
> 
>  Makefile.am                                    |   1 +
>  unstable/xdg-output/README                     |   4 +
>  unstable/xdg-output/xdg-output-unstable-v1.xml | 160 +++++++++++++++++++++++++
>  3 files changed, 165 insertions(+)
>  create mode 100644 unstable/xdg-output/README
>  create mode 100644 unstable/xdg-output/xdg-output-unstable-v1.xml
> 
> diff --git a/Makefile.am b/Makefile.am
> index e693afa..6c696aa 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -12,6 +12,7 @@ unstable_protocols =								\
>  	unstable/tablet/tablet-unstable-v2.xml			                \
>  	unstable/xdg-foreign/xdg-foreign-unstable-v1.xml			\
>  	unstable/idle-inhibit/idle-inhibit-unstable-v1.xml			\
> +	unstable/xdg-output/xdg-output-unstable-v1.xml				\
>  	$(NULL)
>  
>  stable_protocols =								\
> diff --git a/unstable/xdg-output/README b/unstable/xdg-output/README
> new file mode 100644
> index 0000000..e42b711
> --- /dev/null
> +++ b/unstable/xdg-output/README
> @@ -0,0 +1,4 @@
> +xdg_output protocol
> +
> +Maintainers:
> +Olivier Fourdan <ofourdan at redhat.com>
> diff --git a/unstable/xdg-output/xdg-output-unstable-v1.xml b/unstable/xdg-output/xdg-output-unstable-v1.xml
> new file mode 100644
> index 0000000..74b5762
> --- /dev/null
> +++ b/unstable/xdg-output/xdg-output-unstable-v1.xml
> @@ -0,0 +1,160 @@
> +<?xml version="1.0" encoding="UTF-8"?>
> +<protocol name="xdg_output_unstable_v1">
> +
> +  <copyright>
> +    Copyright © 2017 Red Hat Inc.
> +
> +    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="Protocol to describe output regions">
> +    This protocol aims at describing outputs in a way which is more in line
> +    with the concept of an output on desktop oriented systems.
> +
> +    Some information are more specific to the concept of an output for
> +    a desktop oriented system and may not make sense in other applications,
> +    such as IVI systems for example.
> +
> +    Typically, the global compositor space on a desktop system is made of
> +    a contiguous or overlapping set of rectangular regions.
> +
> +    Some of the information provided in this protocol might be identical
> +    to their counterparts already available from wl_output, in which case
> +    the information provided by this protocol should be preferred to their
> +    equivalent in wl_output. The goal is to move the desktop specific
> +    concepts (such as output location within the global compositor space,
> +    the connector name and types, etc.) out of the core wl_output protocol.
> +
> +    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="zxdg_output_manager" version="1">
> +    <description summary="manage xdg_output objects">
> +      A global factory interface for xdg_output objects.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the xdg_output_manager object">
> +	Using this request a client can tell the server that it is not
> +	going to use the xdg_output_manager object anymore.
> +      </description>
> +    </request>
> +
> +    <request name="get_xdg_output">
> +      <description summary="create an xdg output from a wl_output">
> +	This creates a new xdg_output object for the given wl_output.
> +      </description>
> +      <arg name="id" type="new_id" interface="zxdg_output"/>
> +      <arg name="output" type="object" interface="wl_output"/>
> +    </request>
> +  </interface>
> +
> +  <interface name="zxdg_output" version="1">
> +    <description summary="compositor logical output region">
> +      An xdg_output describes part of the compositor geometry.
> +
> +      This typically corresponds to a monitor that displays part of the
> +      compositor space.
> +    </description>
> +
> +    <request name="destroy" type="destructor">
> +      <description summary="destroy the xdg_output object">
> +	Using this request a client can tell the server that it is not
> +	going to use the xdg_output object anymore.
> +      </description>
> +    </request>
> +
> +    <event name="logical_position">
> +      <description summary="position of the output within the global compositor space">
> +	The position event describes the location of the wl_output within
> +	the global compositor space.
> +
> +	The logical_position event is sent after creating an xdg_output
> +	(see xdg_output_manager.get_xdg_output) and whenever the location
> +	of the output changes within the global compositor space.
> +      </description>
> +      <arg name="x" type="int"
> +	   summary="x position within the global compositor space"/>
> +      <arg name="y" type="int"
> +	   summary="y position within the global compositor space"/>
> +    </event>
> +
> +    <event name="logical_size">
> +      <description summary="size of the output in the global compositor space">
> +	The logical_size event describes the size of the output in the
> +	global compositor space.
> +
> +	For example, a surface without any buffer scale, transformation
> +	nor rotation set, with the size matching the logical_size will
> +	have the same size as the corresponding output when displayed.
> +
> +	Most regular Wayland clients should not pay attention to the
> +	logical size and would rather rely on xdg_shell interfaces.
> +
> +	Some clients such as Xwayland, however, need this to configure
> +	their surfaces in the global compositor space as the compositor
> +	may apply a different scale from what is advertised by the output
> +	scaling property (to achieve fractional scaling, for example).
> +
> +	For example, for a wl_output mode 3840×2160 and a scale factor 2:
> +
> +	- A compositor not scaling the surface buffers will advertise a
> +	  logical size of 3840×2160,
> +
> +	- A compositor automatically scaling the surface buffers will
> +	  advertise a logical size of 1920×1080,
> +
> +	- A compositor using a fractional scale of 1.5 will advertise a
> +	  logical size to 2560×1620.
> +
> +	The logical_size event is sent after creating an xdg_output
> +	(see xdg_output_manager.get_xdg_output) and whenever the logical
> +	size of the output changes, either as a result of a change in the
> +	applied scale or because of a change in the corresponding output
> +	mode(see wl_output.mode) or transform (see wl_output.transform).
> +      </description>
> +      <arg name="width" type="int"
> +	   summary="width of the mode in global compositor space"/>
> +      <arg name="height" type="int"
> +	   summary="height of the mode in global compositor space"/>
> +    </event>
> +
> +    <event name="done">
> +      <description summary="all information about the output have been sent">
> +	This event is sent after all other properties of an xdg_output
> +	have been sent.
> +
> +	This allows changes to the xdg_output properties to be seen as
> +	atomic, even if they happen via multiple events.
> +      </description>
> +    </event>
> +
> +  </interface>
> +</protocol>
> +
> -- 
> 2.9.4
> 