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

[Juan Zhao]

  On 03/01/2012 01:20 AM, Kristian Hoegsberg wrote:
> On Wed, Feb 29, 2012 at 09:59:43AM +0200, Pekka Paalanen wrote:
>> On Tue, 28 Feb 2012 16:48:26 +0000
>> 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"/>
>> Looks good to me, thanks.
>> Can we have summary attributes to the enums themselves, or would those
>> be redundant?
> Agree, it clears things up a bit.  Pushed.
Appreciated. Thank you all to refine it!

BRs,
Juan


> Kristian
> _______________________________________________
> wayland-devel mailing list
> wayland-devel at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/wayland-devel