docs.unity.cn
    Show / Hide Table of Contents

    Class Pointer

    Base class for pointer-style devices moving on a 2D screen.

    Inheritance
    Object
    InputControl
    InputDevice
    Pointer
    Mouse
    Pen
    Touchscreen
    Inherited Members
    InputDevice.InvalidDeviceId
    InputDevice.description
    InputDevice.enabled
    InputDevice.canRunInBackground
    InputDevice.added
    InputDevice.remote
    InputDevice.native
    InputDevice.updateBeforeRender
    InputDevice.deviceId
    InputDevice.lastUpdateTime
    InputDevice.wasUpdatedThisFrame
    InputDevice.allControls
    InputDevice.valueType
    InputDevice.valueSizeInBytes
    InputDevice.all
    InputDevice.ReadValueFromBufferAsObject(Void*, Int32)
    InputDevice.ReadValueFromStateAsObject(Void*)
    InputDevice.ReadValueFromStateIntoBuffer(Void*, Void*, Int32)
    InputDevice.CompareValue(Void*, Void*)
    InputDevice.OnAdded()
    InputDevice.OnConfigurationChanged()
    InputDevice.ExecuteCommand<TCommand>(TCommand)
    InputDevice.ExecuteCommand(InputDeviceCommand*)
    InputControl.name
    InputControl.displayName
    InputControl.shortDisplayName
    InputControl.path
    InputControl.layout
    InputControl.variants
    InputControl.device
    InputControl.parent
    InputControl.children
    InputControl.usages
    InputControl.aliases
    InputControl.stateBlock
    InputControl.noisy
    InputControl.synthetic
    InputControl.Item[String]
    InputControl.ToString()
    InputControl.EvaluateMagnitude()
    InputControl.EvaluateMagnitude(Void*)
    InputControl.WriteValueFromBufferIntoState(Void*, Int32, Void*)
    InputControl.WriteValueFromObjectIntoState(Object, Void*)
    InputControl.TryGetChildControl(String)
    InputControl.TryGetChildControl<TControl>(String)
    InputControl.GetChildControl(String)
    InputControl.GetChildControl<TControl>(String)
    InputControl.RefreshConfigurationIfNeeded()
    InputControl.RefreshConfiguration()
    InputControl.m_StateBlock
    InputControl.currentStatePtr
    InputControl.previousFrameStatePtr
    InputControl.defaultStatePtr
    InputControl.noiseMaskPtr
    InputControl.stateOffsetRelativeToDeviceRoot
    Namespace: UnityEngine.InputSystem
    Syntax
    public class Pointer : InputDevice, IInputStateCallbackReceiver
    Remarks

    This class abstracts over general "pointing" behavior where a pointer is moved across a 2D surface. Operating at the Pointer level allows treating Mouse, Pen, and Touchscreen all as pointers with a set of shared behaviors.

    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 Pointer or null.

    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
    AccumulateValueInEvent(InputControl<Single>, Void*, InputEventPtr)

    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
    radius

    Methods

    FinishSetup()

    Perform final initialization tasks after the control hierarchy has been put into place.

    Declaration
    protected override void FinishSetup()
    Overrides
    InputControl.FinishSetup()
    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
    InputDevice.MakeCurrent()
    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
    current
    current
    current
    current

    OnNextUpdate()

    Called whenever the input system advances by one frame.

    Declaration
    protected void OnNextUpdate()
    See Also
    Update()

    OnRemoved()

    Called by the system when the device is removed from devices.

    Declaration
    protected override void OnRemoved()
    Overrides
    InputDevice.OnRemoved()
    Remarks

    This is called after the device has already been removed.

    See Also
    devices
    Removed
    OnRemoved()

    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.GetStateOffsetForEvent(InputControl, InputEventPtr, ref UInt32)

    IInputStateCallbackReceiver.OnNextUpdate()

    Declaration
    void IInputStateCallbackReceiver.OnNextUpdate()
    Implements
    IInputStateCallbackReceiver.OnNextUpdate()

    IInputStateCallbackReceiver.OnStateEvent(InputEventPtr)

    Declaration
    void IInputStateCallbackReceiver.OnStateEvent(InputEventPtr eventPtr)
    Parameters
    Type Name Description
    InputEventPtr eventPtr
    Implements
    IInputStateCallbackReceiver.OnStateEvent(InputEventPtr)

    Extension Methods

    InputControlExtensions.FindInParentChain<TControl>(InputControl)
    InputControlExtensions.IsPressed(InputControl, Single)
    InputControlExtensions.IsActuated(InputControl, Single)
    InputControlExtensions.ReadValueAsObject(InputControl)
    InputControlExtensions.ReadValueIntoBuffer(InputControl, Void*, Int32)
    InputControlExtensions.ReadDefaultValueAsObject(InputControl)
    InputControlExtensions.ReadValueFromEventAsObject(InputControl, InputEventPtr)
    InputControlExtensions.WriteValueFromObjectIntoEvent(InputControl, InputEventPtr, Object)
    InputControlExtensions.WriteValueIntoState(InputControl, Void*)
    InputControlExtensions.WriteValueIntoState<TValue>(InputControl, TValue, Void*)
    InputControlExtensions.WriteValueIntoEvent<TValue>(InputControl, TValue, InputEventPtr)
    InputControlExtensions.CopyState(InputDevice, Void*, Int32)
    InputControlExtensions.CopyState<TState>(InputDevice, out TState)
    InputControlExtensions.CheckStateIsAtDefault(InputControl)
    InputControlExtensions.CheckStateIsAtDefault(InputControl, Void*, Void*)
    InputControlExtensions.CheckStateIsAtDefaultIgnoringNoise(InputControl)
    InputControlExtensions.CheckStateIsAtDefaultIgnoringNoise(InputControl, Void*)
    InputControlExtensions.CompareStateIgnoringNoise(InputControl, Void*)
    InputControlExtensions.CompareState(InputControl, Void*, Void*, Void*)
    InputControlExtensions.CompareState(InputControl, Void*, Void*)
    InputControlExtensions.HasValueChangeInState(InputControl, Void*)
    InputControlExtensions.HasValueChangeInEvent(InputControl, InputEventPtr)
    InputControlExtensions.GetStatePtrFromStateEvent(InputControl, InputEventPtr)
    InputControlExtensions.ResetToDefaultStateInEvent(InputControl, InputEventPtr)
    InputControlExtensions.FindControlsRecursive<TControl>(InputControl, IList<TControl>, Func<TControl, Boolean>)

    See Also

    Mouse
    Pen
    Touchscreen
    Back to top Copyright © 2022 Unity Technologies
    Generated by DocFX
    on Wednesday, January 5, 2022
    Terms of use