diff mbox series

[v4,2/4] dt-bindings: touchscreen: add overlay-touchscreen and overlay-buttons properties

Message ID 20230510-feature-ts_virtobj_patch-v4-2-5c6c0fc1eed6@wolfvision.net
State New
Headers show
Series [v4,1/4] Input: touch-overlay - Add touchscreen overlay object handling | expand

Commit Message

Javier Carrasco Aug. 24, 2023, 1:17 p.m. UTC
The overlay-touchscreen object defines an area within the touchscreen
where touch events are reported and their coordinates get converted to
the overlay origin. This object avoids getting events from areas that
are physically hidden by overlay frames.

For touchscreens where overlay buttons on the touchscreen surface are
provided, the overlay-buttons object contains a node for every button
and the key event that should be reported when pressed.

Signed-off-by: Javier Carrasco <javier.carrasco@wolfvision.net>
---
 .../bindings/input/touchscreen/touchscreen.yaml    | 152 +++++++++++++++++++++
 1 file changed, 152 insertions(+)

Comments

Rob Herring Aug. 31, 2023, 11:48 a.m. UTC | #1
On Thu, Aug 24, 2023 at 03:17:10PM +0200, Javier Carrasco wrote:
> The overlay-touchscreen object defines an area within the touchscreen
> where touch events are reported and their coordinates get converted to
> the overlay origin. This object avoids getting events from areas that
> are physically hidden by overlay frames.
> 
> For touchscreens where overlay buttons on the touchscreen surface are
> provided, the overlay-buttons object contains a node for every button
> and the key event that should be reported when pressed.
> 
> Signed-off-by: Javier Carrasco <javier.carrasco@wolfvision.net>
> ---
>  .../bindings/input/touchscreen/touchscreen.yaml    | 152 +++++++++++++++++++++
>  1 file changed, 152 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> index 895592da9626..d90cbb4932b5 100644
> --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> @@ -80,6 +80,158 @@ properties:
>    touchscreen-y-plate-ohms:
>      description: Resistance of the Y-plate in Ohms
>  
> +  overlay-touchscreen:
> +    description: Clipped touchscreen area
> +
> +      This object can be used to describe a frame that restricts the area
> +      within touch events are reported, ignoring the events that occur outside
> +      this area. This is of special interest if the touchscreen is shipped
> +      with a physical overlay on top of it with a frame that hides some part
> +      of the original touchscreen area.
> +
> +      The x-origin and y-origin properties of this object define the offset of
> +      a new origin from where the touchscreen events are referenced.
> +      This offset is applied to the events accordingly. The x-size and y-size
> +      properties define the size of the overlay-touchscreen (effective area).
> +
> +      The following example shows the new touchscreen area and the new origin
> +      (0',0') for the touch events generated by the device.
> +
> +                   Touchscreen (full area)
> +         ┌────────────────────────────────────────┐
> +         │    ┌───────────────────────────────┐   │
> +         │    │                               │   │
> +         │    ├ y-size                        │   │
> +         │    │                               │   │
> +         │    │      overlay-touchscreen      │   │
> +         │    │                               │   │
> +         │    │                               │   │
> +         │    │            x-size             │   │
> +         │   ┌└──────────────┴────────────────┘   │
> +         │(0',0')                                 │
> +        ┌└────────────────────────────────────────┘
> +      (0,0)
> +
> +     where (0',0') = (0+x-origin,0+y-origin)

What happens if touchscreen-inverted-x/y are set?

Though the existing binding never defines what the non-inverted 
orientation is.

