[PATCH wayland] protocol: Clarify the meaning of NULL buffer attachment

[Pekka Paalanen]

On Mon, 13 Feb 2017 12:06:24 -0600
Derek Foreman <derekf at osg.samsung.com> wrote:

> This documents what has apparently been the case for ages - attaching a NULL
> buffer does *not* always remove the surface content, rather it has behaviour
> determined by the surface role (which may be documented elsewhere).
> 
> Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
> ---
>  protocol/wayland.xml | 13 +++++++++++--
>  1 file changed, 11 insertions(+), 2 deletions(-)
> 
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 29b63be..d7f7690 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -1359,8 +1359,17 @@
>  	wl_buffer before receiving the wl_buffer.release event, the surface
>  	contents become undefined immediately.
>  
> -	If wl_surface.attach is sent with a NULL wl_buffer, the
> -	following wl_surface.commit will remove the surface content.
> +	If wl_surface.attach is sent with a NULL wl_buffer, the result is
> +	determined by the surface role. For the result of attaching a NULL
> +	wl_buffer to a surface with a cursor role, see the documentation for
> +	wl_pointer.set_cursor.

Hi,

either list all the roles defined in wayland.xml or none. I'd lean on
none to reduce duplication.

> +
> +	The result of attaching a NULL buffer to a shell surface should be
> +	defined by the shell protocol specification.  As the result may be
> +	a posted error and a client disconnect, developers should be careful
> +	to read the appropriate protocol specification.  Attaching a NULL
> +	buffer to a wl_shell surface removes the surface content, but this
> +	behavior is not specified for all shell protocols.
>        </description>
>        <arg name="buffer" type="object" interface="wl_buffer" allow-null="true"
>  	   summary="buffer of surface contents"/>

Not sure shells should be mentioned explicitly either. If it's
role-specific, it's role-specific. Period.

We do need to check that all roles actually do specify the behaviour.

My suggestion would have been to keep the existing wording and add
"Surface roles may specify additional behaviour or errors for attaching
or committing buffers."

That one is not limited to NULL buffers even. E.g. we have the dmabuf
protocol going to have the create_immediate request which potentially
creates an invalid wl_buffer, and it specifies (or rather deliberately
says it's not specified by the protocol) what happens if you attach and
commit it.

The one thing that will always happen regardless of the role, IMO, is
that the surface contents will get removed. Whether that also leads to a
fatal error or something else is outside the wl_surface spec.


Thanks,
pq
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 801 bytes
Desc: OpenPGP digital signature
URL: <https://lists.freedesktop.org/archives/wayland-devel/attachments/20170214/3224eb87/attachment.sig>