A game about forced loneliness, made by TACStudios
tacstudios.tngl.sh
1// In retrospect, allowing Touchscreen to do what it does the way it does it was a mistake. It came out of thinking that
2// we need Touchscreen to have a large pool of TouchStates from which to dynamically allocate -- as this was what the old
3// input system does. This made it unfeasible/unwise to put the burden of touch allocation on platform backends and thus
4// led to the current setup where backends are sending TouchState events which Touchscreen dynamically incorporates.
5//
6// This shouldn't have happened.
7//
8// Ultimately, this led to IInputStateCallbackReceiver in its current form. While quite flexible in what it allows you to
9// do, it introduces a lot of additional complication and deviation from an otherwise very simple model based on trivially
10// understood chunks of input state.
11
12namespace UnityEngine.InputSystem.LowLevel
13{
14 /// <summary>
15 /// Interface for devices that implement their own state update handling.
16 /// </summary>
17 /// <remarks>
18 /// The input system has built-in logic to automatically handle the state buffers that store input values for devices. This
19 /// means that if an input event containing input state is processed, its data will be copied automatically into the state
20 /// memory for the device.
21 ///
22 /// However, some devices need to apply custom logic whenever new input is received. An example of this is <see cref="Pointer.delta"/>
23 /// which needs to accumulate deltas as they are received within a frame and then reset the delta at the beginning of a new frame.
24 ///
25 /// Also, devices like <see cref="Touchscreen"/> extensively customize event handling in order to implement features such as
26 /// tap detection and primary touch handling. This is what allows the device to receive state events in <see cref="TouchState"/>
27 /// format even though that is not the format of the device itself (which is mainly a composite of several TouchStates).
28 ///
29 /// This interface allows to bypass the built-in logic and instead intercept and manually handle state updates.
30 /// </remarks>
31 /// <seealso cref="InputDevice"/>
32 /// <seealso cref="Pointer"/>
33 /// <seealso cref="Touchscreen"/>
34 public interface IInputStateCallbackReceiver
35 {
36 /// <summary>
37 /// A new input update begins. This means that the current state of the device is being carried over into the next
38 /// frame.
39 /// </summary>
40 /// <remarks>
41 /// This is called without the front and back buffer for the device having been flipped. You can use <see cref="InputState.Change"/>
42 /// to write values into the device's state (e.g. to reset a given control to its default state) which will implicitly perform
43 /// the buffer flip.
44 /// </remarks>
45 void OnNextUpdate();
46
47 /// <summary>
48 /// A new state event has been received and is being processed.
49 /// </summary>
50 /// <param name="eventPtr">The state event. This will be either a <see cref="StateEvent"/> or a <see cref="DeltaStateEvent"/>.</param>
51 /// <remarks>
52 /// Use <see cref="InputState.Change"/> to write state updates into the device state buffers. While nothing will prevent a device
53 /// from writing directly into the memory buffers retrieved with <see cref="InputControl.currentStatePtr"/>, doing so will bypass
54 /// the buffer flipping logic as well as change detection from change monitors (<see cref="IInputStateChangeMonitor"/>; this will
55 /// cause <see cref="InputAction"/> to not work with the device) and thus lead to incorrect behavior.
56 /// </remarks>
57 /// <seealso cref="StateEvent"/>
58 /// <seealso cref="DeltaStateEvent"/>
59 void OnStateEvent(InputEventPtr eventPtr);
60
61 /// <summary>
62 /// Compute an offset that correlates <paramref name="control"/> with the state in <paramref name="eventPtr"/>.
63 /// </summary>
64 /// <param name="control">Control the state of which we want to access within <paramref name="eventPtr"/>.</param>
65 /// <param name="eventPtr">An input event. Must be a <see cref="StateEvent"/> or <see cref="DeltaStateEvent"/></param>
66 /// <param name="offset"></param>
67 /// <returns>False if the correlation failed or true if <paramref name="offset"/> has been set and should be used
68 /// as the offset for the state of <paramref name="control"/>.</returns>
69 /// <remarks>
70 /// This method will only be called if the given state event has a state format different than that of the device. In that case,
71 /// the memory of the input state captured in the given state event cannot be trivially correlated with the control.
72 ///
73 /// The input system calls the method to know which offset (if any) in the device's state block to consider the state
74 /// in <paramref name="eventPtr"/> relative to when accessing the state for <paramref name="control"/> as found in
75 /// the event.
76 ///
77 /// An example of when this is called is for touch events. These are normally sent in <see cref="TouchState"/> format
78 /// which, however, is not the state format of <see cref="Touchscreen"/> (which uses a composite of several TouchStates).
79 /// When trying to access the state in <paramref name="eventPtr"/> to, for example, read out the touch position,
80 /// </remarks>
81 /// <seealso cref="InputControlExtensions.GetStatePtrFromStateEvent"/>
82 bool GetStateOffsetForEvent(InputControl control, InputEventPtr eventPtr, ref uint offset);
83 }
84}