> +
> +    type: object
> +
> +    properties:
> +      x-origin:
> +        description: horizontal origin of the clipped area
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +
> +      y-origin:
> +        description: vertical origin of the clipped area
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +
> +      x-size:
> +        description: horizontal resolution of the clipped area
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +
> +      y-size:
> +        description: vertical resolution of the clipped area
> +        $ref: /schemas/types.yaml#/definitions/uint32
> +
> +        required:
> +          - x-origin
> +          - y-origin
> +          - x-size
> +          - y-size
> +
> +  overlay-buttons:
> +    description: list of nodes defining the buttons on the touchscreen
> +
> +      This object can be used to describe buttons on the touchscreen area,
> +      reporting the touch events on their surface as key events instead of
> +      the original touch events.
> +
> +      This is of special interest if the touchscreen is shipped with a
> +      physical overlay on top of it where a number of buttons with some
> +      predefined functionality are printed. In that case a specific behavior
> +      is expected from those buttons instead of raw touch events.
> +
> +      The overlay-buttons properties define a per-button area as well as an
> +      origin relative to the real touchscreen origin. Touch events within the
> +      button area are reported as the key event defined in the linux,code
> +      property. Given that the key events do not provide coordinates, the
> +      button origin is only used to place the button area on the touchscreen
> +      surface. Any event outside the overlay-buttons object is reported as a
> +      touch event with no coordinate transformation.
> +
> +      The following example shows a touchscreen with a single button on it
> +
> +              Touchscreen (full area)
> +        ┌───────────────────────────────────┐
> +        │                                   │
> +        │                                   │
> +        │   ┌─────────┐                     │
> +        │   │button 0 │                     │
> +        │   │KEY_POWER│                     │
> +        │   └─────────┘                     │
> +        │                                   │
> +        │                                   │
> +       ┌└───────────────────────────────────┘
> +     (0,0)
> +
> +      The overlay-buttons object can  be combined with the overlay-touchscreen
> +      object as shown in the following example. In that case only the events
> +      within the overlay-touchscreen object are reported as touch events.
> +
> +                  Touchscreen (full area)
> +        ┌─────────┬──────────────────────────────┐
> +        │         │                              │
> +        │         │    ┌───────────────────────┐ │
> +        │ button 0│    │                       │ │
> +        │KEY_POWER│    │                       │ │
> +        │         │    │                       │ │
> +        ├─────────┤    │  overlay-touchscreen  │ │
> +        │         │    │                       │ │
> +        │         │    │                       │ │
> +        │ button 1│    │                       │ │
> +        │ KEY_INFO│   ┌└───────────────────────┘ │
> +        │         │(0',0')                       │
> +       ┌└─────────┴──────────────────────────────┘
> +     (0,0)
> +
> +    type: object
> +
> +    patternProperties:
> +      '^button-':
> +        type: object
> +        description:
> +          Each button (key) is represented as a sub-node.
> +
> +        properties:
> +          label:
> +            $ref: /schemas/types.yaml#/definitions/string
> +            description: descriptive name of the button
> +
> +          linux,code: true
> +
> +          x-origin:
> +            description: horizontal origin of the button area
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +
> +          y-origin:
> +            description: vertical origin of the button area
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +
> +          x-size:
> +            description: horizontal resolution of the button area
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +
> +          y-size:
> +            description: vertical resolution of the button area
> +            $ref: /schemas/types.yaml#/definitions/uint32
> +
> +        required:
> +          - linux,code
> +          - x-origin
> +          - y-origin
> +          - x-size
> +          - y-size

We have the same properties defined twice. Move all the common ones to a 
$def entry and then reference it here and in overlay-touchscreen.

$defs:
  overlay-node:
    type: object
    properties:
      x-origin:
      ...

And then here:

'^button-':
  $ref: '#/$defs/overlay-node
  unevaluatedProperties: false

  properties:
    label:
      ...


Rob
Javier Carrasco Oct. 13, 2023, 9:54 a.m. UTC | #2
Hi Rob,

