Struct Touch

A high-level representation of a touch which automatically keeps track of a touch over time.

Implements
Namespace: UnityEngine.InputSystem.EnhancedTouch
Assembly: Unity.InputSystem.dll
Syntax
public struct Touch : IEquatable<Touch>
Remarks

This API obsoletes the need for manually keeping tracking of touch IDs (touchId) and touch phases (phase) in order to tell one touch apart from another.

Also, this class protects against losing touches. If a touch is shorter-lived than a single input update, Touchscreen may overwrite it with a new touch coming in in the same update whereas this class will retain all changes that happened on the touchscreen in any particular update.

The API makes a distinction between "fingers" and "touches". A touch refers to one contact state change event, that is, a finger beginning to touch the screen (Began), moving on the screen (Moved), or being lifted off the screen (Ended or Canceled). A finger, on the other hand, always refers to the Nth contact on the screen.

A Touch instance is a struct which only contains a reference to the actual data which is stored in unmanaged memory.

Properties

activeFingers

Set of currently active fingers, i.e. touch contacts that currently have an active touch (as defined by activeTouches).

Declaration
public static ReadOnlyArray<Finger> activeFingers { get; }
Property Value
Type Description
ReadOnlyArray<Finger>
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

activeTouches

All touches that are either on-going as of the current frame or have ended in the current frame.

Declaration
public static ReadOnlyArray<Touch> activeTouches { get; }
Property Value
Type Description
ReadOnlyArray<Touch>
Remarks

A touch that begins in a frame will always have its phase set to Began even if there was also movement (or even an end/cancellation) for the touch in the same frame.

A touch that begins and ends in the same frame will have its Began surface in that frame and then another entry with Ended surface in the next frame. This logic implies that there can be more active touches than concurrent touches supported by the hardware/platform.

A touch that begins and moves in the same frame will have its Began surface in that frame and then another entry with Moved and the screen motion surface in the next frame except if the touch also ended in the frame (in which case phase will be Ended instead of Moved).

Note that the touches reported by this API do not necessarily have to match the contents of UnityEngine.Input.touches. The reason for this is that the UnityEngine.Input API and the Input System API flush their input queues at different points in time and may thus have a different view on available input. In particular, the Input System event queue is flushed later in the frame than inputs for UnityEngine.Input and may thus have newer inputs available. On Android, for example, touch input is gathered from a separate UI thread and fed into the input system via a "background" event queue that can gather input asynchronously. Due to this setup, touch events that will reach UnityEngine.Input only in the next frame may have already reached the Input System.

void Awake()
{
    // Enable EnhancedTouch.
    EnhancedTouchSupport.Enable();
}

void Update()
{
foreach (var touch in Touch.activeTouches)
if (touch.began)
Debug.Log($"Touch {touch} started this frame");
else if (touch.ended)
Debug.Log($"Touch {touch} ended this frame");
}
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

began

Whether the touch has begun this frame, i.e. whether phase is Began.

Declaration
public bool began { get; }
Property Value
Type Description
bool
See Also

delta

Screen-space motion delta of the touch.

Declaration
public Vector2 delta { get; }
Property Value
Type Description
Vector2

Screen-space motion delta of the touch.
Remarks

Note that deltas have behaviors attached to them different from most other controls. See delta for details.

See Also

displayIndex

The index of the display containing the touch.

Declaration
public int displayIndex { get; }
Property Value
Type Description
int

A zero based number representing the display index containing the touch.
See Also

ended

Whether the touch has ended this frame, i.e. whether phase is either Ended or Canceled.

Declaration
public bool ended { get; }
Property Value
Type Description
bool
See Also

finger

The finger used for the touch contact. Null only for default-initialized instances of the struct.

Declaration
public Finger finger { get; }
Property Value
Type Description
Finger

Finger used for the touch contact.
See Also

fingers

An array of all possible concurrent touch contacts, i.e. all concurrent touch contacts regardless of whether they are currently active or not.

Declaration
public static ReadOnlyArray<Finger> fingers { get; }
Property Value
Type Description
ReadOnlyArray<Finger>
Remarks

For querying only active fingers, use activeFingers.

The length of this array will always correspond to the maximum number of concurrent touches supported by the system. Note that the actual number of physically supported concurrent touches as determined by the current hardware and operating system may be lower than this number.

Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

history

History for this specific touch.

Declaration
public TouchHistory history { get; }
Property Value
Type Description
TouchHistory
Remarks

Unlike touchHistory, this gives the history of this touch only.

inProgress

Whether the touch is currently in progress, i.e. whether phase is either Moved, Stationary, or Began.

Declaration
public bool inProgress { get; }
Property Value
Type Description
bool
See Also

isInProgress

Whether the touch is currently in progress, i.e. has a phase of Began, Moved, or Stationary.

Declaration
public bool isInProgress { get; }
Property Value
Type Description
bool

Whether the touch is currently ongoing.

isTap

Whether the touch has performed a tap.

Declaration
public bool isTap { get; }
Property Value
Type Description
bool

Indicates whether the touch has tapped the screen.
Remarks

A tap is defined as a touch that begins and ends within defaultTapTime and stays within tapRadius of its startScreenPosition. If this is the case for a touch, this button is set to 1 at the time the touch goes to phase Ended.

Resets to 0 only when another touch is started on the control or when the control is reset.

See Also

maxHistoryLengthPerFinger

