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. 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. 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. 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 > wayland-devel@lists.freedesktop.org > http://lists.freedesktop.org/mailman/listinfo/wayland-devel _______________________________________________ wayland-devel mailing list wayland-devel@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/wayland-devel
