[PATCH fullscreen-shell v6 01/19] Add a fullscreen shell protocol
Bryce W. Harrington
b.harrington at samsung.com
Tue Apr 8 11:02:23 PDT 2014
Looks good, spotted one typo though.
On Wed, Apr 02, 2014 at 07:53:43PM -0500, Jason Ekstrand wrote:
> Signed-off-by: Jason Ekstrand <jason at jlekstrand.net>
> ---
> protocol/fullscreen-shell.xml | 206 ++++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 206 insertions(+)
> create mode 100644 protocol/fullscreen-shell.xml
>
> diff --git a/protocol/fullscreen-shell.xml b/protocol/fullscreen-shell.xml
> new file mode 100644
> index 0000000..8639ea3
> --- /dev/null
> +++ b/protocol/fullscreen-shell.xml
> @@ -0,0 +1,206 @@
> +<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 on multiple
> + outputs simultaneously.
> +
> + Once a surface is presented on an output, it stays on that output
> + until either the client removes it or the compositor destroys the
> + output. This way, the client can update the output's contents by
> + simply attaching a new buffer.
> + </description>
> +
> + <request name="release" type="destructor">
> + <description summary="release the wl_fullscreen_shell interface">
> + Release the binding from the wl_fullscreen_shell interface
> +
> + This destroys the server-side object and frees this binding. If
> + the client binds to wl_fullscreen_shell multiple times, it may wish
> + to free some of those bindings.
> + </description>
> + </request>
> +
> + <enum name="capability">
> + <description summary="capabilities advertised by the compositor">
> + Various capabilities that can be advertised by the compositor. They
> + are advertised one-at-a-time when the wl_fullscreen_shell interface is
> + bound. See the wl_fullscreen_shell.capability event for more details.
> +
> + ARBITRARY_MODE:
> + This is a hint to the client that indicates that the compositor is
> + capable of setting practially any mode on its outputs. If this
> + capability is provided, wl_fullscreen_shell.present_surface_for_mode
> + will almost never fail and clients should feel free to set whatever
> + mode they like. If the compositor does not advertise this, it may
> + still suppot some modes that are not advertised through wl_global.mode
support
> + but it is less likely.
> +
> + CURSOR_PLANE:
> + This is a hint to the client that indicates that the compositor can
> + handle a cursor surface from the client without actually compositing.
> + This may be because of a hardware cursor plane or some other mechanism.
> + If the compositor does not advertise this capability then setting
> + wl_pointer.cursor may degrade performance or be ignored entirely. If
> + CURSOR_PLANE is not advertised, it is recommended that the client draw
> + its own cursor and set wl_pointer.cursor(NULL).
> + </description>
> + <entry name="arbitrary_modes" value="1" summary="compositor is capable of almost any output mode"/>
> + <entry name="cursor_plane" value="2" summary="compositor has a seperate cursor plane"/>
> + </enum>
> +
> + <event name="capability">
> + <description summary="advertises a capability of the compositor">
> + Advertises a single capability of the compositor.
> +
> + When the wl_fullscreen_shell interface is bound, this event is emitted
> + once for each capability advertised. Valid capabilities are given by
> + the wl_fullscreen_shell.capability enum. If clients want to take
> + advantage of any of these capabilities, they sould use a
> + wl_display.sync request immediatly after binding to ensure that they
> + recieve all the capability events.
> + </description>
> + <arg name="capabilty" type="uint"/>
> + </event>
> +
> + <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 hint 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" allow-null="true"/>
> + <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-switch 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_successful 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_cancelled event will be sent.
> +
> + Due to race conditions and other issues unknown to the client, no
> + mode-switch operation is guaranteed to succeed. However, if the
> + mode is one advertised by wl_output.mode or if the compositor
> + advertises the ARBITRARY_MODES capability, then the client should
> + expect that the mode-switch operation will usually succeed.
> +
> + 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 desired framerate for the
> + output in mHz. The compositor is free to ignore this parameter. A
> + value of 0 indicates that the client has no preference.
> +
> + If the value of wl_output.scale differs from wl_surface.buffer_scale,
> + then 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 receiving this event, the client should destroy the
> + wl_fullscreen_shell_mode_feedback object.
> + </description>
> + </event>
> + <event name="mode_failed">
> + <description summary="mode switch failed">
> + 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 it.
> +
> + Upon receiving this event, the client should destroy the
> + wl_fullscreen_shell_mode_feedback object.
> + </description>
> + </event>
> + <event name="present_cancelled">
> + <description summary="mode switch cancelled">
> + This event indicates that the attempted mode switch operation was
> + cancelled. Most likely this is because the client requested a
> + second mode switch before the first one completed.
> +
> + Upon receiving this event, the client should destroy the
> + wl_fullscreen_shell_mode_feedback object.
> + </description>
> + </event>
> + </interface>
> +</protocol>
> --
> 1.9.0
>
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel
More information about the wayland-devel
mailing list