On 31.08.23 13:48, Rob Herring wrote:
> On Thu, Aug 24, 2023 at 03:17:10PM +0200, Javier Carrasco wrote:
>> The overlay-touchscreen object defines an area within the touchscreen
>> where touch events are reported and their coordinates get converted to
>> the overlay origin. This object avoids getting events from areas that
>> are physically hidden by overlay frames.
>>
>> For touchscreens where overlay buttons on the touchscreen surface are
>> provided, the overlay-buttons object contains a node for every button
>> and the key event that should be reported when pressed.
>>
>> Signed-off-by: Javier Carrasco <javier.carrasco@wolfvision.net>
>> ---
>>  .../bindings/input/touchscreen/touchscreen.yaml    | 152 +++++++++++++++++++++
>>  1 file changed, 152 insertions(+)
>>
>> diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> index 895592da9626..d90cbb4932b5 100644
>> --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
>> @@ -80,6 +80,158 @@ properties:
>>    touchscreen-y-plate-ohms:
>>      description: Resistance of the Y-plate in Ohms
>>  
>> +  overlay-touchscreen:
>> +    description: Clipped touchscreen area
>> +
>> +      This object can be used to describe a frame that restricts the area
>> +      within touch events are reported, ignoring the events that occur outside
>> +      this area. This is of special interest if the touchscreen is shipped
>> +      with a physical overlay on top of it with a frame that hides some part
>> +      of the original touchscreen area.
>> +
>> +      The x-origin and y-origin properties of this object define the offset of
>> +      a new origin from where the touchscreen events are referenced.
>> +      This offset is applied to the events accordingly. The x-size and y-size
>> +      properties define the size of the overlay-touchscreen (effective area).
>> +
>> +      The following example shows the new touchscreen area and the new origin
>> +      (0',0') for the touch events generated by the device.
>> +
>> +                   Touchscreen (full area)
>> +         ┌────────────────────────────────────────┐
>> +         │    ┌───────────────────────────────┐   │
>> +         │    │                               │   │
>> +         │    ├ y-size                        │   │
>> +         │    │                               │   │
>> +         │    │      overlay-touchscreen      │   │
>> +         │    │                               │   │
>> +         │    │                               │   │
>> +         │    │            x-size             │   │
>> +         │   ┌└──────────────┴────────────────┘   │
>> +         │(0',0')                                 │
>> +        ┌└────────────────────────────────────────┘
>> +      (0,0)
>> +
>> +     where (0',0') = (0+x-origin,0+y-origin)
> 
> What happens if touchscreen-inverted-x/y are set?
> 
> Though the existing binding never defines what the non-inverted 
> orientation is.
> 
This feature acts on the raw input values and the inversion is carried
out afterwards.The events will be inverted within the defined frame,
which is probably the expected behavior.