The amount of history kept for each single touch.

Declaration
public static int maxHistoryLengthPerFinger { get; }
Property Value
Type Description
int
Remarks

By default, this is zero meaning that no history information is kept for touches. Setting this to Int32.maxValue will cause all history from the beginning to the end of a touch being kept.

phase

Current phase of the touch.

Declaration
public TouchPhase phase { get; }
Property Value
Type Description
TouchPhase

Current phase of the touch.
Remarks

Every touch goes through a predefined cycle that starts with Began, then potentially Moved and/or Stationary, and finally concludes with either Ended or Canceled.

This property indicates where in the cycle the touch is.

See Also

pressure

Normalized pressure of the touch against the touch surface.

Declaration
public float pressure { get; }
Property Value
Type Description
float

Pressure level of the touch.
Remarks

Not all touchscreens are pressure-sensitive. If unsupported, this property will always return 0.

In general, touch pressure is supported on mobile platforms only.

Note that it is possible for the value to go above 1 even though it is considered normalized. The reason is that calibration on the system can put the maximum pressure point below the physically supported maximum value.

See Also

radius

Screen-space radius of the touch.

Declaration
public Vector2 radius { get; }
Property Value
Type Description
Vector2

Horizontal and vertical extents of the touch contact.
Remarks

If supported by the underlying device, this reports the size of the touch contact based on its screenPosition center point. If not supported, this will be default(Vector2).

See Also

screen

The touchscreen on which the touch occurred.

Declaration
public Touchscreen screen { get; }
Property Value
Type Description
Touchscreen

Touchscreen associated with the touch.

screenPosition

Screen-space position of the touch.

Declaration
public Vector2 screenPosition { get; }
Property Value
Type Description
Vector2

Screen-space position of the touch.
See Also

screens

Return the set of Touchscreens on which touch input is monitored.

Declaration
public static IEnumerable<Touchscreen> screens { get; }
Property Value
Type Description
IEnumerable<Touchscreen>
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().

startScreenPosition

Screen-space position where the touch started.

Declaration
public Vector2 startScreenPosition { get; }
Property Value
Type Description
Vector2

Start position of the touch.
See Also

startTime

Time in seconds on the same timeline as Time.realTimeSinceStartup when the touch began.

Declaration
public double startTime { get; }
Property Value
Type Description
double

Start time of the touch.
Remarks

This is the value of time when the touch started with phase Began.

See Also

tapCount

Number of times that the touch has been tapped in succession.

Declaration
public int tapCount { get; }
Property Value
Type Description
int

Indicates how many taps have been performed one after the other.
Remarks

Successive taps have to come within multiTapDelayTime for them to increase the tap count. I.e. if a new tap finishes within that time after startTime of the previous touch, the tap count is increased by one. If more than multiTapDelayTime passes after a tap with no successive tap, the tap count is reset to zero.

See Also

time

Time in seconds on the same timeline as Time.realTimeSinceStartup when the touch record was reported.

Declaration
public double time { get; }
Property Value
Type Description
double

Time the touch record was reported.
Remarks

This is the value time of the event that signaled the current state change for the touch.

touchId

Unique ID of the touch as (usually) assigned by the platform.

Declaration
public int touchId { get; }
Property Value
Type Description
int

Unique, non-zero ID of the touch.
Remarks

Each touch contact that is made with the screen receives its own unique ID which is normally assigned by the underlying platform.

Note a platform may reuse touch IDs after their respective touches have finished. This means that the guarantee of uniqueness is only made with respect to activeTouches.

In particular, all touches in history will have the same ID whereas touches in the a finger's touchHistory may end up having the same touch ID even though constituting different physical touch contacts.

See Also

valid

Whether this touch record holds valid data.

Declaration
public bool valid { get; }
Property Value
Type Description
bool

If true, the data contained in the touch is valid.
Remarks

Touch data is stored in unmanaged memory as a circular input buffer. This means that when the buffer runs out of capacity, older touch entries will get reused. When this happens, existing Touch instances referring to the record become invalid.

This property can be used to determine whether the record held on to by the Touch instance is still valid.

This property will be false for default-initialized Touch instances.

Note that accessing most of the other properties on this struct when the touch is invalid will trigger InvalidOperationException.

Methods

Equals(object)

Declaration
public override bool Equals(object obj)
Parameters
Type Name Description
object obj
Returns
Type Description
bool
Overrides

Equals(Touch)

Declaration
public bool Equals(Touch other)
Parameters
Type Name Description
Touch other
Returns
Type Description
bool

GetHashCode()

Declaration
public override int GetHashCode()
Returns
Type Description
int
Overrides

ToString()

Declaration
public override string ToString()
Returns
Type Description
string
Overrides

Events

onFingerDown

Event that is invoked when a finger touches a Touchscreen.

Declaration
public static event Action<Finger> onFingerDown
Event Type
Type Description
Action<Finger>
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

onFingerMove

Event that is invoked when a finger that is in contact with a Touchscreen moves on the screen.

Declaration
public static event Action<Finger> onFingerMove
Event Type
Type Description
Action<Finger>
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

onFingerUp

Event that is invoked when a finger stops touching a Touchscreen.

Declaration
public static event Action<Finger> onFingerUp
Event Type
Type Description
Action<Finger>
Exceptions
Type Condition
InvalidOperationException

EnhancedTouch has not been enabled via Enable().
See Also

Implements