Merge branch 'linux-4.21' of git://github.com/skeggsb/linux into drm-fixes
[sfrench/cifs-2.6.git] / Documentation / media / uapi / v4l / dev-touch.rst
1 .. Permission is granted to copy, distribute and/or modify this
2 .. document under the terms of the GNU Free Documentation License,
3 .. Version 1.1 or any later version published by the Free Software
4 .. Foundation, with no Invariant Sections, no Front-Cover Texts
5 .. and no Back-Cover Texts. A copy of the license is included at
6 .. Documentation/media/uapi/fdl-appendix.rst.
7 ..
8 .. TODO: replace it to GFDL-1.1-or-later WITH no-invariant-sections
9
10 .. _touch:
11
12 *************
13 Touch Devices
14 *************
15
16 Touch devices are accessed through character device special files named
17 ``/dev/v4l-touch0`` to ``/dev/v4l-touch255`` with major number 81 and
18 dynamically allocated minor numbers 0 to 255.
19
20 Overview
21 ========
22
23 Sensors may be Optical, or Projected Capacitive touch (PCT).
24
25 Processing is required to analyse the raw data and produce input events. In
26 some systems, this may be performed on the ASIC and the raw data is purely a
27 side-channel for diagnostics or tuning. In other systems, the ASIC is a simple
28 analogue front end device which delivers touch data at high rate, and any touch
29 processing must be done on the host.
30
31 For capacitive touch sensing, the touchscreen is composed of an array of
32 horizontal and vertical conductors (alternatively called rows/columns, X/Y
33 lines, or tx/rx). Mutual Capacitance measured is at the nodes where the
34 conductors cross. Alternatively, Self Capacitance measures the signal from each
35 column and row independently.
36
37 A touch input may be determined by comparing the raw capacitance measurement to
38 a no-touch reference (or "baseline") measurement:
39
40 Delta = Raw - Reference
41
42 The reference measurement takes account of variations in the capacitance across
43 the touch sensor matrix, for example manufacturing irregularities,
44 environmental or edge effects.
45
46 Querying Capabilities
47 =====================
48
49 Devices supporting the touch interface set the ``V4L2_CAP_VIDEO_CAPTURE`` flag
50 and the ``V4L2_CAP_TOUCH`` flag in the ``capabilities`` field of
51 :c:type:`v4l2_capability` returned by the
52 :ref:`VIDIOC_QUERYCAP` ioctl.
53
54 At least one of the read/write or streaming I/O methods must be
55 supported.
56
57 The formats supported by touch devices are documented in
58 :ref:`Touch Formats <tch-formats>`.
59
60 Data Format Negotiation
61 =======================
62
63 A touch device may support any I/O method.