>> +
>> +    type: object
>> +
>> +    properties:
>> +      x-origin:
>> +        description: horizontal origin of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      y-origin:
>> +        description: vertical origin of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      x-size:
>> +        description: horizontal resolution of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +      y-size:
>> +        description: vertical resolution of the clipped area
>> +        $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +        required:
>> +          - x-origin
>> +          - y-origin
>> +          - x-size
>> +          - y-size
>> +
>> +  overlay-buttons:
>> +    description: list of nodes defining the buttons on the touchscreen
>> +
>> +      This object can be used to describe buttons on the touchscreen area,
>> +      reporting the touch events on their surface as key events instead of
>> +      the original touch events.
>> +
>> +      This is of special interest if the touchscreen is shipped with a
>> +      physical overlay on top of it where a number of buttons with some
>> +      predefined functionality are printed. In that case a specific behavior
>> +      is expected from those buttons instead of raw touch events.
>> +
>> +      The overlay-buttons properties define a per-button area as well as an
>> +      origin relative to the real touchscreen origin. Touch events within the
>> +      button area are reported as the key event defined in the linux,code
>> +      property. Given that the key events do not provide coordinates, the
>> +      button origin is only used to place the button area on the touchscreen
>> +      surface. Any event outside the overlay-buttons object is reported as a
>> +      touch event with no coordinate transformation.
>> +
>> +      The following example shows a touchscreen with a single button on it
>> +
>> +              Touchscreen (full area)
>> +        ┌───────────────────────────────────┐
>> +        │                                   │
>> +        │                                   │
>> +        │   ┌─────────┐                     │
>> +        │   │button 0 │                     │
>> +        │   │KEY_POWER│                     │
>> +        │   └─────────┘                     │
>> +        │                                   │
>> +        │                                   │
>> +       ┌└───────────────────────────────────┘
>> +     (0,0)
>> +
>> +      The overlay-buttons object can  be combined with the overlay-touchscreen
>> +      object as shown in the following example. In that case only the events
>> +      within the overlay-touchscreen object are reported as touch events.
>> +
>> +                  Touchscreen (full area)
>> +        ┌─────────┬──────────────────────────────┐
>> +        │         │                              │
>> +        │         │    ┌───────────────────────┐ │
>> +        │ button 0│    │                       │ │
>> +        │KEY_POWER│    │                       │ │
>> +        │         │    │                       │ │
>> +        ├─────────┤    │  overlay-touchscreen  │ │
>> +        │         │    │                       │ │
>> +        │         │    │                       │ │
>> +        │ button 1│    │                       │ │
>> +        │ KEY_INFO│   ┌└───────────────────────┘ │
>> +        │         │(0',0')                       │
>> +       ┌└─────────┴──────────────────────────────┘
>> +     (0,0)
>> +
>> +    type: object
>> +
>> +    patternProperties:
>> +      '^button-':
>> +        type: object
>> +        description:
>> +          Each button (key) is represented as a sub-node.
>> +
>> +        properties:
>> +          label:
>> +            $ref: /schemas/types.yaml#/definitions/string
>> +            description: descriptive name of the button
>> +
>> +          linux,code: true
>> +
>> +          x-origin:
>> +            description: horizontal origin of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          y-origin:
>> +            description: vertical origin of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          x-size:
>> +            description: horizontal resolution of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +          y-size:
>> +            description: vertical resolution of the button area
>> +            $ref: /schemas/types.yaml#/definitions/uint32
>> +
>> +        required:
>> +          - linux,code
>> +          - x-origin
>> +          - y-origin
>> +          - x-size
>> +          - y-size
> 
> We have the same properties defined twice. Move all the common ones to a 
> $def entry and then reference it here and in overlay-touchscreen.
> 
> $defs:
>   overlay-node:
>     type: object
>     properties:
>       x-origin:
>       ...
> 
> And then here:
> 
> '^button-':
>   $ref: '#/$defs/overlay-node
>   unevaluatedProperties: false
> 
>   properties:
>     label:
>       ...
> 
> 
> Rob
Thank your for your feedback, I will send a next version with this
modification in it.

Best regards,
Javier Carrasco
diff mbox series

Patch

diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
index 895592da9626..d90cbb4932b5 100644
--- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
+++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
@@ -80,6 +80,158 @@  properties:
   touchscreen-y-plate-ohms:
     description: Resistance of the Y-plate in Ohms
 
