[RFC v4] Fullscreen shell protocol

[Jonas Ådahl]

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 at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel