Re: [PATCH v7 1/4] dt-bindings: touchscreen: add touch-overlay property

[Javier Carrasco <javier.carrasco@wolfvision.net>]

On 1/19/24 08:43, Javier Carrasco wrote:
> The touch-overlay encompasses a number of touch areas that define a
> clipped touchscreen area and/or buttons with a specific functionality.
> 
> A clipped touchscreen area avoids getting events from regions that are
> physically hidden by overlay frames.
> 
> For touchscreens with printed overlay buttons, sub-nodes with a suitable
> key code can be defined to report key events instead of the original
> touch events.
> 
> Reviewed-by: Jeff LaBundy <jeff@labundy.com>
> Reviewed-by: Rob Herring <robh@kernel.org>
> Signed-off-by: Javier Carrasco <javier.carrasco@wolfvision.net>
> ---
>  .../bindings/input/touchscreen/touchscreen.yaml    | 119 +++++++++++++++++++++
>  1 file changed, 119 insertions(+)
> 
> diff --git a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> index 431c13335c40..eb1e86fa86c6 100644
> --- a/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> +++ b/Documentation/devicetree/bindings/input/touchscreen/touchscreen.yaml
> @@ -87,6 +87,125 @@ properties:
>    touchscreen-y-plate-ohms:
>      description: Resistance of the Y-plate in Ohms
>  
> +  touch-overlay:

Even though it has already been reviewed, just in case before it gets
applied. Should it not be:

	description: |
	  List of nodes...

instead, to keep formatting?

> +    description: list of nodes defining segments (touch areas) on the
> +      touchscreen.
> +
> +      This object can be used to describe a series of segments to
> +      restrict the region within touch events are reported or buttons
> +      with a specific functionality.
> +
> +      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. Printed buttons on that overlay are also a typical
> +      use case.
> +
> +      A new touchscreen area is defined as a sub-node without a key code. If a
> +      key code is defined in the sub-node, it will be interpreted as a button.
> +
> +      The x-origin and y-origin properties of a touchscreen area 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 touchscreen effective area.
> +
> +      The following example shows a new touchscreen area with the new origin
> +      (0',0') for the touch events generated by the device.
> +
> +                   Touchscreen (full area)
> +         ┌────────────────────────────────────────┐
> +         │    ┌───────────────────────────────┐   │
> +         │    │                               │   │
> +         │    ├ y-size                        │   │
> +         │    │                               │   │
> +         │    │       touchscreen area        │   │
> +         │    │         (no key code)         │   │
> +         │    │                               │   │
> +         │    │            x-size             │   │
> +         │   ┌└──────────────┴────────────────┘   │
> +         │(0',0')                                 │
> +        ┌└────────────────────────────────────────┘
> +      (0,0)
> +

When at it, the following line could be aligned to match the rest of the
description.

> +     where (0',0') = (0+x-origin,0+y-origin)
> +
> +      Sub-nodes with key codes report the touch events on their surface as key
> +      events instead.
> +
> +      The following example shows a touchscreen with a single button on it.
> +
> +              Touchscreen (full area)
> +        ┌───────────────────────────────────┐
> +        │                                   │
> +        │                                   │
> +        │   ┌─────────┐                     │
> +        │   │button 0 │                     │
> +        │   │KEY_POWER│                     │
> +        │   └─────────┘                     │
> +        │                                   │
> +        │                                   │
> +       ┌└───────────────────────────────────┘
> +     (0,0)
> +

And the origin above too.

> +      Segments defining buttons and clipped toushcreen areas can be combined
> +      as shown in the following example.
> +      In that case only the events within the touchscreen area are reported
> +      as touch events. Events within the button areas report their associated
> +      key code. Any events outside the defined areas are ignored.
> +
> +                  Touchscreen (full area)
> +        ┌─────────┬──────────────────────────────┐
> +        │         │                              │
> +        │         │    ┌───────────────────────┐ │
> +        │ button 0│    │                       │ │
> +        │KEY_POWER│    │                       │ │
> +        │         │    │                       │ │
> +        ├─────────┤    │   touchscreen area    │ │
> +        │         │    │     (no key code)     │ │
> +        │         │    │                       │ │
> +        │ button 1│    │                       │ │
> +        │ KEY_INFO│   ┌└───────────────────────┘ │
> +        │         │(0',0')                       │
> +       ┌└─────────┴──────────────────────────────┘
> +     (0,0)
> +

Same with this one.

> +    type: object
> +

Best regards,
Javier Carrasco