Struct InputEvent

A chunk of memory signaling a data transfer in the input system.

Inherited Members
Namespace: UnityEngine.InputSystem.LowLevel
Syntax
public struct InputEvent
Remarks

Input events are raw memory buffers akin to a byte array. For most uses of the input system, it is not necessary to be aware of the event stream in the background. Events are written to the internal event buffer by producers -- usually by the platform-specific backends sitting in the Unity runtime. Once per fixed or dynamic update (depending on what updateMode is set to), the input system then goes and flushes out the internal event buffer to process pending events.

Events may signal general device-related occurrences (such as DeviceConfigurationEvent or DeviceRemoveEvent) or they may signal input activity. The latter kind of event is called "state events". In particular, these events are either StateEvent, only.

Events are solely focused on input. To effect output on an input device (e.g. haptics effects), "commands" (see InputDeviceCommand) are used.

Event processing can be listened to using onEvent. This callback will get triggered for each event as it is processed by the input system.

Note that there is no "routing" mechanism for events, i.e. no mechanism by which the input system looks for a handler for a specific event. Instead, events represent low-level activity that the input system directly integrates into the state of its InputDevice instances.

Each type of event is distinguished by its own FourCC type tag. The tag can be queried from the type property.

Each event will receive a unique ID when queued to the internal event buffer. The ID can be queried using the eventId property. Over the lifetime of the input system, no two events will receive the same ID. If you repeatedly queue an event from the same memory buffer, each individual call of QueueEvent(InputEventPtr) will result in its own unique event ID.

All events are device-specific meaning that deviceId will always reference some device (which, however, may or may not translate to an InputDevice; that part depends on whether the input system was able to create an InputDevice based on the information received from the backend).

To implement your own type of event, TODO (manual?)

Constructors

InputEvent(FourCC, Int32, Int32, Double)

Declaration
public InputEvent(FourCC type, int sizeInBytes, int deviceId, double time = -1)
Parameters
Type Name Description
FourCC type
Int32 sizeInBytes
Int32 deviceId
Double time

Fields

InvalidEventId

Default, invalid value for eventId. Upon being queued with QueueEvent(InputEventPtr), no event will receive this ID.

Declaration
public const int InvalidEventId = 0
Field Value
Type Description
Int32

Properties

deviceId

ID of the device that the event is for.

Declaration
public int deviceId { get; set; }
Property Value
Type Description
Int32
Remarks

Device IDs are allocated by the UnityEngine.InputSystem.LowLevel.IInputRuntime. No two devices will receive the same ID over an application lifecycle regardless of whether the devices existed at the same time or not.

See Also

eventId

Unique serial ID of the event.

Declaration
public int eventId { get; set; }
Property Value
Type Description
Int32
Remarks

Events are assigned running IDs when they are put on an event queue (see QueueEvent(InputEventPtr)).

See Also

handled

Declaration
public bool handled { get; set; }
Property Value
Type Description
Boolean

sizeInBytes

Total size of the event in bytes.

Declaration
public uint sizeInBytes { get; set; }
Property Value
Type Description
UInt32

Size of the event in bytes.
Remarks

Events are variable-size structs. This field denotes the total size of the event as stored in memory. This includes the full size of this struct and not just the "payload" of the event.

// Store event in private buffer:
unsafe byte[] CopyEventData(InputEventPtr eventPtr)
{
    var sizeInBytes = eventPtr.sizeInBytes;
    var buffer = new byte[sizeInBytes];
    fixed (byte* bufferPtr = buffer)
    {
        UnsafeUtility.MemCpy(new IntPtr(bufferPtr), eventPtr.data, sizeInBytes);
    }
    return buffer;
}

The maximum supported size of events is ushort.MaxValue, i.e. events cannot be larger than 64KB.

Exceptions
Type Condition
ArgumentException

value exceeds ushort.MaxValue.

time

Time that the event was generated at.

Declaration
public double time { get; set; }
Property Value
Type Description
Double
Remarks

Times are in seconds and progress linearly in real-time. The timeline is the same as for realtimeSinceStartup.

Note that this implies that event times will reset in the editor every time you go into play mode. In effect, this can result in events appearing with negative timestamps (i.e. the event was generated before the current zero point for realtimeSinceStartup).

type

Type code for the event.

Declaration
public FourCC type { get; set; }
Property Value
Type Description
FourCC
Remarks

Each type of event has its own unique FourCC tag. For example, state events (see StateEvent) are tagged with "STAT". The type tag for a specific type of event can be queried from its Type property (for example, Type).

To check whether an event has a specific type tag, you can use IsA<TOtherEvent>().

Methods

Equals(InputEvent*, InputEvent*)

Declaration
public static bool Equals(InputEvent*first, InputEvent*second)
Parameters
Type Name Description
InputEvent* first
InputEvent* second
Returns
Type Description
Boolean

ToString()

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

See Also