Touch Device Driver Requirements

 转自：http://source.android.com/tech/input/touch-devices.html

Touch Device Driver Requirements

1. Touch device drivers should only register axes and key codes for the axes and buttons that they actually support. Registering excess axes or key codes may confuse the device classification algorithm or cause the system to incorrectly detect the capabilities of the device.

   For example, if the device reports the BTN_TOUCH key code, the system will assume thatBTN_TOUCH will always be used to indicate whether the tool is actually touching the screen or is merely in range and hovering.

2. Single-touch devices use the following Linux input events:

   • ABS_X: (REQUIRED) Reports the X coordinate of the tool.

   • ABS_Y: (REQUIRED) Reports the Y coordinate of the tool.

   • ABS_PRESSURE: (optional) Reports the physical pressure applied to the tip of the tool or the signal strength of the touch contact.

   • ABS_TOOL_WIDTH: (optional) Reports the cross-sectional area or width of the touch contact or of the tool itself.

   • ABS_DISTANCE: (optional) Reports the distance of the tool from the surface of the touch device.

   • ABS_TILT_X: (optional) Reports the tilt of the tool from the surface of the touch device along the X axis.

   • ABS_TILT_Y: (optional) Reports the tilt of the tool from the surface of the touch device along the Y axis.

   • BTN_TOUCH: (REQUIRED) Indicates whether the tool is touching the device.

   • BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_BACK, BTN_SIDE, BTN_FORWARD, BTN_EXTRA,BTN_STYLUS, BTN_STYLUS2: (optional) Reports button states.

   • BTN_TOOL_FINGER, BTN_TOOL_PEN, BTN_TOOL_RUBBER,BTN_TOOL_BRUSH, BTN_TOOL_PENCIL, BTN_TOOL_AIRBRUSH,BTN_TOOL_MOUSE, BTN_TOOL_LENS, BTN_TOOL_DOUBLETAP,BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: (optional) Reports thetool type.

3. Multi-touch devices use the following Linux input events:

   • ABS_MT_POSITION_X: (REQUIRED) Reports the X coordinate of the tool.

   • ABS_MT_POSITION_Y: (REQUIRED) Reports the Y coordinate of the tool.

   • ABS_MT_PRESSURE: (optional) Reports the physical pressure applied to the tip of the tool or the signal strength of the touch contact.

   • ABS_MT_TOUCH_MAJOR: (optional) Reports the cross-sectional area of the touch contact, or the length of the longer dimension of the touch contact.

   • ABS_MT_TOUCH_MINOR: (optional) Reports the length of the shorter dimension of the touch contact. This axis should not be used ifABS_MT_TOUCH_MAJOR is reporting an area measurement.

   • ABS_MT_WIDTH_MAJOR: (optional) Reports the cross-sectional area of the tool itself, or the length of the longer dimension of the tool itself. This axis should not be used if the dimensions of the tool itself are unknown.

   • ABS_MT_WIDTH_MINOR: (optional) Reports the length of the shorter dimension of the tool itself. This axis should not be used ifABS_MT_WIDTH_MAJOR is reporting an area measurement or if the dimensions of the tool itself are unknown.

   • ABS_MT_ORIENTATION: (optional) Reports the orientation of the tool.

   • ABS_MT_DISTANCE: (optional) Reports the distance of the tool from the surface of the touch device.

   • ABS_MT_TOOL_TYPE: (optional) Reports the tool type as MT_TOOL_FINGER or MT_TOOL_PEN.

   • ABS_MT_TRACKING_ID: (optional) Reports the tracking id of the tool. The tracking id is an arbitrary non-negative integer that is used to identify and track each tool independently when multiple tools are active. For example, when multiple fingers are touching the device, each finger should be assigned a distinct tracking id that is used as long as the finger remains in contact. Tracking ids may be reused when their associated tools move out of range.

   • ABS_MT_SLOT: (optional) Reports the slot id of the tool, when using the Linux multi-touch protocol 'B'. Refer to the Linux multi-touch protocol documentation for more details.

   • BTN_TOUCH: (REQUIRED) Indicates whether the tool is touching the device.

   • BTN_LEFT, BTN_RIGHT, BTN_MIDDLE, BTN_BACK, BTN_SIDE, BTN_FORWARD, BTN_EXTRA,BTN_STYLUS, BTN_STYLUS2: (optional) Reports button states.

   • BTN_TOOL_FINGER, BTN_TOOL_PEN, BTN_TOOL_RUBBER,BTN_TOOL_BRUSH, BTN_TOOL_PENCIL, BTN_TOOL_AIRBRUSH,BTN_TOOL_MOUSE, BTN_TOOL_LENS, BTN_TOOL_DOUBLETAP,BTN_TOOL_TRIPLETAP, BTN_TOOL_QUADTAP: (optional) Reports thetool type.

4. If axes for both the single-touch and multi-touch protocol are defined, then only the multi-touch axes will be used and the single-touch axes will be ignored.

