Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit 233b213a authored by Nick Dyer's avatar Nick Dyer Committed by Mauro Carvalho Chehab
Browse files

[media] Documentation: add support for V4L touch devices 



Document the new touch API.

Signed-off-by: default avatarNick Dyer <nick@shmanahar.org>
Signed-off-by: default avatarHans Verkuil <hans.verkuil@cisco.com>
[hans.verkuil@cisco.com: fix up videodev2.h.rst.exceptions]

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab@s-opensource.com>
Acked-by: default avatarDmitry Torokhov <dmitry.torokhov@gmail.com>
parent b4972652

Documentation/media/uapi/mediactl/media-types.rst

+17 −7
Original line number Diff line number Diff line
@@ -437,6 +437,16 @@ Types and flags used to represent the media graph elements 


    -  .. row 11



       ..  _MEDIA-INTF-T-V4L-TOUCH:



       -  ``MEDIA_INTF_T_V4L_TOUCH``



       -  Device node interface for Touch device (V4L)



       -  typically, /dev/v4l-touch?



    -  .. row 12



       ..  _MEDIA-INTF-T-ALSA-PCM-CAPTURE:



       -  ``MEDIA_INTF_T_ALSA_PCM_CAPTURE``
@@ -445,7 +455,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/pcmC?D?c



    -  .. row 12

    -  .. row 13



       ..  _MEDIA-INTF-T-ALSA-PCM-PLAYBACK:
@@ -455,7 +465,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/pcmC?D?p



    -  .. row 13

    -  .. row 14



       ..  _MEDIA-INTF-T-ALSA-CONTROL:
@@ -465,7 +475,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/controlC?



    -  .. row 14

    -  .. row 15



       ..  _MEDIA-INTF-T-ALSA-COMPRESS:
@@ -475,7 +485,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/compr?



    -  .. row 15

    -  .. row 16



       ..  _MEDIA-INTF-T-ALSA-RAWMIDI:
@@ -485,7 +495,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/midi?



    -  .. row 16

    -  .. row 17



       ..  _MEDIA-INTF-T-ALSA-HWDEP:
@@ -495,7 +505,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/hwC?D?



    -  .. row 17

    -  .. row 18



       ..  _MEDIA-INTF-T-ALSA-SEQUENCER:
@@ -505,7 +515,7 @@ Types and flags used to represent the media graph elements 


       -  typically, /dev/snd/seq



    -  .. row 18

    -  .. row 19



       ..  _MEDIA-INTF-T-ALSA-TIMER:

Documentation/media/uapi/v4l/dev-touch.rst

0 → 100644
+56 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _touch:



*************

Touch Devices

*************



Touch devices are accessed through character device special files named

``/dev/v4l-touch0`` to ``/dev/v4l-touch255`` with major number 81 and

dynamically allocated minor numbers 0 to 255.



Overview

========



Sensors may be Optical, or Projected Capacitive touch (PCT).



Processing is required to analyse the raw data and produce input events. In

some systems, this may be performed on the ASIC and the raw data is purely a

side-channel for diagnostics or tuning. In other systems, the ASIC is a simple

analogue front end device which delivers touch data at high rate, and any touch

processing must be done on the host.



For capacitive touch sensing, the touchscreen is composed of an array of

horizontal and vertical conductors (alternatively called rows/columns, X/Y

lines, or tx/rx). Mutual Capacitance measured is at the nodes where the

conductors cross. Alternatively, Self Capacitance measures the signal from each

column and row independently.



A touch input may be determined by comparing the raw capacitance measurement to

a no-touch reference (or "baseline") measurement:



Delta = Raw - Reference



The reference measurement takes account of variations in the capacitance across

the touch sensor matrix, for example manufacturing irregularities,

environmental or edge effects.



Querying Capabilities

=====================



Devices supporting the touch interface set the ``V4L2_CAP_VIDEO_CAPTURE`` flag

and the ``V4L2_CAP_TOUCH`` flag in the ``capabilities`` field of

:ref:`v4l2_capability <v4l2-capability>` returned by the

:ref:`VIDIOC_QUERYCAP` ioctl.



At least one of the read/write or streaming I/O methods must be

supported.



The formats supported by touch devices are documented in

:ref:`Touch Formats <tch-formats>`.



