[PATCH wayland-protocols v2 0/5] Stabilize wl_scaler as wp_viewporter

[Pekka Paalanen]

On Tue, 19 Apr 2016 15:55:01 +0100
Daniel Stone <daniel at fooishbar.org> wrote:

> Hi,
> 
> On 19 April 2016 at 15:46, Yong Bakos <junk at humanoriented.com> wrote:
> > On Apr 19, 2016, at 7:23 AM, Pekka Paalanen <ppaalanen at gmail.com> wrote:  
> >> The final XML file is also verbatim at the end of this email to allow easy
> >> overall review.  
> 
> Thanks a lot for this, that helps hugely.
> 
> > v2 patches 1 - 4 look good and are
> > Reviewed-by: Yong Bakos <ybakos at humanoriented.com>
> >
> > I defer to Daniel/others regarding 5/5.  
> 
> Below nitpicks notwithstanding:
> Reviewed-by: Daniel Stone <daniels at collabora.com>

Hi,

very cool!

> >> <?xml version="1.0" encoding="UTF-8"?>
> >> <protocol name="viewporter">
> >>
> >>  <copyright>
> >>    Copyright © 2013-2014 Collabora, Ltd.  
> 
> -2016

Yeah, now there are enough changes to update that.

> >>  <interface name="wp_viewporter" version="1">
> >>    <description summary="surface cropping and scaling">
> >>      The global interface exposing surface cropping and scaling
> >>      capabilities is used to instantiate an interface extension for a  
> 
> 'interface extension'? Is that meant to be instance extension, or is
> it meaning an interface which extends the wl_surface? No problem
> either way.

Wow, that's an awkward sentence. The same wording is used for
wp_viewporter.get_viewport request.

The interface extension refers to a protocol object whose interface is
extending the interface of a particular wl_surface object.

It's easier to explain things using Weston's implementation as a
reference. A protocol object wl_surface is backed by a weston_surface
with one-to-one relationship. A protocol object wp_viewport is also
backed by the same weston_surface that backs the wl_surface it was
created for. A wp_viewport without the wl_surface (and so without
the weston_surface) is "dead" - it has no use.

This is a case of extending an existing interface wl_surface with
another interface wp_viewport. This happens on an object by object
basis.

Maybe Yong can come up with a nicer wording as a follow-up patch?

> >>  <interface name="wp_viewport" version="1">
> >>    <description summary="crop and scale interface to a wl_surface">
> >>      An additional interface to a wl_surface object, which allows the
> >>      client to specify the cropping and scaling of the surface
> >>      contents.
> >>
> >>      This interface works with two concepts: the source rectangle (src_x,
> >>      src_y, src_width, src_height), and the destination size (dst_width,
> >>      dst_height). The contents of the source rectangle are scaled to the
> >>      destination size, and content outside the source rectangle is culled.  
> 
> s/culled/ignored/ as culled implies a destructive operation. I know
> there's no way anyone particularly familiar with how Wayland works
> could read it to be destructive to the wl_buffer content, but might as
> well make it as accessible as possible. :)

Yup, that's better.

> >>      The x, y arguments of wl_surface.attach are applied as normal to
> >>      the surface. They indicate how many pixels to remove from the
> >>      surface size from the left and the top. In other words, they are
> >>      still in the surface-local coordinate system, just like dst_width
> >>      and dst_height are.  
> 
> In a similar spirit, s/pixels to remove from the surface size/pixels
> to translate the surface position by/.

That was a very deliberate wording to steer away from the notion that
you can move your window by abusing the x,y of wl_surface.attach.
"Removing from size" is probably a strange phrase indeed. I'll leave
that as is for now.

The important thing in this paragraph is explaining the coordinate
system used by the x,y which is not affected by the viewport. In that
sense, we could even remove the whole paragraph. Should we?

I have fixed the year and "culled" in my branch. I will send out the
final series once I have the Weston patches ready.
https://git.collabora.com/cgit/user/pq/wayland-protocols.git/log/?h=viewporter


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