Class InputControl | Package Manager UI website
docs.unity3d.com
    Show / Hide Table of Contents

    Class InputControl

    A typed and named value in a hierarchy of controls.

    Inheritance
    System.Object
    InputControl
    InputControl<TValue>
    InputDevice
    Inherited Members
    System.Object.Equals(System.Object)
    System.Object.Equals(System.Object, System.Object)
    System.Object.ReferenceEquals(System.Object, System.Object)
    System.Object.GetHashCode()
    System.Object.GetType()
    System.Object.MemberwiseClone()
    Namespace: UnityEngine.Experimental.Input
    Syntax
    public abstract class InputControl
    Remarks

    Controls can have children which in turn may have children. At the root of the child hierarchy is always an InputDevice (which themselves are InputControls).

    Controls can be looked up by their path (see and TryFindControl(InputControl, String, Int32)).

    Each control must have a unique name within its parent (see name). Multiple names can be assigned to controls using aliases (see aliases). Name lookup is case-insensitive.

    In addition to names, a control may have usages associated with it (see usages). A usage indicates how a control is meant to be used. For example, a button can be assigned the "PrimaryAction" usage to indicate it is the primary action button the device. Within a device, usages have to be unique. See CommonUsages for a list of standardized usages.

    Controls do not actually store values. Instead, every control receives an InputStateBlock which, after the control's device has been added to the system, is used to read out values from the device's backing store. This backing store is referred to as "state" in the API as opposed to "values" which represent the data resulting from reading state. The format that each control stores state in is specific to the control. It can vary not only between controls of different types but also between controls of the same type. An , for example, can be stored as a float or as a byte or in a number of other formats. stateBlock identifies both where the control stores its state as well as the format it stores it in.

    Constructors

    InputControl()

    Declaration
    protected InputControl()

    Fields

    m_StateBlock

    Declaration
    protected InputStateBlock m_StateBlock
    Field Value
    Type Description
    InputStateBlock

    ReservedCharacters

    Characters that may not appear in control names.

    Declaration
    public static string ReservedCharacters
    Field Value
    Type Description
    System.String

    Properties

    aliases

    Declaration
    public ReadOnlyArray<InternedString> aliases { get; }
    Property Value
    Type Description
    ReadOnlyArray<InternedString>

    children

    List of immediate children.

    Declaration
    public ReadOnlyArray<InputControl> children { get; }
    Property Value
    Type Description
    ReadOnlyArray<InputControl>
    Remarks

    Does not allocate.

    currentStatePtr

    Declaration
    protected void *currentStatePtr { get; }
    Property Value
    Type Description
    System.Void*

    defaultStatePtr

    Declaration
    protected void *defaultStatePtr { get; }
    Property Value
    Type Description
    System.Void*

    device

    The device that this control is a part of.

    Declaration
    public InputDevice device { get; }
    Property Value
    Type Description
    InputDevice
    Remarks

    This is the root of the control hiearchy. For the device at the root, this will point to itself.

    displayName

    The text to display as the name of the control.

    Declaration
    public string displayName { get; protected set; }
    Property Value
    Type Description
    System.String
    Remarks

    Note that the display name of a control may change over time. For example, when changing from a QWERTY keyboard layout to an AZERTY keyboard layout, the "q" key (which will keep that name) will change its display name from "q" to "a".

    By default, a control's display name will come from its layout. If it is not assigned a display name there, the display name will default to name. However, specific controls may override this behavior. , for example, will set the display name to the actual key name corresponding to the current keyboard layout.

    For nested controls, the display name will include the display names of all parent controls, i.e. the display name will fully identify the control on the device. For example, the display name for the left D-Pad button on a gamepad is "D-Pad Left" and not just "Left".

    See Also
    shortDisplayName

    Item[String]

    Fetch a control from the control's hierarchy by name.

    Declaration
    public InputControl this[string path] { get; }
    Parameters
    Type Name Description
    System.String path
    Property Value
    Type Description
    InputControl
    Remarks

    Note that path matching is case-insensitive.

    Examples
    gamepad["leftStick"] // Returns Gamepad.leftStick
    gamepad["leftStick/x"] // Returns Gamepad.leftStick.x
    gamepad["{PrimaryAction}"] // Returns the control with PrimaryAction usage, i.e. Gamepad.aButton
    See Also
    InputControlPath
    path
    TryGetChildControl(String)

    layout

    Layout the control is based on.

    Declaration
    public string layout { get; }
    Property Value
    Type Description
    System.String
    Remarks

    This is the layout name rather than a reference to an as we only create layout instances during device creation and treat them as temporaries in general so as to not waste heap space during normal operation.

    name

    The name of the control, i.e. the final name part in its path.

    Declaration
    public string name { get; }
    Property Value
    Type Description
    System.String
    Remarks

    Names of controls must be unique within the context of their parent.

    Lookup of names is case-insensitive.

    See Also
    path
    aliases

    noiseMaskPtr

    Declaration
    protected void *noiseMaskPtr { get; }
    Property Value
    Type Description
    System.Void*

    noisy

    Whether the control is considered noisy.

    Declaration
    public bool noisy { get; }
    Property Value
    Type Description
    System.Boolean
    Remarks

    A control is considered "noisy" if it produces different values without necessarily requiring user interaction. Sensors are a good example.

    The value of this property is determined by the layout () that the control has been built from.

    Note that for devices (InputDevice) this property is true if any control on the device is marked as noisy.

    parent

    The immediate parent of the control or null if the control has no parent (which, once fully constructed) will only be the case for InputDevices).

    Declaration
    public InputControl parent { get; }
    Property Value
    Type Description
    InputControl

    path

    Full path all the way from the root.

    Declaration
    public string path { get; }
    Property Value
    Type Description
    System.String
    Remarks

    Allocates on first hit. Paths are not created until someone asks for them.

    Examples

    Example: "/gamepad/leftStick/x"

    previousFrameStatePtr

    Declaration
    protected void *previousFrameStatePtr { get; }
    Property Value
    Type Description
    System.Void*

    shortDisplayName

    An alternate, abbreviated displayName (for example "LMB" instead of "Left Button").

    Declaration
    public string shortDisplayName { get; protected set; }
    Property Value
    Type Description
    System.String
    Remarks

    If the control has no abbreviated version, this will be null. Note that this behavior is different from displayName which will fall back to name if not display name has been assigned to the control.

    For nested controls, the short display name will include the short display names of all parent controls, i.e. the display name will fully identify the control on the device. For example, the display name for the left D-Pad button on a gamepad is "D-Pad \u2190" and not just "\u2190". Note that if a parent control has no short name, its long name will be used instead.

    See Also
    displayName

    stateBlock

    Declaration
    public InputStateBlock stateBlock { get; }
    Property Value
    Type Description
    InputStateBlock

    stateOffsetRelativeToDeviceRoot

    The offset of this control's state relative to its device root.

    Declaration
    protected uint stateOffsetRelativeToDeviceRoot { get; }
    Property Value
    Type Description
    System.UInt32
    Remarks

    Once a device has been added to the system, its state block will get allocated in the global state buffers and the offset of the device's state block will get baked into all of the controls on the device. This property always returns the "unbaked" offset.

    synthetic

    Whether the control is considered synthetic.

    Declaration
    public bool synthetic { get; }
    Property Value
    Type Description
    System.Boolean
    Remarks

    A control is considered "synthetic" if it does not correspond to an actual, physical control on the device. An example for this is anyKey or the up/down/left/right buttons added by .

    The value of this property is determined by the layout () that the control has been built from.

    usages

    Declaration
    public ReadOnlyArray<InternedString> usages { get; }
    Property Value
    Type Description
    ReadOnlyArray<InternedString>

    valueSizeInBytes

    Size in bytes of values that the control returns.

    Declaration
    public abstract int valueSizeInBytes { get; }
    Property Value
    Type Description
    System.Int32
    See Also
    valueType

    valueType

    Returns the underlying value type of this control.

    Declaration
    public abstract Type valueType { get; }
    Property Value
    Type Description
    Type
    Remarks

    This is the type of values that are returned when reading the current value of a control or when reading a value of a control from an event.

    See Also
    valueSizeInBytes

    variants

    Semicolon-separated list of variants of the control layout or "default".

    Declaration
    public string variants { get; }
    Property Value
    Type Description
    System.String
    Examples

    "Lefty" when using the "Lefty" gamepad layout.

    Methods

    CompareState(Void*, Void*, Void*)

    Compare the control's stored state in firstStatePtr to secondStatePtr.

    Declaration
    public bool CompareState(void *firstStatePtr, void *secondStatePtr, void *maskPtr = null)
    Parameters
    Type Name Description
    System.Void* firstStatePtr

    Memory containing the control's stateBlock.

    System.Void* secondStatePtr

    Memory containing the control's stateBlock

    System.Void* maskPtr

    Optional mask. If supplied, it will be used to mask the comparison between firstStatePtr and secondStatePtr such that any bit not set in the mask will be ignored even if different between the two states. This can be used, for example, to ignore noise in the state (noiseMaskPtr).

    Returns
    Type Description
    System.Boolean

    True if the state is equivalent in both memory buffers.

    Remarks

    Unlike CompareValue(Void*, Void*), this method only compares raw memory state. If used on a stick, for example, it may mean that this method returns false for two stick values that would compare equal using CompareValue(Void*, Void*) (e.g. if both stick values fall below the deadzone).

    See Also
    CompareValue(Void*, Void*)

    CompareValue(Void*, Void*)

    Compare the value of the control as read from firstStatePtr to that read from secondStatePtr and return true if they are equal.

    Declaration
    public abstract bool CompareValue(void *firstStatePtr, void *secondStatePtr)
    Parameters
    Type Name Description
    System.Void* firstStatePtr

    Memory containing the control's stateBlock.

    System.Void* secondStatePtr

    Memory containing the control's stateBlock

    Returns
    Type Description
    System.Boolean

    True if the value of the control is equal in both firstStatePtr and secondStatePtr.

    Remarks

    Unlike CompareState(Void*, Void*, Void*), this method will have to do more than just compare the memory for the control in the two state buffers. It will have to read out state for the control and run the full processing machinery for the control to turn the state into a final, processed value. CompareValue is thus more costly than CompareState(Void*, Void*, Void*).

    This method will apply epsilons () when comparing floats.

    See Also
    CompareState(Void*, Void*, Void*)

    EvaluateMagnitude()

    Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated.

    Declaration
    public float EvaluateMagnitude()
    Returns
    Type Description
    System.Single

    Amount of actuation of the control or -1 if it cannot be determined.

    Remarks

    Magnitudes do not make sense for all types of controls. For example, for a control that represents an enumeration of values (such as ), there is no meaningful linear ordering of values (one could derive a linear ordering through the actual enum values but their assignment may be entirely arbitrary; it is unclear whether a state of Cancelled has a higher or lower "magnitude" as a state of Began).

    Controls that have no meaningful magnitude will return -1 when calling this method. Any negative return value should be considered an invalid value.

    See Also
    EvaluateMagnitude(Void*)

    EvaluateMagnitude(Void*)

    Compute an absolute, normalized magnitude value that indicates the extent to which the control is actuated in the given state.

    Declaration
    public virtual float EvaluateMagnitude(void *statePtr)
    Parameters
    Type Name Description
    System.Void* statePtr

    State containing the control's stateBlock.

    Returns
    Type Description
    System.Single

    Amount of actuation of the control or -1 if it cannot be determined.

    See Also
    EvaluateMagnitude()
    stateBlock

    FinishSetup(InputDeviceBuilder)

    Declaration
    protected virtual void FinishSetup(InputDeviceBuilder builder)
    Parameters
    Type Name Description
    InputDeviceBuilder builder

    ReadValueFromStateAsObject(Void*)

    Read the control's final, processed value from the given state and return the value as an object.

    Declaration
    public abstract object ReadValueFromStateAsObject(void *statePtr)
    Parameters
    Type Name Description
    System.Void* statePtr
    Returns
    Type Description
    System.Object

    The control's value as stored in statePtr.

    Remarks

    This method allocates GC memory and should not be used during normal gameplay operation.

    See Also
    ReadValueFromStateIntoBuffer(Void*, Void*, Int32)

    ReadValueFromStateIntoBuffer(Void*, Void*, Int32)

    Read the control's final, processed value from the given state and store it in the given buffer.

    Declaration
    public abstract void ReadValueFromStateIntoBuffer(void *statePtr, void *bufferPtr, int bufferSize)
    Parameters
    Type Name Description
    System.Void* statePtr

    State to read the value for the control from.

    System.Void* bufferPtr

    Buffer to store the value in.

    System.Int32 bufferSize

    Size of bufferPtr in bytes. Must be at least valueSizeInBytes. If it is smaller, will be thrown.

    See Also
    ReadValueFromStateAsObject(Void*)
    WriteValueFromBufferIntoState(Void*, Int32, Void*)

    RefreshConfiguration()

    Declaration
    protected virtual void RefreshConfiguration()

    RefreshConfigurationIfNeeded()

    Declaration
    protected void RefreshConfigurationIfNeeded()

    ToString()

    Declaration
    public override string ToString()
    Returns
    Type Description
    System.String
    Overrides
    System.Object.ToString()

    TryGetChildControl(String)

    Declaration
    public InputControl TryGetChildControl(string path)
    Parameters
    Type Name Description
    System.String path
    Returns
    Type Description
    InputControl

    WriteValueFromBufferIntoState(Void*, Int32, Void*)

    Read a value from the given memory and store it as state.

    Declaration
    public virtual void WriteValueFromBufferIntoState(void *bufferPtr, int bufferSize, void *statePtr)
    Parameters
    Type Name Description
    System.Void* bufferPtr

    Memory containing value.

    System.Int32 bufferSize

    Size of bufferPtr in bytes. Must be at least valueSizeInBytes.

    System.Void* statePtr

    State containing the control's stateBlock. Will receive the state as converted from the given value.

    Remarks

    Writing values will NOT apply processors to the given value. This can mean that when reading a value from a control after it has been written to its state, the resulting value differs from what was written.

    See Also
    ReadValueFromStateIntoBuffer(Void*, Void*, Int32)
    WriteValueFromObjectIntoState(Object, Void*)

    WriteValueFromObjectIntoState(Object, Void*)

    Read a value object and store it as state in the given memory.

    Declaration
    public virtual void WriteValueFromObjectIntoState(object value, void *statePtr)
    Parameters
    Type Name Description
    System.Object value

    Value for the control.

    System.Void* statePtr

    State containing the control's stateBlock. Will receive the state state as converted from the given value.

    Remarks

    Writing values will NOT apply processors to the given value. This can mean that when reading a value from a control after it has been written to its state, the resulting value differs from what was written.

    See Also
    WriteValueFromBufferIntoState(Void*, Int32, Void*)

    See Also

    InputDevice
    Back to top
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023