[PATCH wayland-protocols v3 1/5] stable: add viewporter draft

[Pekka Paalanen]

On Thu, 28 Apr 2016 13:26:33 -0500
Derek Foreman <derekf at osg.samsung.com> wrote:

> On 26/04/16 07:50 AM, Pekka Paalanen wrote:
> > From: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > 
> > This XML file has been copied verbatim from Weston 1.10.0 release,
> > protocol/scaler.xml.
> > 
> > The interfaces still need renaming according to wayland-protocols
> > policy. Also a redundant request needs to be removed. These will be done
> > in a follow-up patch to clearly show the changes.
> > 
> > Signed-off-by: Pekka Paalanen <pekka.paalanen at collabora.co.uk>
> > Reviewed-by: Yong Bakos <ybakos at humanoriented.com>
> > Reviewed-by: Daniel Stone <daniels at collabora.com>
> > ---
> >  stable/viewporter/README         |   7 ++
> >  stable/viewporter/viewporter.xml | 208 +++++++++++++++++++++++++++++++++++++++
> >  2 files changed, 215 insertions(+)
> >  create mode 100644 stable/viewporter/README
> >  create mode 100644 stable/viewporter/viewporter.xml

> > +  <interface name="wl_viewport" version="2">
> > +    <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 allows to define the source rectangle (src_x,
> > +      src_y, src_width, src_height) from where to take the wl_buffer
> > +      contents, and scale that to destination size (dst_width,
> > +      dst_height). This state is double-buffered, and is applied on the
> > +      next wl_surface.commit.
> > +
> > +      The two parts of crop and scale state are independent: the source
> > +      rectangle, and the destination size. Initially both are unset, that
> > +      is, no scaling is applied. The whole of the current wl_buffer is
> > +      used as the source, and the surface size is as defined in
> > +      wl_surface.attach.
> > +
> > +      If the destination size is set, it causes the surface size to become
> > +      dst_width, dst_height. The source (rectangle) is scaled to exactly
> > +      this size. This overrides whatever the attached wl_buffer size is,
> > +      unless the wl_buffer is NULL. If the wl_buffer is NULL, the surface
> > +      has no content and therefore no size. Otherwise, the size is always
> > +      at least 1x1 in surface coordinates.
> > +
> > +      If the source rectangle is set, it defines what area of the
> > +      wl_buffer is taken as the source. If the source rectangle is set and
> > +      the destination size is not set, the surface size becomes the source
> > +      rectangle size rounded up to the nearest integer. If the source size
> > +      is already exactly integers, this results in cropping without scaling.
> > +
> > +      The coordinate transformations from buffer pixel coordinates up to
> > +      the surface-local coordinates happen in the following order:
> > +        1. buffer_transform (wl_surface.set_buffer_transform)
> > +        2. buffer_scale (wl_surface.set_buffer_scale)
> > +        3. crop and scale (wl_viewport.set*)
> > +      This means, that the source rectangle coordinates of crop and scale
> > +      are given in the coordinates after the buffer transform and scale,
> > +      i.e. in the coordinates that would be the surface-local coordinates
> > +      if the crop and scale was not applied.
> > +
> > +      If the source rectangle is partially or completely outside of the
> > +      wl_buffer, then the surface contents are undefined (not void), and
> > +      the surface size is still dst_width, dst_height.
> > +
> > +      The x, y arguments of wl_surface.attach are applied as normal to  
> 
> I'm a little uncomfortable with "applied as normal to".  In geometry,
> when something is normal to a surface it's perpendicular to it, but I
> think here we're trying to say x and y are in surface co-ordinates?

Yeah, but there might be some confusion whether that is measured before
or after applying the new wl_buffer and/or viewport state. The doc in
wl_surface.attach tries to explain it, and I'd rather not duplicate it
here.

A slightly poor choice of words, yes. Can be fixed later perfectly
well. Anyway, this patch really means to be a verbatim copy from
Weston, so needs to be fixed in a follow-up. That's why I'll take your
R-b as is. :-)

> > +      the surface. They indicate how many pixels to remove from the
> > +      surface size from the left and the top. In other words, they are  
> 
> I prefer this "in other words" explanation. :)
> 
> Otherwise,
> Reviewed-by: Derek Foreman <derekf at osg.samsung.com>

Thanks,
pq


> 
> > +      still in the surface-local coordinate system, just like dst_width
> > +      and dst_height are.
> > +
> > +      If the wl_surface associated with the wl_viewport is destroyed,
> > +      the wl_viewport object becomes inert.
> > +
> > +      If the wl_viewport object is destroyed, the crop and scale
> > +      state is removed from the wl_surface. The change will be applied
> > +      on the next wl_surface.commit.
> > +    </description>
-------------- 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/20160429/8f3e690b/attachment-0001.sig>