Data Format Negotiation

=======================



A touch device may support any I/O method.

Documentation/media/uapi/v4l/devices.rst

+1 −0
Original line number Diff line number Diff line
@@ -22,5 +22,6 @@ Interfaces 
    dev-radio

    dev-rds

    dev-sdr

    dev-touch

    dev-event

    dev-subdev

Documentation/media/uapi/v4l/pixfmt-tch-td08.rst

0 → 100644
+80 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _V4L2-TCH-FMT-DELTA-TD08:



********************************

V4L2_TCH_FMT_DELTA_TD08 ('TD08')

********************************



*man V4L2_TCH_FMT_DELTA_TD08(2)*



8-bit signed Touch Delta



Description

===========



This format represents delta data from a touch controller.



Delta values may range from -128 to 127. Typically the values will vary through

a small range depending on whether the sensor is touched or not. The full value

may be seen if one of the touchscreen nodes has a fault or the line is not

connected.



**Byte Order.**

Each cell is one byte.







.. flat-table::

    :header-rows:  0

    :stub-columns: 0

    :widths:       2 1 1 1 1





    -  .. row 1



       -  start + 0:



       -  D'\ :sub:`00`



       -  D'\ :sub:`01`



       -  D'\ :sub:`02`



       -  D'\ :sub:`03`



    -  .. row 2



       -  start + 4:



       -  D'\ :sub:`10`



       -  D'\ :sub:`11`



       -  D'\ :sub:`12`



       -  D'\ :sub:`13`



    -  .. row 3



       -  start + 8:



       -  D'\ :sub:`20`



       -  D'\ :sub:`21`



       -  D'\ :sub:`22`



       -  D'\ :sub:`23`



    -  .. row 4



       -  start + 12:



       -  D'\ :sub:`30`



       -  D'\ :sub:`31`



       -  D'\ :sub:`32`



       -  D'\ :sub:`33`

Documentation/media/uapi/v4l/pixfmt-tch-td16.rst

0 → 100644
+111 −0
Original line number Diff line number Diff line 
.. -*- coding: utf-8; mode: rst -*-



.. _V4L2-TCH-FMT-DELTA-TD16:



********************************

V4L2_TCH_FMT_DELTA_TD16 ('TD16')

********************************



*man V4L2_TCH_FMT_DELTA_TD16(2)*



16-bit signed Touch Delta





Description

===========



This format represents delta data from a touch controller.



Delta values may range from -32768 to 32767. Typically the values will vary

through a small range depending on whether the sensor is touched or not. The

full value may be seen if one of the touchscreen nodes has a fault or the line

is not connected.



**Byte Order.**

Each cell is one byte.



.. flat-table::

    :header-rows:  0

    :stub-columns: 0

    :widths:       2 1 1 1 1 1 1 1 1





    -  .. row 1



       -  start + 0:



       -  D'\ :sub:`00high`



       -  D'\ :sub:`00low`



       -  D'\ :sub:`01high`



       -  D'\ :sub:`01low`



       -  D'\ :sub:`02high`



       -  D'\ :sub:`02low`



       -  D'\ :sub:`03high`



       -  D'\ :sub:`03low`



    -  .. row 2



       -  start + 8:



       -  D'\ :sub:`10high`



       -  D'\ :sub:`10low`



       -  D'\ :sub:`11high`



       -  D'\ :sub:`11low`



       -  D'\ :sub:`12high`



       -  D'\ :sub:`12low`



       -  D'\ :sub:`13high`



       -  D'\ :sub:`13low`



    -  .. row 3



       -  start + 16:



       -  D'\ :sub:`20high`



       -  D'\ :sub:`20low`



       -  D'\ :sub:`21high`



       -  D'\ :sub:`21low`



       -  D'\ :sub:`22high`



       -  D'\ :sub:`22low`



       -  D'\ :sub:`23high`



       -  D'\ :sub:`23low`



    -  .. row 4



       -  start + 24:



       -  D'\ :sub:`30high`



       -  D'\ :sub:`30low`



       -  D'\ :sub:`31high`



       -  D'\ :sub:`31low`



       -  D'\ :sub:`32high`



       -  D'\ :sub:`32low`



       -  D'\ :sub:`33high`



       -  D'\ :sub:`33low`