From f565d80ff598f93e6e27d585357d8ebbce849769 Mon Sep 17 00:00:00 2001 From: Pekka Paalanen Date: Tue, 26 Nov 2013 18:19:44 +0100 Subject: [PATCH] protocol: crop & scale RFC v3 Add cropping and scaling to wl_surface. Add a global factory interface wl_scaler, which creates wl_scaler_surface objects tied to a given wl_surface. The wl_scaler_surface object can be used to set a cropping and scaling transformation to change how a wl_buffer maps to wl_surface contents. Changes in v2: Take into account buffer_transform and buffer_scale, and try to explain more clearly how the coordinate transformations work and what their order is. Add, that crop and scale state is double-buffered. Explain missing dst_x, dst_y. Clarify that undefined content still is some content, but NULL buffer implies no content nor size. Changes in v3: Disallow zero values for dst_width and dst_height. Open issues: Should this be a separate interface like here, or just a wl_surface request? If we keep this as a separate interface, rename wl_surface_scaler to wl_viewport. --- protocol/Makefile.am | 3 +- protocol/scaler.xml | 156 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 158 insertions(+), 1 deletion(-) create mode 100644 protocol/scaler.xml diff --git a/protocol/Makefile.am b/protocol/Makefile.am index 4f5ecc3f..5e331a74 100644 --- a/protocol/Makefile.am +++ b/protocol/Makefile.am @@ -7,7 +7,8 @@ protocol_sources = \ workspaces.xml \ text-cursor-position.xml \ wayland-test.xml \ - xdg-shell.xml + xdg-shell.xml \ + scaler.xml if HAVE_XMLLINT .PHONY: validate diff --git a/protocol/scaler.xml b/protocol/scaler.xml new file mode 100644 index 00000000..d98215a6 --- /dev/null +++ b/protocol/scaler.xml @@ -0,0 +1,156 @@ + + + + + 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. + + + + + 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 direct relationship between the buffer and the + surface size. + + + + + 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. + + + + + + + + + + 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. + + + + + + + + + + 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. + + 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 as defined in wl_surface.attach. + + 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. If the wl_buffer is + NULL, the surface has no content and therefore no size. + + 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_surface_scaler.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 + 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. + + + + + The associated wl_surface's crop and scale state is removed. + The change is applied on the next wl_surface.commit. + + + + + + + + + + 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. + + The bad_value protocol error is raised if src_width or + src_height is negative, or if dst_width or dst_height is not + positive. + + The crop and scale state is double-buffered state, and will be + applied on the next wl_surface.commit. + + Arguments dst_x and dst_y do not exist here, use the x and y + arguments to wl_surface.attach. The x, y, dst_width, and dst_height + define the surface-local coordinate system irrespective of the + attached wl_buffer size. + + + + + + + + + + + +