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

Examples

using UnityEngine;
using UnityEngine.InputSystem.EnhancedTouch;

// Alias EnhancedTouch.Touch to "Touch" for less typing.
using Touch = UnityEngine.InputSystem.EnhancedTouch.Touch;
using TouchPhase = UnityEngine.InputSystem.TouchPhase;

public class Example : MonoBehaviour
{
    void Awake()
    {
        // Note that enhanced touch support needs to be explicitly enabled.
        EnhancedTouchSupport.Enable();
    }

    void Update()
    {
        // Illustrates how to examine all active touches once per frame and show their last recorded position
        // in the associated screen-space.
        foreach (var touch in Touch.activeTouches)
        {
            switch (touch.phase)
            {
                case TouchPhase.Began:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} started this frame at ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Ended:
                    Debug.Log($"Frame {Time.frameCount}:Touch {touch} ended this frame at ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Moved:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} moved this frame to ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Canceled:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} was canceled this frame");
                    break;
                case TouchPhase.Stationary:
                    Debug.Log($"Frame {Time.frameCount}: ouch {touch} was not updated this frame");
                    break;
            }
        }
    }
}

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>

Remarks

To instead get a collection of all fingers (not only currently active) use fingers.

Exceptions

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

activeTouches

All touches that are either ongoing 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.

In order to evaluate all active touches on a per-frame basis see activeFingers.

Examples

using UnityEngine;
using UnityEngine.InputSystem.EnhancedTouch;

// Alias EnhancedTouch.Touch to "Touch" for less typing.
using Touch = UnityEngine.InputSystem.EnhancedTouch.Touch;
using TouchPhase = UnityEngine.InputSystem.TouchPhase;

public class Example : MonoBehaviour
{
    void Awake()
    {
        // Note that enhanced touch support needs to be explicitly enabled.
        EnhancedTouchSupport.Enable();
    }

    void Update()
    {
        // Illustrates how to examine all active touches once per frame and show their last recorded position
        // in the associated screen-space.
        foreach (var touch in Touch.activeTouches)
        {
            switch (touch.phase)
            {
                case TouchPhase.Began:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} started this frame at ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Ended:
                    Debug.Log($"Frame {Time.frameCount}:Touch {touch} ended this frame at ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Moved:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} moved this frame to ({touch.screenPosition.x}, {touch.screenPosition.y})");
                    break;
                case TouchPhase.Canceled:
                    Debug.Log($"Frame {Time.frameCount}: Touch {touch} was canceled this frame");
                    break;
                case TouchPhase.Stationary:
                    Debug.Log($"Frame {Time.frameCount}: ouch {touch} was not updated this frame");
                    break;
            }
        }
    }
}

Exceptions

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

began

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

Declaration

public bool began { get; }

Property Value

Type	Description
bool

Remarks

Use isInProgress to more conveniently evaluate whether this touch is currently active or not.

delta

Screen-space motion delta of the touch.

Declaration

public Vector2 delta { get; }

Property Value

Type	Description
Vector2

Remarks

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

Also see delta for retrieving delta directly from a device control.

displayIndex

The index of the display containing the touch.

Declaration

public int displayIndex { get; }

Property Value

Type	Description
int

Remarks

A zero based number representing the display index of the Display that contains the touch.

Also see displayIndex for retrieving display index directly from a device control.

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

Remarks

Use isInProgress to more conveniently evaluate whether this touch is currently active or not.

finger

The finger used for the touch contact.

Declaration

public Finger finger { get; }

Property Value

Type	Description
Finger

Remarks

Note that this is only null for default-initialized instances of the struct.

See activeFingers for how to access all active fingers.

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. For querying only active touches, use activeTouches.

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().

history

History touch readings for this specific touch contact.

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

isInProgress

Whether the touch is currently in progress.

Declaration

public bool isInProgress { get; }

Property Value

Type	Description
bool

Remarks

This is effectively equivalent to checking if phase is equal to either of: Began, Moved, or Stationary.

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.

Use tapCount to determine if there were multiple taps occurring during the frame. Also note that tap may be used to determine whether there was a tap.

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

The current touch phase of the touch indicating its current state in the phase cycle.

Declaration

public TouchPhase phase { get; }

Property Value

Type	Description
TouchPhase

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 and is based on phase.

Use isInProgress to more conveniently evaluate whether this touch is currently active or not.

pressure

Normalized pressure of the touch against the touch surface.

Declaration

public float pressure { get; }

Property Value

Type	Description
float

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.

Touch pressure may also be retrieved directly from the device control via pressure.

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.

radius

Screen-space radius of the touch which define its horizontal and vertical extents.

Declaration

public Vector2 radius { get; }

Property Value

Type	Description
Vector2

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).

Touch radius may also be retrieved directly from the device control via radius.

screen

The Touchscreen associated with the touch contact.

Declaration

public Touchscreen screen { get; }

Property Value

Type	Description
Touchscreen

screenPosition

Screen-space position of the touch.

Declaration

public Vector2 screenPosition { get; }

Property Value

Type	Description
Vector2

Remarks

Also see position for retrieving position directly from a device control.

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

Remarks

Also see startPosition for retrieving start position directly from a device control.

startTime

Start time of the touch in seconds on the same timeline as Time.realTimeSinceStartup.

Declaration

public double startTime { get; }

Property Value

Type	Description
double

Remarks

This is the value of time when the touch started with phase Began. Note that start time may also be retrieved directly from the device control via startTime.

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.

Also see tapCount for retrieving tap count directly from a device control.

time

Time the touch record was reported on the same timeline as realtimeSinceStartup.

Declaration

public double time { get; }

Property Value

Type	Description
double

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

Remarks

Each touch contact that is made with the screen receives its own unique, non-zero ID which is normally assigned by the underlying platform via touchId.

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 finger's touchHistory may end up having the same touch ID even though constituting different physical touch contacts.

valid

Whether this touch record holds valid data.

Declaration

public bool valid { get; }

Property Value

Type	Description
bool

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

ValueType.Equals(object)

Equals(Touch)

Compares this touch for equality with another instance other.

Declaration

public bool Equals(Touch other)

Parameters

Type	Name	Description
Touch	other	The other instance to compare with.

Returns

Type	Description
bool	`true` if this touch and `other` represents the same finger and maps to the same touch record, otherwise `false`

GetHashCode()

Declaration

public override int GetHashCode()

Returns

Type	Description
int

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>

Remarks

In order to react to a finger being moved or released, see onFingerMove and onFingerUp respectively.

Exceptions

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

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>

Remarks

In order to react to a finger that touches a Touchscreen or a finger that stops touching a Touchscreen, use onFingerDown and onFingerUp respectively.

Exceptions

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

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>

Remarks

In order to react to a finger that touches a Touchscreen or a finger that is being moved use onFingerDown and onFingerMove respectively.

Exceptions

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

Implements

IEquatable<T>