5. The minimum and maximum values of the ABS_X, ABS_Y, ABS_MT_POSITION_X and ABS_MT_POSITION_Y axes define the bounds of the active area of the device in device-specific surface units. In the case of a touch screen, the active area describes the part of the touch device that actually covers the display.

   For a touch screen, the system automatically interpolates the reported touch positions in surface units to obtain touch positions in display pixels according to the following calculation:

   displayX = (x - minX) * displayWidth / (maxX - minX + 1)displayY = (y - minY) * displayHeight / (maxY - minY + 1)

   A touch screen may report touches outside of the reported active area.

   Touches that are initiated outside the active area are not delivered to applications but may be used for virtual keys.

   Touches that are initiated inside the active area, or that enter and exit the display area are delivered to applications. Consequently, if a touch starts within the bounds of an application and then moves outside of the active area, the application may receive touch events with display coordinates that are negative or beyond the bounds of the display. This is expected behavior.

   A touch device should never clamp touch coordinates to the bounds of the active area. If a touch exits the active area, it should be reported as being outside of the active area, or it should not be reported at all.

   For example, if the user's finger is touching near the top-left corner of the touch screen, it may report a coordinate of (minX, minY). If the finger continues to move further outside of the active area, the touch screen should either start reporting coordinates with components less than minX and minY, such as (minX - 2, minY - 3), or it should stop reporting the touch altogether. In other words, the touch screen shouldnot be reporting (minX, minY) when the user's finger is really touching outside of the active area.

   Clamping touch coordinates to the display edge creates an artificial hard boundary around the edge of the screen which prevents the system from smoothly tracking motions that enter or exit the bounds of the display area.

6. The values reported by ABS_PRESSURE or ABS_MT_PRESSURE, if they are reported at all, must be non-zero when the tool is touching the device and zero otherwise to indicate that the tool is hovering.

   Reporting pressure information is optional but strongly recommended. Applications can use pressure information to implement pressure-sensitive drawing and other effects.

7. The values reported by ABS_TOOL_WIDTH, ABS_MT_TOUCH_MAJOR,ABS_MT_TOUCH_MINOR, ABS_MT_WIDTH_MAJOR, or ABS_MT_WIDTH_MINOR should be non-zero when the tool is touching the device and zero otherwise, but this is not required. For example, the touch device may be able to measure the size of finger touch contacts but not stylus touch contacts.

   Reporting size information is optional but strongly recommended. Applications can use pressure information to implement size-sensitive drawing and other effects.

8. The values reported by ABS_DISTANCE or ABS_MT_DISTANCE should approach zero when the tool is touching the device. The distance may remain non-zero even when the tool is in direct contact. The exact values reported depend on the manner in which the hardware measures distance.

   Reporting distance information is optional but recommended for stylus devices.

9. The values reported by ABS_TILT_X and ABS_TILT_Y should be zero when the tool is perpendicular to the device. A non-zero tilt is taken as an indication that the tool is held at an incline.

   The tilt angles along the X and Y axes are assumed to be specified in degrees from perpendicular. The center point (perfectly perpendicular) is given by(max + min) / 2 for each axis. Values smaller than the center point represent a tilt up or to the left, values larger than the center point represent a tilt down or to the right.

   The InputReader converts the X and Y tilt components into a perpendicular tilt angle ranging from 0 toPI / 2 radians and a planar orientation angle ranging from -PI toPI radians. This representation results in a description of orientation that is compatible with what is used to describe finger touches.

   Reporting tilt information is optional but recommended for stylus devices.

10. If the tool type is reported by ABS_MT_TOOL_TYPE, it will supercede any tool type information reported byBTN_TOOL_*. If no tool type information is available at all, the tool type defaults toMotionEvent.TOOL_TYPE_FINGER.

11. A tool is determined to be active based on the following conditions:

    • When using the single-touch protocol, the tool is active if BTN_TOUCH, orBTN_TOOL_* is 1.

      This condition implies that the InputReader needs to have at least some information about the nature of the tool, either whether it is touching, or at least its tool type. If no information is available, then the tool is assumed to be inactive (out of range).

    • When using the multi-touch protocol 'A', the tool is active whenever it appears in the most recent sync report. When the tool stops appearing in sync reports, it ceases to exist.

    • When using the multi-touch protocol 'B', the tool is active as long as it has an active slot. When the slot it cleared, the tool ceases to exist.

12. A tool is determined to be hovering based on the following conditions:

    • If the tool is BTN_TOOL_MOUSE or BTN_TOOL_LENS, then the tool is not hovering, even if either of the following conditions are true.

    • If the tool is active and the driver reports pressure information, and the reported pressure is zero, then the tool is hovering.

    • If the tool is active and the driver supports the BTN_TOUCH key code andBTN_TOUCH has a value of zero, then the tool is hovering.

13. The InputReader supports both multi-touch protocol 'A' and 'B'. New drivers should use the 'B' protocol but either will work.

14. As of Android Ice Cream Sandwich 4.0, touch screen drivers may need to be changed to comply with the Linux input protocol specification.

    The following changes may be required:

    • When a tool becomes inactive (finger goes "up"), it should stop appearing in subsequent multi-touch sync reports. When all tools become inactive (all fingers go "up"), the driver should send an empty sync report packet, such asSYN_MT_REPORT followed by SYN_REPORT.

      Previous versions of Android expected "up" events to be reported by sending a pressure value of 0. The old behavior was incompatible with the Linux input protocol specification and is no longer supported.

    • Physical pressure or signal strength information should be reported using ABS_MT_PRESSURE.

      Previous versions of Android retrieved pressure information from ABS_MT_TOUCH_MAJOR. The old behavior was incompatible with the Linux input protocol specification and is no longer supported.

    • Touch size information should be reported using ABS_MT_TOUCH_MAJOR.

      Previous versions of Android retrieved size information from ABS_MT_TOOL_MAJOR. The old behavior was incompatible with the Linux input protocol specification and is no longer supported.

    Touch device drivers no longer need Android-specific customizations. By relying on the standard Linux input protocol, Android can support a wider variety of touch peripherals, such as external HID multi-touch touch screens, using unmodified drivers.