<div dir="ltr">Jonas, thanks for reviewing. On Feb 24, 2014 4:03 PM, "Jonas Ådahl" <<a href="mailto:jadahl@gmail.com" target="_blank">jadahl@gmail.com</a>> wrote: > > On Thu, Feb 13, 2014 at 10:37:53PM -0600, Jason Ekstrand wrote: > > The following is yet another take on the fullscreen shell protocol. > > Previous versions more-or-less followed the approach taken in wl_shell. > > This version completely reworks the concept. In particular, the protocol > > is split into two use-cases. The first is that of a simple client that > > wants to present a surface or set of surfaces possibly with some scaling. > > This happens through the present_surface request which looks similar to > > that of wl_shell only without the modesetting. > > > > The second use-case is of a client that wants more control over the > > outputs. In this case, the client uses the present_surface_for_mode > > request to present the surface at a particular output mode. This request > > provides a more-or-less atomic modeset operation. If the compositor can > > satisfy the requested mode, then the mode is changed and the new surface is > > presented. Otherwise, the compositor harmlessly falls back to the > > previously presented surface and the client is informed that the switch > > failed. This way, the surface is either displayed correctly or not at all. > > Of course, a client is free to call present_surface_for_mode with the > > currently presented surface and hope for the best. However, this may > > result in strange behavior and there is no reliable fallback if the mode > > switch fails. > > > > In particular, I would like feedback on the modesetting portion of this > > protocol. This is particularly targetted at compositors that want to run > > inside weston or some other fullscreen compositor. In the next week or so, > > I will attempt to implement all this in weston and see how well it works. > > However, I would also like to know how well this will work for other > > compositors such as KWin or Hawaii. > > Hi Jason, > > Some follow up comments from last round inline. > > > > > Thanks for your feedback, > > --Jason Ekstrand > > > > ===== Protocol follows: ===== > > > > <protocol name="fullscreen_shell"> > > <interface name="wl_fullscreen_shell" version="1"> > > <description summary="Displays a single surface per output"> > > Displays a single surface per output. > > > > This interface provides a mechanism for a single client to display > > simple full-screen surfaces. While there technically may be multiple > > clients bound to this interface, only one of those clients should be > > shown at a time. > > > > To present a surface, the client uses either the present_surface or > > present_surface_for_mode requests. Presenting a surface takes effect > > on the next wl_surface.commit. See the individual requests for > > details about scaling and mode switches. > > > > The client can have at most one surface per output at any time. > > Requesting a surface be presented on an output that already has a > > surface replaces the previously presented surface. Presenting a null > > surface removes its content and effectively disables the output. > > Exactly what happens when an output is "disabled" is > > compositor-specific. The same surface may be presented multiple > > outputs simultaneously. > > </description> > > > > <enum name="present_method"> > > <description summary="different method to set the surface fullscreen"> > > Hints to indicate to the compositor how to deal with a conflict > > between the dimensions of the surface and the dimensions of the > > output. The compositor is free to ignore this parameter. > > </description> > > <entry name="default" value="0" summary="no preference, apply default policy"/> > > <entry name="center" value="1" summary="center the surface on the output"/> > > <entry name="zoom" value="2" summary="scale the surface, preserving aspect ratio, to the largest size that will fit on the output" /> > > <entry name="zoom_crop" value="3" summary="scale the surface, preserving aspect ratio, to fully fill the output cropping if needed" /> > > <entry name="stretch" value="4" summary="scale the surface to the size of the output ignoring aspect ratio" /> > > </enum> > > > > <request name="present_surface"> > > <description summary="present surface for display"> > > Present a surface on the given output. > > > > If the output is null, the compositor will present the surface on > > whatever display (or displays) it thinks best. In particular, this > > may replace any or all surfaces currently presented so it should > > not be used in combination with placing surfaces on specific > > outputs. > > > > The method parameter is a hit to the compositor for how the surface > > is to be presented. In particular, it tells the compostior how to > > handle a size mismatch between the presented surface and the > > output. The compositor is free to ignore this parameter. > > > > The "zoom", "zoom_crop", and "stretch" methods imply a scaling > > operation on the surface. This will override any kind of output > > scaling, so the buffer_scale property of the surface is effectively > > ignored. > > </description> > > <arg name="surface" type="object" interface="wl_surface"/> > > I think you might be missing an 'allow-null="true"' parameter here, as > you above specify that presenting a null-surface on non-null output > would "disable" that output. Yes, it does. I have it fixed locally. > > It might also be a good idea to add a note that presenting a > null-surface on a null-output should raise a protocol error as I assume > it should. Nope, that's fine. It should clear whatever default stuff you've presented. In my implementation, it clears everything. > > Regarding present_surface_for_mode, it is unclear if it is expected > that it will handle null-surface (if you'd add allow-null="true") as one > need to provide a frame rate, while the description doesn't say anything > of what method of presenting has the described effect. Yeah. You could make null here the same as the other or not accept null. From a client perspective it shouldn't make much difference whether they call one or the other. I think we can make allow-null=false for present_surface_for_mode for now. If we ever have reason to change that we can later. > > > Jonas > > > <arg name="method" type="uint"/> > > <arg name="output" type="object" interface="wl_output" allow-null="true"/> > > </request> > > > > <request name="present_surface_for_mode"> > > <description summary="present surface for display at a particular mode"> > > Presents a surface on the given output for a particular mode. > > > > If the current size of the output differs from that of the surface, > > the compositor will attempt to change the size of the output to > > match the surface. The result of the mode-swith operation will be > > returned via the provided wl_fullscreen_shell_mode_feedback object. > > > > If the current output mode matches the one requested or if the > > compositor successfully switches the mode to match the surface, > > then the mode_successfull event will be sent and the output will > > contain the contents of the given surface. If the compositor > > cannot match the output size to the surface size, the mode_failed > > will be sent and the output will contain the contents of the > > previously presented surface (if any). If another surface is > > presented on the given output before either of these has a chance > > to happen, the present_canceled event will be sent. > > > > If the size of the presented surface changes, the resulting output > > is undefined. The compositor may attempt to change the output mode > > to compensate. However, there is no guarantee that a suitable mode > > will be found and the client has no way to be notified of success > > or failure. > > > > The framerate parameter specifies the target framerate for the > > output. The compositor is free to ignore this parameter. A value > > of 0 indicates that the client has no preference. > > > > If the surface has a buffer_scale greater than 1, the compositor > > may choose a mode that matches either the buffer size or the > > surface size. In either case, the surface will fill the output. > > </description> > > <arg name="surface" type="object" interface="wl_surface"/> > > <arg name="output" type="object" interface="wl_output"/> > > <arg name="framerate" type="int"/> > > <arg name="feedback" type="new_id" interface="wl_fullscreen_shell_mode_feedback"/> > > </request> > > > > <enum name="error"> > > <description summary="wl_fullscreen_shell error values"> > > These errors can be emitted in response to wl_fullscreen_shell requests > > </description> > > <entry name="invalid_method" value="0" summary="present_method is not known"/> > > </enum> > > </interface> > > > > <interface name="wl_fullscreen_shell_mode_feedback" version="1"> > > <event name="mode_successful"> > > <description summary="mode switch succeeded"> > > This event indicates that the attempted mode switch operation was > > successful. A surface of the size requested in the mode switch > > will fill the output without scaling. > > > > Upon recieving this event, the client should destroy the > > wl_fullscreen_shell_mode_feedback object. > > </description> > > </event> > > <event name="mode_failed"> > > <description summary="mode switch succeeded"> > > This event indicates that the attempted mode switch operation > > failed. This may be because the requested output mode is not > > possible or it may mean that the compositor does not want to allow > > mode switches at this time. > > > > Upon recieving this event, the client should destroy the > > wl_fullscreen_shell_mode_feedback object. > > </description> > > </event> > > <event name="present_canceled"> > > <description summary="mode switch succeeded"> > > This event indicates that the attempted mode switch operation was > > canceled. Most likely this is because the client requested a > > second mode switch before the first one completed. > > > > Upon recieving this event, the client should destroy the > > wl_fullscreen_shell_mode_feedback object. > > </description> > > </event> > > </interface> > > </protocol> > > _______________________________________________ > > wayland-devel mailing list > > <a href="mailto:wayland-devel@lists.freedesktop.org" target="_blank">wayland-devel@lists.freedesktop.org</a> > > <a href="http://lists.freedesktop.org/mailman/listinfo/wayland-devel" target="_blank">http://lists.freedesktop.org/mailman/listinfo/wayland-devel</a> </div>