Struct Touch

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

Namespace: UnityEngine.InputSystem.EnhancedTouch

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 readonly ReadOnlyArray<Finger> activeFingers { get; }

Property Value

Type	Description
ReadOnlyArray<Finger>

Exceptions

Type	Condition
InvalidOperationException	EnhancedTouch has not been enabled via Enable().

See Also

activeTouches

fingers

activeTouches

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

Declaration

public static readonly 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

activeFingers

began

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

Declaration

public readonly bool began { get; }

Property Value

Type	Description
Boolean

See Also

phase

ended

inProgress

delta

Screen-space motion delta of the touch.

Declaration

public readonly 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

delta

ended

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

Declaration

public readonly bool ended { get; }

Property Value

Type	Description
Boolean

See Also

phase

began

isInProgress

finger

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

Declaration

public readonly Finger finger { get; }

Property Value

Type	Description
Finger	Finger used for the touch contact.

See Also

activeFingers

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 readonly 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

activeTouches

activeFingers

history

History for this specific touch.

Declaration

public readonly 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 readonly bool inProgress { get; }

Property Value

Type	Description
Boolean

See Also

phase

began

ended

isInProgress

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

Declaration

public readonly bool isInProgress { get; }

Property Value

Type	Description
Boolean	Whether the touch is currently ongoing.

isTap

Whether the touch has performed a tap.

Declaration

public readonly bool isTap { get; }

Property Value

Type	Description
Boolean	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

tapCount

defaultTapTime

tap

maxHistoryLengthPerFinger

The amount of history kept for each single touch.

Declaration

public static readonly int maxHistoryLengthPerFinger { get; }

Property Value

Type	Description
Int32

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 readonly 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

isInProgress

phase

pressure

Normalized pressure of the touch against the touch surface.

Declaration

public readonly float pressure { get; }

Property Value

Type	Description
Single	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

pressure

radius

Screen-space radius of the touch.

Declaration

public readonly 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

radius

screen

The touchscreen on which the touch occurred.

Declaration

public readonly Touchscreen screen { get; }

Property Value

Type	Description
Touchscreen	Touchscreen associated with the touch.

screenPosition

Screen-space position of the touch.

Declaration

public readonly Vector2 screenPosition { get; }

Property Value

Type	Description
Vector2	Screen-space position of the touch.

See Also

position

screens

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

Declaration

public static readonly 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 readonly Vector2 startScreenPosition { get; }

Property Value

Type	Description
Vector2	Start position of the touch.

See Also

startPosition

startTime

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

Declaration

public readonly 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

startTime

tapCount

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

Declaration

public readonly int tapCount { get; }

Property Value

Type	Description
Int32	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

tapCount

time

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

Declaration

public readonly 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 readonly int touchId { get; }

Property Value

Type	Description
Int32	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

touchId

valid

Whether this touch record holds valid data.

Declaration

public readonly bool valid { get; }

Property Value

Type	Description
Boolean	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
Boolean

Overrides

ValueType.Equals(Object)

Equals(Touch)

Declaration

public bool Equals(Touch other)

Parameters

Type	Name	Description
Touch	other

Returns

Type	Description
Boolean

Implements

IEquatable<T>.Equals(T)

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
Int32

Overrides

ValueType.GetHashCode()

ToString()

Declaration

public override string ToString()

Returns

Type	Description
String

Overrides

ValueType.ToString()

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

onFingerUp

onFingerMove

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

onFingerDown

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

onFingerDown

onFingerMove