+  overlay-touchscreen:
+    description: Clipped touchscreen area
+
+      This object can be used to describe a frame that restricts the area
+      within touch events are reported, ignoring the events that occur outside
+      this area. This is of special interest if the touchscreen is shipped
+      with a physical overlay on top of it with a frame that hides some part
+      of the original touchscreen area.
+
+      The x-origin and y-origin properties of this object define the offset of
+      a new origin from where the touchscreen events are referenced.
+      This offset is applied to the events accordingly. The x-size and y-size
+      properties define the size of the overlay-touchscreen (effective area).
+
+      The following example shows the new touchscreen area and the new origin
+      (0',0') for the touch events generated by the device.
+
+                   Touchscreen (full area)
+         ┌────────────────────────────────────────┐
+         │    ┌───────────────────────────────┐   │
+         │    │                               │   │
+         │    ├ y-size                        │   │
+         │    │                               │   │
+         │    │      overlay-touchscreen      │   │
+         │    │                               │   │
+         │    │                               │   │
+         │    │            x-size             │   │
+         │   ┌└──────────────┴────────────────┘   │
+         │(0',0')                                 │
+        ┌└────────────────────────────────────────┘
+      (0,0)
+
+     where (0',0') = (0+x-origin,0+y-origin)
+
+    type: object
+
+    properties:
+      x-origin:
+        description: horizontal origin of the clipped area
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+      y-origin:
+        description: vertical origin of the clipped area
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+      x-size:
+        description: horizontal resolution of the clipped area
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+      y-size:
+        description: vertical resolution of the clipped area
+        $ref: /schemas/types.yaml#/definitions/uint32
+
+        required:
+          - x-origin
+          - y-origin
+          - x-size
+          - y-size
+
+  overlay-buttons:
+    description: list of nodes defining the buttons on the touchscreen
+
+      This object can be used to describe buttons on the touchscreen area,
+      reporting the touch events on their surface as key events instead of
+      the original touch events.
+
+      This is of special interest if the touchscreen is shipped with a
+      physical overlay on top of it where a number of buttons with some
+      predefined functionality are printed. In that case a specific behavior
+      is expected from those buttons instead of raw touch events.
+
+      The overlay-buttons properties define a per-button area as well as an
+      origin relative to the real touchscreen origin. Touch events within the
+      button area are reported as the key event defined in the linux,code
+      property. Given that the key events do not provide coordinates, the
+      button origin is only used to place the button area on the touchscreen
+      surface. Any event outside the overlay-buttons object is reported as a
+      touch event with no coordinate transformation.
+
+      The following example shows a touchscreen with a single button on it
+
+              Touchscreen (full area)
+        ┌───────────────────────────────────┐
+        │                                   │
+        │                                   │
+        │   ┌─────────┐                     │
+        │   │button 0 │                     │
+        │   │KEY_POWER│                     │
+        │   └─────────┘                     │
+        │                                   │
+        │                                   │
+       ┌└───────────────────────────────────┘
+     (0,0)
+
+      The overlay-buttons object can  be combined with the overlay-touchscreen
+      object as shown in the following example. In that case only the events
+      within the overlay-touchscreen object are reported as touch events.
+
+                  Touchscreen (full area)
+        ┌─────────┬──────────────────────────────┐
+        │         │                              │
+        │         │    ┌───────────────────────┐ │
+        │ button 0│    │                       │ │
+        │KEY_POWER│    │                       │ │
+        │         │    │                       │ │
+        ├─────────┤    │  overlay-touchscreen  │ │
+        │         │    │                       │ │
+        │         │    │                       │ │
+        │ button 1│    │                       │ │
+        │ KEY_INFO│   ┌└───────────────────────┘ │
+        │         │(0',0')                       │
+       ┌└─────────┴──────────────────────────────┘
+     (0,0)
+
+    type: object
+
+    patternProperties:
+      '^button-':
+        type: object
+        description:
+          Each button (key) is represented as a sub-node.
+
+        properties:
+          label:
+            $ref: /schemas/types.yaml#/definitions/string
+            description: descriptive name of the button
+
+          linux,code: true
+
+          x-origin:
+            description: horizontal origin of the button area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          y-origin:
+            description: vertical origin of the button area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          x-size:
+            description: horizontal resolution of the button area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+          y-size:
+            description: vertical resolution of the button area
+            $ref: /schemas/types.yaml#/definitions/uint32
+
+        required:
+          - linux,code
+          - x-origin
+          - y-origin
+          - x-size
+          - y-size
+
 dependencies:
   touchscreen-size-x: [ touchscreen-size-y ]
   touchscreen-size-y: [ touchscreen-size-x ]