[RFC] wl_surface scale and crop protocol extension

[Bill Spitzak]

Pekka Paalanen 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?

"scalar" is often used to identify a single number in linear algebra. A 
different name would be better. "transform" might work but that also 
would cover the subsurface and surface transforms, perhaps that can be 
moved to this api as well.

I think the buffer_transform and surface x,y should be part of this. Ie 
when this is created it is initialized with these values, and changes to 
these values make identical changes to the transform values.

There is a whole stack of transforms and clips that need to be applied 
and possibly the methods for all of these should be put into this api. I 
think all of the following transforms should work. Transforms are affine 
matrix defined by 6 numbers and include translation.

First there is the actual pixels in the buffer. The buffer has a width 
and height and starts out oriented with the width horizontal and the 
corner at 0,0. Pixels outside this rectangle have implementation-defined 
values (depending on the renderer they may be black or the edges 
replicated).

There is a "drawing transform". The *inverse* of this transform is 
applied to the pixels. The current buffer_transform is incorporated into 
this matrix. The purpose is so if a client can figure out the total 
transform it can compensate for it when drawing. It also allows a client 
to use a single very large buffer and lay out the drawings of multiple 
surfaces inside it. The reason it is inverted and not merged with the 
scaling transform is so the compositor can divide by it accurately, and 
so it matches the matrix passed to cairo.

Then there is the "scaling transform". The pixels are transformed by 
this to "surface space". The translation is used to set the corner of 
the crop. Events sent to the surface are reported in surface space, as 
in your proposal, and opaque and input regions are defined in this space.

Then there is the "crop", which is a width and height. This and 0,0 
determine a rectangle in "surface space" and determine the surface size. 
The compositor replaces all pixels outside this rectangle with 
transparent black.

Then there is a "surface transform". The current x,y of wl_surface is 
the translation component of this. This already exists.

It is further transformed by the surface transform of a parent surface 
for a subsurface, and recursively for it's parent, etc.

Finally it is transformed by the "output transform" which handles RandR 
of the outputs.