[RFC] wl_surface scale and crop protocol extension

John Kåre Alsaker john.kare.alsaker at gmail.com
Tue Apr 30 07:06:02 PDT 2013


I'd say we should split the cropping and scaling request into two.

Specifying a scaling with a NULL buffer should still set the surface size,
so we can have surfaces with only an input region.

I don't see a way to disable scaling and cropping, could passing 0 as width
and height do that?


On Tue, Apr 30, 2013 at 2:33 PM, Pekka Paalanen <ppaalanen at gmail.com> wrote:

> Hi all,
>
> below is my first draft for a wl_surface scaling and cropping
> extension. I called it wl_scaler in the lack of a better name. It is
> designed similarly to the other wl_surface extensions wl_shell_surface
> and wl_subsurface.
>
> There probably isn't any interesting details to debate, right? ;-)
>
> I'd like to have a better name for it, and you might want the set
> request split into two or three, or not, but otherwise I'm quite
> satisfied with it. I tried to take into account all existing protocol
> that interacts with this.
>
> Comments? Is the language clear?
>
>
> Thanks,
> pq
>
>
> <?xml version="1.0" encoding="UTF-8"?>
> <protocol name="scaler">
>
>   <copyright>
>     Copyright © 2013 Collabora, Ltd.
>
>     Permission to use, copy, modify, distribute, and sell this
>     software and its documentation for any purpose is hereby granted
>     without fee, provided that the above copyright notice appear in
>     all copies and that both that copyright notice and this permission
>     notice appear in supporting documentation, and that the name of
>     the copyright holders not be used in advertising or publicity
>     pertaining to distribution of the software without specific,
>     written prior permission.  The copyright holders make no
>     representations about the suitability of this software for any
>     purpose.  It is provided "as is" without express or implied
>     warranty.
>
>     THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD TO THIS
>     SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
>     FITNESS, IN NO EVENT SHALL THE COPYRIGHT HOLDERS BE LIABLE FOR ANY
>     SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
>     WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN
>     AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
>     ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
>     THIS SOFTWARE.
>   </copyright>
>
>   <interface name="wl_scaler" 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
>       wl_surface object. This extended interface will then allow
>       cropping and scaling the surface contents, effectively
>       disconnecting the 1:1 relationship between the buffer and the
>       surface size.
>     </description>
>
>     <request name="destroy" type="destructor">
>       <description summary="unbind from the cropping and scaling
> interface">
>         Informs the server that the client will not be using this
>         protocol object anymore. This does not affect any other objects,
>         wl_surface_scaler objects included.
>       </description>
>     </request>
>
>     <enum name="error">
>       <entry name="scaler_exists" value="0"
>              summary="the surface already has a scaler object associated"/>
>     </enum>
>
>     <request name="get_surface_scaler">
>       <description summary="extend surface interface for crop and scale">
>         Instantiate an interface extension for the given wl_surface to
>         crop and scale its content. If the given wl_surface already has
>         a wl_surface_scaler object associated, the scaler_exists
>         protocol error is raised.
>       </description>
>
>       <arg name="id" type="new_id" interface="wl_surface_scaler"
>            summary="the new scaler interface id"/>
>       <arg name="surface" type="object" interface="wl_surface"
>            summary="the surface"/>
>     </request>
>   </interface>
>
>   <interface name="wl_surface_scaler" version="1">
>     <description summary="crop and scale interface to a wl_surface">
>       An additional interface to a wl_surface object, allowing 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.
>
>       Before the first set request, the wl_surface still behaves as if
>       there was no crop and scale state. That is, no scaling is applied,
>       and the surface size is the buffer size.
>
>       On compositing, source rectangle coordinates are evaluated after
>       wl_surface.set_buffer_transform is evaluated. This means that
>       changing the buffer transform and correspondingly the client
>       rendering does not require sending new source rectangle
>       coordinates to keep the exact same image source rectangle. In
>       other words, the source rectangle is given in the
>       not-scaled-and-cropped surface coordinates, not buffer data
>       coordinates.
>
>       The crop and scale state causes the surface size to become
>       dst_width, dst_height. This overrides whatever the attached
>       wl_buffer size is, unless the wl_buffer is NULL.
>
>       The surface-local coordinate system is tied to the space of
>       dst_width and dst_height. That is, surface-local coordinates are
>       relative to the scaled and cropped surface, not the wl_buffer
>       providing the content.
>
>       If the source rectangle is partially or completely outside of the
>       wl_buffer, then the surface contents are undefined, and the
>       surface size is still dst_width, dst_height.
>
>       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.
>
>       If the wl_surface associated with the wl_surface_scaler is
>       destroyed, the wl_surface_scaler object becomes inert.
>
>       If the wl_surface_scaler 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>
>
>     <request name="destroy" type="destructor">
>       <description summary="remove scaling and cropping from the surface">
>         The associated wl_surface's crop and scale state is removed.
>         The change is applied on the next wl_surface.commit.
>       </description>
>     </request>
>
>     <enum name="error">
>       <entry name="bad_value" value="0"
>              summary="negative values in width or height"/>
>     </enum>
>
>     <request name="set">
>       <description summary="set the crop and scale state">
>         Set the crop and scale state of the associated wl_surface. See
>         wl_surface_scaler for the description, and relation to the
>         wl_buffer size.
>
>         If any of src_width, src_height, dst_width, and dst_height is
>         negative, the bad_value protocol error is raised.
>       </description>
>
>       <arg name="src_x" type="fixed" summary="source rectangle x"/>
>       <arg name="src_y" type="fixed" summary="source rectangle y"/>
>       <arg name="src_width" type="fixed" summary="source rectangle width"/>
>       <arg name="src_height" type="fixed" summary="source rectangle
> height"/>
>       <arg name="dst_width" type="int" summary="surface width"/>
>       <arg name="dst_height" type="int" summary="surface height"/>
>     </request>
>
>   </interface>
> </protocol>
>
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freedesktop.org/archives/wayland-devel/attachments/20130430/14779ceb/attachment-0001.html>


More information about the wayland-devel mailing list