using System;
using System.Runtime.InteropServices;
using Unity.Collections.LowLevel.Unsafe;
using UnityEngine.InputSystem.Utilities;
using UnityEngineInternal.Input;
////REVIEW: can we get rid of the timestamp offsetting in the player and leave that complication for the editor only?
namespace UnityEngine.InputSystem.LowLevel
{
/// <summary>
/// A chunk of memory signaling a data transfer in the input system.
/// </summary>
/// <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 <see cref="InputSettings.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 <see cref="DeviceConfigurationEvent"/>
/// or <see cref="DeviceRemoveEvent"/>) or they may signal input activity. The latter kind of
/// event is called "state events". In particular, these events are either <see cref="StateEvent"/>,
/// only.
///
/// Events are solely focused on input. To effect output on an input device (e.g. haptics
/// effects), "commands" (see <see cref="InputDeviceCommand"/>) are used.
///
/// Event processing can be listened to using <see cref="InputSystem.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 <see cref="InputDevice"/>
/// instances.
///
/// Each type of event is distinguished by its own <see cref="FourCC"/> type tag. The tag can
/// be queried from the <see cref="type"/> property.
///
/// Each event will receive a unique ID when queued to the internal event buffer. The ID can
/// be queried using the <see cref="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 <see cref="InputSystem.QueueEvent"/> will result in
/// its own unique event ID.
///
/// All events are device-specific meaning that <see cref="deviceId"/> will always reference
/// some device (which, however, may or may not translate to an <see cref="InputDevice"/>; that
/// part depends on whether the input system was able to create an <see cref="InputDevice"/>
/// based on the information received from the backend).
/// </remarks>
/// <seealso cref="InputEventPtr"/>
// NOTE: This has to be layout compatible with native events.
[StructLayout(LayoutKind.Explicit, Size = kBaseEventSize, Pack = 1)]
public struct InputEvent
{
private const uint kHandledMask = 0x80000000;
private const uint kIdMask = 0x7FFFFFFF;
internal const int kBaseEventSize = NativeInputEvent.structSize;
/// <summary>
/// Default, invalid value for <see cref="eventId"/>. Upon being queued with
/// <see cref="InputSystem.QueueEvent"/>, no event will receive this ID.
/// </summary>
public const int InvalidEventId = 0;
internal const int kAlignment = 4;
[FieldOffset(0)]
private NativeInputEvent m_Event;
/// <summary>
/// Type code for the event.
/// </summary>
/// <remarks>
/// Each type of event has its own unique FourCC tag. For example, state events (see <see cref="StateEvent"/>)
/// are tagged with "STAT". The type tag for a specific type of event can be queried from its <c>Type</c>
/// property (for example, <see cref="StateEvent.Type"/>).
///
/// To check whether an event has a specific type tag, you can use <see cref="InputEventPtr.IsA{T}"/>.
/// </remarks>
public FourCC type
{
get => new FourCC((int)m_Event.type);
set => m_Event.type = (NativeInputEventType)(int)value;
}
/// <summary>
/// Total size of the event in bytes.
/// </summary>
/// <value>Size of the event in bytes.</value>
/// <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.
///
/// <example>
/// <code>
/// // 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;
/// }
/// </code>
/// </example>
///
/// The maximum supported size of events is <c>ushort.MaxValue</c>, i.e. events cannot
/// be larger than 64KB.
/// </remarks>
/// <exception cref="ArgumentException"><paramref name="value"/> exceeds <c>ushort.MaxValue</c>.</exception>
public uint sizeInBytes
{
get => m_Event.sizeInBytes;
set
{
if (value > ushort.MaxValue)
throw new ArgumentException("Maximum event size is " + ushort.MaxValue, nameof(value));
m_Event.sizeInBytes = (ushort)value;
}
}
/// <summary>
/// Unique serial ID of the event.
/// </summary>
/// <remarks>
/// Events are assigned running IDs when they are put on an event queue (see
/// <see cref="InputSystem.QueueEvent"/>).
/// </remarks>
/// <seealso cref="InvalidEventId"/>
public int eventId
{
get => (int)(m_Event.eventId & kIdMask);
set => m_Event.eventId = value | (int)(m_Event.eventId & ~kIdMask);
}
/// <summary>
/// ID of the device that the event is for.
/// </summary>
/// <remarks>
/// Device IDs are allocated by the <see cref="IInputRuntime">runtime</see>. No two devices
/// will receive the same ID over an application lifecycle regardless of whether the devices
/// existed at the same time or not.
/// </remarks>
/// <seealso cref="InputDevice.deviceId"/>
/// <seealso cref="InputSystem.GetDeviceById"/>
/// <seealso cref="InputDevice.InvalidDeviceId"/>
public int deviceId
{
get => m_Event.deviceId;
set => m_Event.deviceId = (ushort)value;
}
/// <summary>
/// Time that the event was generated at.
/// </summary>
/// <remarks>
/// Times are in seconds and progress linearly in real-time. The timeline is the
/// same as for <see cref="Time.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
/// <see cref="Time.realtimeSinceStartup"/>).
/// </remarks>
public double time
{
get => m_Event.time - InputRuntime.s_CurrentTimeOffsetToRealtimeSinceStartup;
set => m_Event.time = value + InputRuntime.s_CurrentTimeOffsetToRealtimeSinceStartup;
}
/// <summary>
/// This is the raw input timestamp without the offset to <see cref="Time.realtimeSinceStartup"/>.
/// </summary>
/// <remarks>
/// Internally, we always store all timestamps in "input time" which is relative to the native
/// function GetTimeSinceStartup(). <see cref="IInputRuntime.currentTime"/> yields the current
/// time on this timeline.
/// </remarks>
internal double internalTime
{
get => m_Event.time;
set => m_Event.time = value;
}
////FIXME: this API isn't consistent; time seems to be internalTime whereas time property is external time
public InputEvent(FourCC type, int sizeInBytes, int deviceId, double time = -1)
{
if (time < 0)
time = InputRuntime.s_Instance.currentTime;
m_Event.type = (NativeInputEventType)(int)type;
m_Event.sizeInBytes = (ushort)sizeInBytes;
m_Event.deviceId = (ushort)deviceId;
m_Event.time = time;
m_Event.eventId = InvalidEventId;
}
// We internally use bits inside m_EventId as flags. IDs are linearly counted up by the
// native input system starting at 1 so we have plenty room.
// NOTE: The native system assigns IDs when events are queued so if our handled flag
// will implicitly get overwritten. Having events go back to unhandled state
// when they go on the queue makes sense in itself, though, so this is fine.
public bool handled
{
get => (m_Event.eventId & kHandledMask) == kHandledMask;
set
{
if (value)
m_Event.eventId = (int)(m_Event.eventId | kHandledMask);
else
m_Event.eventId = (int)(m_Event.eventId & ~kHandledMask);
}
}
public override string ToString()
{
return $"id={eventId} type={type} device={deviceId} size={sizeInBytes} time={time}";
}
/// <summary>
/// Get the next event after the given one.
/// </summary>
/// <param name="currentPtr">A valid event pointer.</param>
/// <returns>Pointer to the next event in memory.</returns>
/// <remarks>
/// This method applies no checks and must only be called if there is an event following the
/// given one. Also, the size of the given event must be 100% as the method will simply
/// take the size and advance the given pointer by it (and aligning it to <see cref="kAlignment"/>).
/// </remarks>
/// <seealso cref="GetNextInMemoryChecked"/>
internal static unsafe InputEvent* GetNextInMemory(InputEvent* currentPtr)
{
Debug.Assert(currentPtr != null, "Event pointer must not be NULL");
var alignedSizeInBytes = currentPtr->sizeInBytes.AlignToMultipleOf(kAlignment);
return (InputEvent*)((byte*)currentPtr + alignedSizeInBytes);
}
/// <summary>
/// Get the next event after the given one. Throw if that would point to invalid memory as indicated
/// by the given memory buffer.
/// </summary>
/// <param name="currentPtr">A valid event pointer to an event inside <paramref name="buffer"/>.</param>
/// <param name="buffer">Event buffer in which to advance to the next event.</param>
/// <returns>Pointer to the next event.</returns>
/// <exception cref="InvalidOperationException">There are no more events in the given buffer.</exception>
internal static unsafe InputEvent* GetNextInMemoryChecked(InputEvent* currentPtr, ref InputEventBuffer buffer)
{
Debug.Assert(currentPtr != null, "Event pointer must not be NULL");
var alignedSizeInBytes = currentPtr->sizeInBytes.AlignToMultipleOf(kAlignment);
var nextPtr = (InputEvent*)((byte*)currentPtr + alignedSizeInBytes);
if (!buffer.Contains(nextPtr))
throw new InvalidOperationException(
$"Event '{new InputEventPtr(currentPtr)}' is last event in given buffer with size {buffer.sizeInBytes}");
return nextPtr;
}
public static unsafe bool Equals(InputEvent* first, InputEvent* second)
{
if (first == second)
return true;
if (first == null || second == null)
return false;
if (first->m_Event.sizeInBytes != second->m_Event.sizeInBytes)
return false;
return UnsafeUtility.MemCmp(first, second, first->m_Event.sizeInBytes) == 0;
}
}
}