[RFC v4] Fullscreen shell protocol

Mon Feb 24 18:07:06 PST 2014

Jonas, thanks for reviewing.
On Feb 24, 2014 4:03 PM, "Jonas Ådahl" <jadahl at gmail.com> 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
> > 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/20140224/e41b2987/attachment-0001.html>