[PATCH] documentation: clarify the need for wl_surface.damage

[Pekka Paalanen]

On Tue, 03 Oct 2017 18:02:35 +0200
Mahdi Khanalizadeh <mahdi at khanalizadeh.com> wrote:

> Hi,
> thanks for reviewing.
> 
> Am 03.10.2017 09:02:03 schrieb(en) Pekka Paalanen:
> > On Mon,  2 Oct 2017 17:39:56 +0200
> > Mahdi Khanalizadeh <mahdi at khanalizadeh.com> wrote:
> >   
> > > Add an explanation for wl_surface.attach why a wl_surface.damage    
> > request  
> > > is necessary. Explicitly declare it implementation defined    
> > behaviour if the  
> > > wl_surface.damage request is omitted to give the compositor some    
> > leeway  
> > > on how it handles attaches.
> > >
> > > Signed-off-by: Mahdi Khanalizadeh <mahdi at khanalizadeh.com>
> > > ---
> > >  protocol/wayland.xml | 5 +++++
> > >  1 file changed, 5 insertions(+)
> > >
> > > diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> > > index aabc7ae..6f6cc11 100644
> > > --- a/protocol/wayland.xml
> > > +++ b/protocol/wayland.xml
> > > @@ -1365,6 +1365,11 @@
> > >  	wl_buffer before receiving the wl_buffer.release event, the    
> > surface  
> > >  	contents become undefined immediately.
> > >
> > > +	Attaching a buffer should always be accompanied by a
> > > +	wl_surface.damage request to signal the compositor that the
> > > +	contents of the buffer have changed. Otherwise it is    
> > implementation  
> > > +	defined whether the wl_surface.attach request has any visible    
> > effect.
> > 
> > Hi,
> > 
> > thank you for the clarification, I assume this is as a response to our
> > IRC discussion.  
> Indeed.
> 
> > How about phrasing it: "Attaching a buffer should always be  
> > accompanied
> > by at least one wl_surface.damage request to signal the compositor
> > which parts of the surface contents are changed."?
> > 
> > - There can be multiple damage requests to build up a complex region.
> > - It's not about buffer contents, it is about surface contents.
> > - We don't want to imply that you must always give full surface-sized
> >   damage when the buffer is swapped.
> > 
> > However, most of the new paragraph are redundant with the first
> > paragraph for the damage request. Could you instead add one more
> > sentence to the first paragraph explaining that the compositor has no
> > obligation to use the new contents outside of the given damage?
> > 
> > There is also the request damage_buffer which is otherwise the same  
> > but
> > uses a different coordinate system.  

> Taking your suggestions into account, what’s your opinion on adding the  
> following
> sentence after the first paragraphs of damage and damage_buffer instead  
> of
> my original change?
> 
> “For this reason every wl_surface.attach request should always be
> accompanied by at least one wl_surface.damage or
> wl_surface.damage_buffer request to signal the compositor which
> parts of the surface contents have changed, because the compositor
> is not obliged to update any surface content that falls outside of the
> damaged area.”

Hi Mahdi,

as I just wrote in my reply to Jonas, there may actually be cases where
no damage is necessary and gave one example. I also think that is quite
verbose. Could you not easily realize from something like "A compositor
may but is not required to use or repaint areas outside of the given
damage" that if you change surface content, you really need damage to
make sure it goes through?

That would also underline another fact that people did not always
realize: the attached buffer must always be completely drawn by the
client. Drawing only the damage area is not sufficient, because the
compositor is allowed to sample more than the damage.

I know there is a need for a more verbose explanation on how the
protocol works, but the XML spec is not a good place for it. The XML
spec is a reference, not a guide with rationale. We are missing a
guide, and that would likely belong in the Wayland docbook in the
Wayland repository.


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