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@xxxxxxxxxxxxxx>
> ---
> .../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
