1# Input Coordinate Processing in InputFlinger 2 3This document aims to illustrate why we need to take care when converting 4between the discrete and continuous coordinate spaces, especially when 5performing rotations. 6 7The Linux evdev protocol works over **discrete integral** values. The same is 8true for displays, which output discrete pixels. WindowManager also tracks 9window bounds in pixels in the rotated logical display. 10 11However, our `MotionEvent` APIs 12report **floating point** axis values in a **continuous space**. This disparity 13is important to note when working in InputFlinger, which has to make sure the 14discrete raw coordinates are converted to the continuous space correctly in all 15scenarios. 16 17## Disparity between continuous and discrete coordinates during rotation 18 19Let's consider an example of device that has a 3 x 4 screen. 20 21### Natural orientation: No rotation 22 23If the user interacts with the highlighted pixel, the touchscreen would report 24the discreet coordinates (0, 2). 25 26``` 27 ┌─────┬─────┬─────┐ 28 │ 0,0 │ 1,0 │ 2,0 │ 29 ├─────┼─────┼─────┤ 30 │ 0,1 │ 1,1 │ 2,1 │ 31 ├─────┼─────┼─────┤ 32 │█0,2█│ 1,2 │ 2,2 │ 33 ├─────┼─────┼─────┤ 34 │ 0,3 │ 1,3 │ 2,3 │ 35 └─────┴─────┴─────┘ 36``` 37 38When converted to the continuous space, the point (0, 2) corresponds to the 39location shown below. 40 41``` 42 0 1 2 3 43 0 ┌─────┬─────┬─────┐ 44 │ │ │ │ 45 1 ├─────┼─────┼─────┤ 46 │ │ │ │ 47 2 █─────┼─────┼─────┤ 48 │ │ │ │ 49 3 ├─────┼─────┼─────┤ 50 │ │ │ │ 51 4 └─────┴─────┴─────┘ 52``` 53 54### Rotated orientation: 90-degree counter-clockwise rotation 55 56When the device is rotated and the same place on the touchscreen is touched, the 57input device will still report the same coordinates of (0, 2). 58 59In the rotated display, that now corresponds to the pixel (2, 2). 60 61``` 62 ┌─────┬─────┬─────┬─────┐ 63 │ 0,0 │ 1,0 │ 2,0 │ 3,0 │ 64 ├─────┼─────┼─────┼─────┤ 65 │ 0,1 │ 1,1 │ 2,1 │ 3,1 │ 66 ├─────┼─────┼─────┼─────┤ 67 │ 0,2 │ 1,2 │█2,2█│ 3,2 │ 68 └─────┴─────┴─────┴─────┘ 69``` 70 71*It is important to note that rotating the device 90 degrees is NOT equivalent 72to rotating the continuous coordinate space by 90 degrees.* 73 74The point (2, 2) now corresponds to a different location in the continuous space 75than before, even though the user was interacting at the same place on the 76touchscreen. 77 78``` 79 0 1 2 3 4 80 0 ┌─────┬─────┬─────┬─────┐ 81 │ │ │ │ │ 82 1 ├─────┼─────┼─────┼─────┤ 83 │ │ │ │ │ 84 2 ├─────┼─────█─────┼─────┤ 85 │ │ │ │ │ 86 3 └─────┴─────┴─────┴─────┘ 87``` 88 89If we were to simply (incorrectly) rotate the continuous space from before by 9090 degrees, the touched point would correspond to the location (2, 3), shown 91below. This new point is outside the bounds of the display, since it does not 92correspond to any pixel at that location. 93 94It should be impossible for a touchscreen to generate points outside the bounds 95of the display, because we assume that the area of the touchscreen maps directly 96to the area of the display. Therefore, that point is an invalid coordinate that 97cannot be generated by an input device. 98 99``` 100 0 1 2 3 4 101 0 ┌─────┬─────┬─────┬─────┐ 102 │ │ │ │ ╏ 103 1 ├─────┼─────┼─────┼─────┤ 104 │ │ │ │ ╏ 105 2 ├─────┼─────┼─────┼─────┤ 106 │ │ │ │ ╏ 107 3 └-----┴-----█-----┴-----┘ 108``` 109 110The same logic applies to windows as well. When performing hit tests to 111determine if a point in the continuous space falls inside a window's bounds, 112hit test must be performed in the correct orientation, since points on the right 113and bottom edges of the window do not fall within the window bounds. 114