Class Pointer
Base class for pointer-style devices moving on a 2D screen.
Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
public class Pointer : InputDevice, IInputStateCallbackReceiverRemarks
This class abstracts over general "pointing" behavior where a pointer is moved across a 2D
surface. Operating at the Pointer level allows treating
Note that a pointer may have "multi-point" ability as is the case with multi-touch where multiple touches represent multiple concurrent "pointers". However, for any pointer device with multiple pointers, only one pointer is considered "primary" and drives the pointer controls present on the base class.
Properties
current
The pointer that was added or used last by the user or null if there is no pointer
device connected to the system.
Declaration
public static Pointer current { get; }Property Value
| Type | Description |
|---|---|
| Pointer | Currently active |
delta
The current window-space motion delta of the pointer.
Declaration
public Vector2Control delta { get; protected set; }Property Value
| Type | Description |
|---|---|
| Vector2Control | Control representing the motion delta of the pointer. |
Remarks
Every time a pointer is moved, it generates a motion delta. This control represents this motion.
Note that some pointers have the ability to generate motion deltas without
actually changing the position of the pointer. This is the case for Mouse
which even when, for example, bumping up against the edges of the screen or when being
locked in place, can generate motion. This means that activity on delta is not
necessarily correlated with activity on position.
Deltas have two special behaviors attached to them that makes them quite unique among input controls.
For one, deltas will automatically reset to (0,0) between frames. If, for example,
the current delta value is (12,8), then after the next Update(),
the delta is automatically set to (0,0). More precisely, deltas will reset as part
of onBeforeUpdate. This happens every time regardless of whether
there are pending motion events for the pointer or not. But because it happens in
onBeforeUpdate (that is, before events are processed),
subsequent motion deltas are incorporated normally.
Note that the resetting is visible to InputActions. This means that when
binding to a delta control from an action that is not using PassThrough,
you will see the action getting cancelled at the start of every frame. With a PassThrough
actions, you will instead see it perform one extra time with a zero value.
The other special behavior of deltas is accumulation. When receiving more than one
motion update in a frame, deltas will not simply switch from one value to the other
but instead accumulate them. For example, if two events are received for a pointer
in a frame and one has a motion delta of (1,1) and the other has a motion delta
of (2,2), then once Update() has finished processing
events, the value of the delta control will be (3,3) and not (2,2).
Note that just like resetting, accumulation is also visible to InputActions.
This means that because the delta control changes value twice, the action will trigger
twice but the value when it is triggered the second time will be (3,3) and
not (2,2) even though that's the value received from the event.
See Also
position
The current pointer coordinates in window space.
Declaration
public Vector2Control position { get; protected set; }Property Value
| Type | Description |
|---|---|
| Vector2Control | Control representing the current position of the pointer on screen. |
Remarks
Within player code, the coordinates are in the coordinate space of Unity's Display.
Within editor code, the coordinates are in the coordinate space of the current EditorWindow
This means that if you query the Mouse position in EditorWindow.OnGUI, for example,
the returned 2D vector will be in the coordinate space of your local GUI (same as
Event.mousePosition).
press
Whether the pointer is pressed down.
Declaration
public ButtonControl press { get; protected set; }Property Value
| Type | Description |
|---|---|
| ButtonControl |
Remarks
What this means exactly depends on the nature of the pointer. For mice (Mouse), it means that the left button is pressed. For pens (Pen), it means that the pen tip is touching the screen/tablet surface. For touchscreens (Touchscreen), it means that there is at least one finger touching the screen.
pressure
Normalized pressure with which the pointer is currently pressed while in contact with the pointer surface.
Declaration
public AxisControl pressure { get; protected set; }Property Value
| Type | Description |
|---|---|
| AxisControl | Control representing the pressure with which the pointer is pressed down. |
Remarks
This is only meaningful for pointing devices that support pressure. Mice do not, pens usually do, and touch usually does on mobile platforms.
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
Window-space radius of the pointer contact with the surface.
Declaration
public Vector2Control radius { get; protected set; }Property Value
| Type | Description |
|---|---|
| Vector2Control | Control representing the horizontal and vertical extents of the pointer contact. |
Remarks
Usually, only touch input has radius detection.
See Also
Methods
FinishSetup()
Perform final initialization tasks after the control hierarchy has been put into place.
Declaration
protected override void FinishSetup()Overrides
Remarks
This method can be overridden to perform control- or device-specific setup work. The most common use case is for looking up child controls and storing them in local getters.
public class MyDevice : InputDevice
{
public ButtonControl button { get; private set; }
public AxisControl axis { get; private set; }
protected override void OnFinishSetup()
{
// Cache controls in getters.
button = GetChildControl("button");
axis = GetChildControl("axis");
}
}MakeCurrent()
Make this the current device of its type.
Declaration
public override void MakeCurrent()Overrides
Remarks
This method is called automatically by the input system when a device is
added or when input is received on it. Many types of devices have .current
getters that allow querying the last used device of a specific type directly (for
example, see current).
There is one special case, however, related to noise. A device that has noisy controls
(i.e. controls for which noisy is true) may receive input events
that contain no meaningful user interaction but are simply just noise from the device. A
good example of this is the PS4 gamepad which has a built-in gyro and may thus constantly
feed events into the input system even if not being actually in use. If, for example, an
Xbox gamepad and PS4 gamepad are both connected to a PC and the user is playing with the
Xbox gamepad, the PS4 gamepad would still constantly make itself current
by simply flooding the system with events. Hence why by default, noise on .current getters
will be filtered out and a device will only see MakeCurrent getting called if there input
was detected on non-noisy controls.
See Also
OnNextUpdate()
Called whenever the input system advances by one frame.
Declaration
protected void OnNextUpdate()See Also
OnRemoved()
Called by the system when the device is removed from devices.
Declaration
protected override void OnRemoved()Overrides
Remarks
This is called after the device has already been removed.
See Also
OnStateEvent(InputEventPtr)
Called when the pointer receives a state event.
Declaration
protected void OnStateEvent(InputEventPtr eventPtr)Parameters
| Type | Name | Description |
|---|---|---|
| InputEventPtr | eventPtr | The input event. |
Explicit Interface Implementations
IInputStateCallbackReceiver.GetStateOffsetForEvent(InputControl, InputEventPtr, ref UInt32)
Declaration
bool IInputStateCallbackReceiver.GetStateOffsetForEvent(InputControl control, InputEventPtr eventPtr, ref uint offset)Parameters
| Type | Name | Description |
|---|---|---|
| InputControl | control | |
| InputEventPtr | eventPtr | |
| UInt32 | offset |
Returns
| Type | Description |
|---|---|
| Boolean |
Implements
IInputStateCallbackReceiver.OnNextUpdate()
Declaration
void IInputStateCallbackReceiver.OnNextUpdate()Implements
IInputStateCallbackReceiver.OnStateEvent(InputEventPtr)
Declaration
void IInputStateCallbackReceiver.OnStateEvent(InputEventPtr eventPtr)Parameters
| Type | Name | Description |
|---|---|---|
| InputEventPtr | eventPtr |