Test/Library/PackageCache/com.unity.inputsystem@2436e68c60c4/Documentation~/touch-introduction.md

uid

uid
input-system-touch-devices-intro

Touch devices introduction

You can receive and process touch input from touch devices with the following APIs:

• High-level support implemented in the EnhancedTouch.Touch class. This class provides in-built functionality for finger and touch information, and you can also use it for polling touch input.
• Low-level support implemented in the Touchscreen class. Use this class to implement custom functionality that EnhancedTouch.Touch doesn't have.

For a list of platforms that support touch devices, refer to Supported devices reference.

High-level touch support

The EnhancedTouch.Touch API provides access to touch information along two dimensions:

• By finger: Each finger is defined as the Nth contact source on a Touchscreen. Use Touch.activeFingers to get an array of all currently active fingers.
• By touch: Each touch is a single finger contact with at least a beginning point (PointerPhase.Began) and an endpoint (PointerPhase.Ended or PointerPhase.Cancelled). Between those two points, an arbitrary number of PointerPhase.Moved or PointerPhase.Stationary records exist. All records in a touch have the same touchId. You can use Touch.activeTouches to get an array of all currently active touches. This lets you track how a specific touch moves over the screen, which is useful if you want to implement recognition of specific gestures.

Refer to the EnhancedTouch.Touch API documentation for more information.

Note

The Touch and Finger APIs don't allocate managed memory, and therefore don't cause garbage collection. The bulk of the data is stored in unmanaged memory that's indexed by wrapper structs. All arrays are pre-allocated.

Low-level touch support

At the lowest level, a touch screen is represented by an InputSystem.Touchscreen device which captures the touchscreen's raw state. Touch screens are based on the pointer layout, and they implement some additional controls outlined in the Touchscreen API documentation.

To query the touch screen that was last used or last added, use Touchscreen.current.

API controls

A touch screen device consists of multiple TouchControl instances. Each of these represents a finger which is touching the device. The primaryTouch control represents the touch which is currently driving the pointer representation, and which should be used to interact with the UI.

The primaryTouch control usually represents the first finger that touches the screen and is always identical to one of the entries in the touches array. The touches array contains all the touches that the system can track. This array has a fixed size, regardless of how many touches are currently active. If you need an API that only represents active touches, refer to the higher-level EnhancedTouch.Touch class.

Testing touch devices

To test your app on iOS or Android in the unity Editor with touch input from your mobile device, use the Unity Remote.