[PATCH] protocol: Clarify the documentation for the fullscreen protocol

[Rob Bradford]

Juan,

Does this align with what you intended in this request? I think it is
a bit clearer now and resolves some of the items we discussed at the
last hackfest and also on IRC.

Cheers,

Rob

On 28 February 2012 16:48, Rob Bradford <rob at robster.org.uk> wrote:
> From: Rob Bradford <rob at linux.intel.com>
>
> ---
>  protocol/wayland.xml |   53 ++++++++++++++++++++++++++++++++-----------------
>  1 files changed, 34 insertions(+), 19 deletions(-)
>
> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
> index 5cc13a8..3631289 100644
> --- a/protocol/wayland.xml
> +++ b/protocol/wayland.xml
> @@ -431,12 +431,22 @@
>
>     <request name="set_fullscreen">
>       <description summary="make the surface a fullscreen surface">
> -       Map the surface as a fullscreen surface. On the output the
> -       surface is assigned to. The client can use different fulllscreen
> -       method to fix the size mismatch issue: default, scale, driver
> -       and fill. And the framerate parameter is used for "driver" method,
> -       to indicate the preferred framerate. framerate=0 means that the
> -       app does not care about framerate
> +        Map the surface as a fullscreen surface. If an output parameter is
> +        given then the surface will be made fullscreen on that output. If the
> +        client does not specify the output then the compositor will apply its
> +        policy - usually choosing the output on which the surface has the
> +        biggest surface area.
> +
> +        The client may specify a method to resolve a size conflict between the
> +        output size and the surface size - this is provided through the
> +        fullscreen_method parameter.
> +
> +        The framerate parameter is used only when the fullscreen_method is set
> +        to "driver", to indicate the preferred framerate. framerate=0 indicates
> +        that the app does not care about framerate.
> +
> +        The compositor must reply to this request with a configure event with
> +        the dimensions for the output on which the surface will be made fullscreen.
>       </description>
>       <arg name="method" type="uint"/>
>       <arg name="framerate" type="uint"/>
> @@ -445,19 +455,24 @@
>
>     <enum name="fullscreen_method">
>       <description summary="different method to set the surface fullscreen">
> -       Hints to indicate compositor how to deal with this fullscreen surface.
> -       "default" means the client has no preference on fullscreen
> -                 behavior, policies are determined by compositor.
> -       "scale"   means the client prefers scaling by the compositor.
> -                 Scaling would always preserve surface's aspect ratio.
> -                 And the surface is centered.
> -       "driver"  means the client wants to switch video mode to the
> -                 smallest mode that can fit the client buffer. If the
> -                 sizes do not match, black borders are added.
> -       "fill"    means the client wants to add blackborders to the
> -                 surface. This would be preferring 1:1 pixel mapping
> -                 in the monitor native video mode. The surface is
> -                 centered.
> +        Hints to indicate compositor how to deal with a conflict between the
> +        dimensions for the surface and the dimensions of the output. As a hint
> +        the compositor is free to ignore this parameter.
> +
> +        "default" The client has no preference on fullscreen behavior,
> +        policies are determined by compositor.
> +
> +        "scale" The client prefers scaling by the compositor. Scaling would
> +        always preserve surface's aspect ratio with surface centered on the
> +        output
> +
> +        "driver" The client wants to switch video mode to the smallest mode
> +        that can fit the client buffer. If the sizes do not match the
> +        compositor must add black borders.
> +
> +        "fill" The surface is centered on the output on the screen with no
> +        scaling. If the surface is of insufficient size the compositor must
> +        add black borders.
>       </description>
>       <entry name="default" value="0"/>
>       <entry name="scale" value="1"/>
> --
> 1.7.7.6
>