[RFC PATCH v2] protocol: Extend wayland seat with interfaces for sensor inputs.

[Stefan Schmidt]

Hello.

On 08/22/2013 11:45 PM, Bryce W. Harrington wrote:
> On Thu, Aug 22, 2013 at 09:46:28AM +0100, Stefan Schmidt wrote:
>> Treating some specific sensors as input devices. In particular
>> adding support for wl_compass, wl_gyroscope and wl_accelerometer here.
>>
>> Using these sensor as input for apps and games. Not covering any
>> background apps or services with this protocol.
>>
>> We have requests to start and stop sensor event receiving as well as
>> events to receive the different axis values for these sensors.
>>
>> V2:
>> o Add units to event arguments
>> o Define coordinate system
>> o Be more verbose on security policy in compositor and add error event
>>
>> Signed-off-by: Stefan Schmidt <s.schmidt at samsung.com>
>> ---
>>   protocol/wayland.xml |  175
> ++++++++++++++++++++++++++++++++++++++++++++++++++
>>   1 file changed, 175 insertions(+)
>>
>> diff --git a/protocol/wayland.xml b/protocol/wayland.xml
>> index d7bbbb9..e35413c 100644
>> --- a/protocol/wayland.xml
>> +++ b/protocol/wayland.xml
>> @@ -1251,6 +1251,9 @@
>>         <entry name="pointer" value="1" summary="The seat has pointer
> devices"/>
>>         <entry name="keyboard" value="2" summary="The seat has one or
> more keyboards"/>
>>         <entry name="touch" value="4" summary="The seat has touch
> devices"/>
>> +      <entry name="compass" value="8" summary="The seat has compass
> devices"/>
>> +      <entry name="gyroscope" value="16" summary="The seat has
> gyroscope devices"/>
>> +      <entry name="accelerometer" value="32" summary="The seat has
> accelerometer devices"/>
>>       </enum>
>>
>>       <event name="capabilities">
>> @@ -1297,6 +1300,63 @@
>>
>>       <!-- Version 2 of additions -->
>>
>> +    <request name="get_compass" since="2">
>> +      <description summary="return compass object">
>> +        The ID provided will be initialized to the wl_compass interface
>> +	for this seat.
>> +
>> +        This request only takes effect if the seat has the compass
>> +        capability. If the seat has the capability but no object is
>> +        received it could be that the compositor security policy has
>> +        denied the sensor access for the client. In case of a security
>> +        policy error an error event will be send.
>
> sp. 'send' s/b 'sent'
>
>> +      </description>
>> +      <arg name="id" type="new_id" interface="wl_compass"/>
>> +    </request>
>> +
>> +    <request name="get_gyroscope" since="2">
>> +      <description summary="return gyroscope object">
>> +        The ID provided will be initialized to the wl_gyroscope
> interface
>> +	for this seat.
>> +
>> +        This request only takes effect if the seat has the gyroscope
>> +        capability. If the seat has the capability but no object is
>> +        received it could be that the compositor security policy has
>> +        denied the sensor access for the client. In case of a security
>> +        policy error an error event will be send.
>
> here too
>
>> +      </description>
>> +      <arg name="id" type="new_id" interface="wl_gyroscope"/>
>> +    </request>
>> +
>> +    <request name="get_accelerometer" since="2">
>> +      <description summary="return accelerometer object">
>> +        The ID provided will be initialized to the wl_accelerometer
> interface
>> +	for this seat.
>> +
>> +        This request only takes effect if the seat has the
> accelerometer
>> +        capability. If the seat has the capability but no object is
>> +        received it could be that the compositor security policy has
>> +        denied the sensor access for the client. In case of a security
>> +        policy error an error event will be send.
>
> here too
>
>> +      </description>
>> +      <arg name="id" type="new_id" interface="wl_accelerometer"/>
>> +    </request>
>> +
>> +    <event name="error">
>> +      <description summary="fatal error event">
>> +	The error event is sent out when a fatal (non-recoverable)
>> +	error has occurred.  The object_id argument is the object
>> +	where the error occurred, most often in response to a request
>> +	to that object.  The code identifies the error and is defined
>> +	by the object interface.  As such, each interface defines its
>> +	own set of error codes.  The message is an brief description
>
> sp. 'an brief' s/b 'a brief'
>
>> +	of the error, for (debugging) convenience.
>> +      </description>
>> +      <arg name="object_id" type="object"/>
>> +      <arg name="code" type="uint"/>
>> +      <arg name="message" type="string"/>
>> +    </event>
>> +
>>       <event name="name" since="2">
>>         <description summary="unique identifier for this seat">
>>   	In a multiseat configuration this can be used by the client to
> help
>> @@ -1605,6 +1665,121 @@
>>       </event>
>>     </interface>
>>
>> +  <interface name="wl_compass" version="2">
>> +    <description summary="compass sensor device">
>> +      The wl_compass interface represents a compass
>> +      associated with a seat.
>> +    </description>
>> +
>> +    <request name="start">
>> +      <description summary="Start receiving events">
>> +	Sent to enable event receiving for the compass sensor.
>> +      </description>
>> +    </request>
>> +
>> +    <request name="stop">
>> +      <description summary="Stop receiving events">
>> +	Sent to disable event receiving for the compass sensor.
>> +
>> +	It stops event reporting to this client. Other clients might still
>> +	receive events.
>> +      </description>
>> +    </request>
>> +
>> +    <event name="motion">
>> +      <description summary="Motion event coming from the compass
> sensor">
>> +	Updated sensor data available from compass
>> +
>> +	Measurement of the ambient magnetic field in the X, Y and Z axis.
>
> sp. 'axis' s/b plural 'axes' here I think...
>
>> +
>> +	Coordinate system (device in portrait mode with screen facing
> upwards):
>> +	X axis goes from the left to the right side of the device
>> +	Y axis goes from the bottom of the screen to the top
>> +	Z axis goes from the back of the screen to the front of the screen
>> +     </description>
>> +      <arg name="x" type="fixed" summary="x-axis in micro Tesla (uT)"/>
>> +      <arg name="y" type="fixed" summary="y-axis in micro Tesla (uT)"/>
>> +      <arg name="z" type="fixed" summary="z-axis in micro Tesla (uT)"/>
>> +    </event>
>> +  </interface>
>> +
>> +  <interface name="wl_gyroscope" version="2">
>> +    <description summary="gyroscope sensor device">
>> +      The wl_gyroscope interface represents a gyroscope
>> +      associated with a seat.
>> +    </description>
>> +
>> +    <request name="start">
>> +      <description summary="Start receiving events">
>> +	Sent to enable event receiving for the gyroscope sensor.
>> +      </description>
>> +    </request>
>> +
>> +    <request name="stop">
>> +      <description summary="Stop receiving events">
>> +	Sent to disable event receiving for the gyroscope sensor.
>> +
>> +	It stops event reporting to this client. Other clients might still
>> +	receive events.
>> +      </description>
>> +    </request>
>> +
>> +    <event name="motion">
>> +      <description summary="Motion event coming from the gyroscope
> sensor">
>> +	Updated sensor data available from gyroscope
>> +
>> +	Measurement of the rate of rotation around X, Y and Z axis in
> degree per second.
>
> sp. 'degree' s/b 'degrees'
>
>> +	Values are observed in positive notation in the counter-clockwise
> direction.
>> +
>> +	Coordinate system (device in portrait mode with screen facing
> upwards):
>> +	X axis goes from the left to the right side of the device (Pitch)
>> +	Y axis goes from the bottom of the screen to the top (Roll)
>> +	Z axis goes from the back of the screen to the front of the screen
> (Azimuth/Yaw)
>> +      </description>
>> +      <arg name="x" type="fixed" summary="x-axis in degree per
> second"/>
>> +      <arg name="y" type="fixed" summary="y-axis in degree per
> second"/>
>> +      <arg name="z" type="fixed" summary="z-axis in degree per
> second"/>
>
> ditto *3
>
>> +    </event>
>> +  </interface>
>> +
>> +  <interface name="wl_accelerometer" version="2">
>> +    <description summary="accelerometer sensor device">
>> +      The wl_accelerometer interface represents a accelerometer
>
> sp. 'a' s/b 'an'
>
>> +      associated with a seat.
>> +    </description>
>> +
>> +    <request name="start">
>> +      <description summary="Start receiving events">
>> +	Sent to enable event receiving for the accelerometer sensor.
>> +      </description>
>> +    </request>
>> +
>> +    <request name="stop">
>> +      <description summary="Stop receiving events">
>> +	Sent to disable event receiving for the accelerometer sensor.
>> +
>> +	It stops event reporting to this client. Other clients might still
>> +	receive events.
>> +      </description>
>> +    </request>
>> +
>> +    <event name="motion">
>> +      <description summary="Motion event coming from the accelerometer
> sensor">
>> +	Updated sensor data available from accelerometer
>> +
>> +	Measurement of the acceleration of G on the axis in m/s^2.
>
> Maybe 'on the given axis' would be better?
>
>> +
>> +	Coordinate system (device in portrait mode with screen facing
> upwards):
>> +	X axis goes from the left to the right side of the device
>> +	Y axis goes from the bottom of the screen to the top
>> +	Z axis goes from the back of the screen to the front of the screen
>> +      </description>
>> +      <arg name="x" type="fixed" summary="x-axis G in m/s^2"/>
>> +      <arg name="y" type="fixed" summary="y-axis G in m/s^2"/>
>> +      <arg name="z" type="fixed" summary="z-axis G in m/s^2"/>
>> +    </event>
>> +  </interface>
>> +
>>     <interface name="wl_output" version="2">
>>       <description summary="compositor output region">
>>         An output describes part of the compositor geometry.  The
>> --
>> 1.7.9.5
>
> Other than the little copyedits, nice work.

Added all of your spelling fixes. The joy of being a non-native 
speaker... :)

> Reviewed-by: Bryce Harrington <b.harrington at samsung.com>

I have not added this yet. Simple reason is that I think this will 
change a bit and by then your review tag would not be valid anymore. 
Looking forward to adding it again after a review once this in shape to 
go in.

regards
Stefan Schmidt