[PATCH wayland v2] protocol: Add wl_surface.damage_buffer

Thu Nov 19 09:03:19 PST 2015

On 18/11/15 09:37 PM, Christopher Michael wrote:
> I am certainly not against these changes .. +1 for the effort ;)
> 
> However, I would like to know (and possible others would also), what
> does this mean for toolkits ?? Aside from bumping compositor and surface
> versions, what sort of changes (short version please) should we look at
> implementing to facilitate this ?? Is this going to be a separate
> surface request ?
> 
> What happens if we continue using "current implementation" ?? Please
> understand, I am all FOR these changes as it makes sense to have this
> work with EGL :) ..
> 
> I am more asking out of curiosity (wrt: what does this mean for "us" as
> toolkit developers)

Toolkits can continue to use whichever they want.  There's no need to
change any code.  We're not going to ditch the old damage request -
breaking every existing app is apparently unpopular.

Using damage_buffer in the toolkit can actually result in simpler client
side code though.  Unfortunately if you have to maintain compatibility
with compositors that don't have the new request you'll be stuck
maintaining the old path forever anyway.

I don't know if EFL uses viewports and buffer transforms and scaling
right now, I think it doesn't...  if you start using those you might
want to only support them when the compositor also supports
wl_surface_damage_buffer in order to simplify the client's damage
calculations.

I think right now EFL doesn't currently have any situations where damage
and damage_buffer would behave differently.

Enlightenment will probably want to support damage_buffer after it's
landed in wayland+weston in a form people are happy with - we can arm
wrestle off-list later to see who "gets to" write that. ;)

> Cheers,
> Chris
> 
> On 11/18/2015 05:17 PM, Derek Foreman wrote:
>> wl_surface.damage uses surface local co-ordinates.
>>
>> Buffer scale and buffer transforms came along, and EGL surfaces
>> have no understanding of them.
>>
>> Theoretically, clients pass damage rectangles - in Y-inverted surface
>> co-ordinates) to EGLSwapBuffersWithDamage, and the EGL implementation
>> passed them on to wayland.  However, for this to work the EGL
>> implementation must be able to flip those rectangles into the space
>> the compositor is expecting, but it's unable to do so because it
>> doesn't know the height of the transformed buffer.
>>
>> So, currently, EGLSwapBuffersWithDamage is unusable and EGLSwapBuffers
>> has to pass (0,0) - (INT32_MAX, INT32_MAX) damage to function.
>>
>> wl_surface.damage_buffer allows damage to be registered on a surface
>> in buffer co-ordinates, avoiding this problem.
>>
>> Credit where it's due, these ideas are not entirely my own:
>> Over a year ago the idea of changing damage co-ordinates to buffer
>> co-ordinates was suggested (by Jason Ekstrand), and it was at least
>> partially rejected and abandoned.  At the time it was also suggested
>> (by Pekka Paalanen) that adding a new wl_surface.damage_buffer request
>> was another option.
>>
>> This will eventually resolve:
>> https://bugs.freedesktop.org/show_bug.cgi?id=78190
>> by making the problem irrelevant.
>>
>> Signed-off-by: Derek Foreman <derekf at osg.samsung.com>
>> ---
>>
>> Differnces from v1:
>>   - Don't make such a big deal about GL in the request documentation
>>   - rename the request about 3 times, eventually settle on damage_buffer
>>   - don't say anything about mixing damage and damage_buffer
>>
>>   protocol/wayland.xml | 44 ++++++++++++++++++++++++++++++++++++++++++--
>>   1 file changed, 42 insertions(+), 2 deletions(-)
>>
>> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
>> index 9c22d45..7665307 100644
>> --- a/protocol/wayland.xml
>> +++ b/protocol/wayland.xml
>> @@ -176,7 +176,7 @@
>>       </event>
>>     </interface>
>>
>> -  <interface name="wl_compositor" version="3">
>> +  <interface name="wl_compositor" version="4">
>>       <description summary="the compositor singleton">
>>         A compositor.  This object is a singleton global.  The
>>         compositor is in charge of combining the contents of multiple
>> @@ -986,7 +986,7 @@
>>       </event>
>>     </interface>
>>
>> -  <interface name="wl_surface" version="3">
>> +  <interface name="wl_surface" version="4">
>>       <description summary="an onscreen surface">
>>         A surface is a rectangular area that is displayed on the screen.
>>         It has a location, size and pixel contents.
>> @@ -1111,6 +1111,10 @@
>>       wl_surface.commit assigns pending damage as the current damage,
>>       and clears pending damage. The server will clear the current
>>       damage as it repaints the surface.
>> +
>> +    Alternatively, damage can be posted with wl_surface.damage_buffer
>> +    which uses buffer co-ordinates instead of surface co-ordinates,
>> +    and is probably the preferred and intuitive way of doing this.
>>         </description>
>>
>>         <arg name="x" type="int"/>
>> @@ -1327,6 +1331,42 @@
>>         </description>
>>         <arg name="scale" type="int"/>
>>       </request>
>> +
>> +    <!-- Version 4 additions -->
>> +    <request name="damage_buffer" since="4">
>> +      <description summary="mark part of the surface damaged using
>> buffer co-ordinates">
>> +    This request is used to describe the regions where the pending
>> +    buffer is different from the current surface contents, and where
>> +    the surface therefore needs to be repainted. The pending buffer
>> +    must be set by wl_surface.attach before sending damage. The
>> +    compositor ignores the parts of the damage that fall outside of
>> +    the surface.
>> +
>> +    Damage is double-buffered state, see wl_surface.commit.
>> +
>> +    The damage rectangle is specified in buffer coordinates.
>> +
>> +    The initial value for pending damage is empty: no damage.
>> +    wl_surface.damage adds pending damage: the new pending damage
>> +    is the union of old pending damage and the given rectangle.
>> +
>> +    wl_surface.commit assigns pending damage as the current damage,
>> +    and clears pending damage. The server will clear the current
>> +    damage as it repaints the surface.
>> +
>> +    This request differs from wl_surface.damage in only one way - it
>> +    takes damage in buffer co-ordinates instead of surface local
>> +    co-ordinates.  While this generally is more intuitive than surface
>> +    co-ordinates, it is especially desirable when using wl_viewport
>> +    or when a drawing library (like EGL) is unaware of buffer scale
>> +    and buffer transform.
>> +      </description>
>> +
>> +      <arg name="x" type="int"/>
>> +      <arg name="y" type="int"/>
>> +      <arg name="width" type="int"/>
>> +      <arg name="height" type="int"/>
>> +    </request>
>>      </interface>
>>
>>     <interface name="wl_seat" version="5">
>>
> 
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel