using System;
using System.Collections.Generic;
namespace UnityEngine.InputSystem
{
/// <summary>
/// Contextual data made available when processing values of composite bindings.
/// </summary>
/// <remarks>
/// An instance of this struct is passed to <see
/// cref="InputBindingComposite{TValue}.ReadValue(ref InputBindingCompositeContext)"/>.
/// Use it to access contextual data such as the value for individual part bindings.
///
/// Note that an instance of this struct should never be held on to past the duration
/// of the call to <c>ReadValue</c>. The data it retrieves is only valid during
/// the callback.
/// </remarks>
/// <seealso cref="InputBindingComposite"/>
/// <seealso cref="InputBindingComposite{TValue}"/>
/// <seealso cref="InputBindingComposite{TValue}.ReadValue(ref InputBindingCompositeContext)"/>
public struct InputBindingCompositeContext
{
/// <summary>
/// Information about a control bound to a part of a composite.
/// </summary>
public struct PartBinding
{
/// <summary>
/// Identifier of the part. This is the numeric identifier stored in the public
/// fields of the composite by the input system.
/// </summary>
public int part { get; set; }
/// <summary>
/// The control bound to the part.
/// </summary>
public InputControl control { get; set; }
}
/// <summary>
/// Enumerate all the controls that are part of the composite.
/// </summary>
/// <seealso cref="InputBindingComposite.FinishSetup"/>
public IEnumerable<PartBinding> controls
{
get
{
if (m_State == null)
yield break;
var totalBindingCount = m_State.totalBindingCount;
for (var bindingIndex = m_BindingIndex + 1; bindingIndex < totalBindingCount; ++bindingIndex)
{
var bindingState = m_State.GetBindingState(bindingIndex);
if (!bindingState.isPartOfComposite)
break;
var controlStartIndex = bindingState.controlStartIndex;
for (var i = 0; i < bindingState.controlCount; ++i)
{
var control = m_State.controls[controlStartIndex + i];
yield return new PartBinding
{
part = bindingState.partIndex,
control = control
};
}
}
}
}
public float EvaluateMagnitude(int partNumber)
{
return m_State.EvaluateCompositePartMagnitude(m_BindingIndex, partNumber);
}
/// <summary>
/// Read the value of the giving part binding.
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier. See the example below.</param>
/// <typeparam name="TValue">Type of value to read. This must match the
/// value type expected from controls bound to the part.</typeparam>
/// <returns>The value read from the part bindings.</returns>
/// <exception cref="InvalidOperationException">The given <typeparamref name="TValue"/>
/// value type does not match the actual value type of the control(s) bound
/// to the part.</exception>
/// <remarks>
/// If no control is bound to the given part, the return value will always
/// be <c>default(TValue)</c>. If a single control is bound to the part, the
/// value will be that of the control. If multiple controls are bound to a
/// part, the return value will be that greatest one according to <c>IComparable</c>
/// implemented by <typeparamref name="TValue"/>.
///
/// Note that this method only works with values that are <c>IComparable</c>.
/// To read a value type that is not <c>IComparable</c> or to supply a custom
/// comparer, use <see cref="ReadValue{TValue,TComparer}(int,TComparer)"/>.
///
/// If an invalid <paramref name="partNumber"/> is supplied, the return value
/// will simply be <c>default(TValue)</c>. No exception is thrown.
///
/// <example>
/// <code>
/// public class MyComposite : InputBindingComposite<float>
/// {
/// // Defines a "part" binding for the composite. Each part can be
/// // bound to arbitrary many times (including not at all). The "layout"
/// // property of the attribute we supply determines what kind of
/// // control is expected to be bound to the part.
/// //
/// // When initializing a composite instance, the input system will
/// // automatically assign part numbers and store them in the fields
/// // we define here.
/// [InputControl(layout = "Button")]
/// public int firstPart;
///
/// // Defines a second part.
/// [InputControl(layout = "Vector2")]
/// public int secondPart;
///
/// public override float ReadValue(ref InputBindingCompositeContext context)
/// {
/// // Read the button.
/// var firstValue = context.ReadValue<float>();
///
/// // Read the vector.
/// var secondValue = context.ReadValue<Vector2>();
///
/// // Perform some computation based on the inputs. Here, we just
/// // scale the vector by the value we got from the button.
/// return secondValue * firstValue;
/// }
/// }
/// </code>
/// </example>
/// </remarks>
/// <seealso cref="ReadValue{TValue,TComparer}(int,TComparer)"/>
/// <seealso cref="InputControl{TValue}.ReadValue"/>
public unsafe TValue ReadValue<TValue>(int partNumber)
where TValue : struct, IComparable<TValue>
{
if (m_State == null)
return default;
return m_State.ReadCompositePartValue<TValue, DefaultComparer<TValue>>
(m_BindingIndex, partNumber, null, out _);
}
/// <summary>
/// Same as <see cref="ReadValue{TValue}(int)"/> but also return the control
/// from which the value was read.
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier.</param>
/// <param name="sourceControl">Receives the <see cref="InputControl"/> from
/// which the value was read. If multiple controls are bound to the given part,
/// this is the control whose value was ultimately selected. Will be set to
/// <c>null</c> if <paramref name="partNumber"/> is not a valid part or if no
/// controls are bound to the part.</param>
/// <typeparam name="TValue">Type of value to read. This must match the
/// value type expected from controls bound to the part.</typeparam>
/// <returns>The value read from the part bindings.</returns>
/// <remarks>
/// Like <see cref="ReadValue{TValue}(int)"/>, this method relies on using <c>IComparable</c>
/// implemented by <typeparamref name="TValue"/> to determine the greatest value
/// if multiple controls are bound to the specified part.
/// </remarks>
/// <seealso cref="ReadValue{TValue}(int)"/>
public unsafe TValue ReadValue<TValue>(int partNumber, out InputControl sourceControl)
where TValue : struct, IComparable<TValue>
{
if (m_State == null)
{
sourceControl = null;
return default;
}
var value = m_State.ReadCompositePartValue<TValue, DefaultComparer<TValue>>(m_BindingIndex, partNumber,
null, out var controlIndex);
if (controlIndex != InputActionState.kInvalidIndex)
sourceControl = m_State.controls[controlIndex];
else
sourceControl = null;
return value;
}
////TODO: once we can break the API, remove the versions that rely on comparers and do everything through magnitude
/// <summary>
/// Read the value of the given part bindings and use the given <paramref name="comparer"/>
/// to determine which value to return if multiple controls are bound to the part.
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier.</param>
/// <param name="comparer">Instance of <typeparamref name="TComparer"/> for comparing
/// multiple values.</param>
/// <typeparam name="TValue">Type of value to read. This must match the
/// value type expected from controls bound to the part.</typeparam>
/// <returns>The value read from the part bindings.</returns>
/// <typeparam name="TComparer">Comparer to use if multiple controls are bound to
/// the given part. All values will be compared using <c>TComparer.Compare</c> and
/// the greatest value will be returned.</typeparam>
/// <returns>The value read from the part bindings.</returns>
/// <remarks>
/// This method is a useful alternative to <see cref="ReadValue{TValue}(int)"/> for
/// value types that do not implement <c>IComparable</c> or when the default comparison
/// behavior is undesirable.
///
/// <example>
/// <code>
/// public class CompositeWithVector2Part : InputBindingComposite<Vector2>
/// {
/// [InputControl(layout = "Vector2")]
/// public int part;
///
/// public override Vector2 ReadValue(ref InputBindingCompositeContext context)
/// {
/// // Return the Vector3 with the greatest magnitude.
/// return context.ReadValue<Vector2, Vector2MagnitudeComparer>(part);
/// }
/// }
/// </code>
/// </example>
/// </remarks>
/// <seealso cref="Utilities.Vector2MagnitudeComparer"/>
/// <seealso cref="Utilities.Vector3MagnitudeComparer"/>
public unsafe TValue ReadValue<TValue, TComparer>(int partNumber, TComparer comparer = default)
where TValue : struct
where TComparer : IComparer<TValue>
{
if (m_State == null)
return default;
return m_State.ReadCompositePartValue<TValue, TComparer>(
m_BindingIndex, partNumber, null, out _, comparer);
}
/// <summary>
/// Like <see cref="ReadValue{TValue,TComparer}(int,TComparer)"/> but also return
/// the control from which the value has ultimately been read.
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier.</param>
/// <param name="sourceControl">Receives the <see cref="InputControl"/> from
/// which the value was read. If multiple controls are bound to the given part,
/// this is the control whose value was ultimately selected. Will be set to
/// <c>null</c> if <paramref name="partNumber"/> is not a valid part or if no
/// controls are bound to the part.</param>
/// <param name="comparer">Instance of <typeparamref name="TComparer"/> for comparing
/// multiple values.</param>
/// <typeparam name="TValue">Type of value to read. This must match the
/// value type expected from controls bound to the part.</typeparam>
/// <returns>The value read from the part bindings.</returns>
/// <typeparam name="TComparer">Comparer to use if multiple controls are bound to
/// the given part. All values will be compared using <c>TComparer.Compare</c> and
/// the greatest value will be returned.</typeparam>
/// <returns>The value read from the part bindings.</returns>
public unsafe TValue ReadValue<TValue, TComparer>(int partNumber, out InputControl sourceControl, TComparer comparer = default)
where TValue : struct
where TComparer : IComparer<TValue>
{
if (m_State == null)
{
sourceControl = null;
return default;
}
var value = m_State.ReadCompositePartValue<TValue, TComparer>(m_BindingIndex, partNumber, null,
out var controlIndex, comparer);
if (controlIndex != InputActionState.kInvalidIndex)
sourceControl = m_State.controls[controlIndex];
else
sourceControl = null;
return value;
}
/// <summary>
/// Like <see cref="ReadValue{TValue}(int)"/> but treat bound controls as buttons. This means
/// that custom <see cref="Controls.ButtonControl.pressPoint"/> are respected and that floating-point
/// values from non-ButtonControls will be compared to <see cref="InputSettings.defaultButtonPressPoint"/>.
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier.</param>
/// <returns>True if any button bound to the part is pressed.</returns>
/// <remarks>
/// This method expects all controls bound to the part to be of type <c>InputControl<float></c>.
///
/// This method is different from just calling <see cref="ReadValue{TValue}(int)"/> with a <c>float</c>
/// parameter and comparing the result to <see cref="InputSettings.defaultButtonPressPoint"/> in that
/// custom press points set on individual ButtonControls will be respected.
/// </remarks>
/// <seealso cref="Controls.ButtonControl"/>
/// <seealso cref="InputSettings.defaultButtonPressPoint"/>
public unsafe bool ReadValueAsButton(int partNumber)
{
if (m_State == null)
return default;
////REVIEW: wouldn't this have to take release points into account now?
var buttonValue = false;
m_State.ReadCompositePartValue<float, DefaultComparer<float>>(m_BindingIndex, partNumber, &buttonValue,
out _);
return buttonValue;
}
public unsafe void ReadValue(int partNumber, void* buffer, int bufferSize)
{
m_State?.ReadCompositePartValue(m_BindingIndex, partNumber, buffer, bufferSize);
}
public object ReadValueAsObject(int partNumber)
{
return m_State.ReadCompositePartValueAsObject(m_BindingIndex, partNumber);
}
/// <summary>
/// Return the timestamp (see <see cref="LowLevel.InputEvent.time"/>) for when the given
/// binding part crossed the button press threshold (see <see cref="Controls.ButtonControl.pressPoint"/>).
/// </summary>
/// <param name="partNumber">Number of the part to read. This is assigned
/// automatically by the input system and should be treated as an opaque
/// identifier.</param>
/// <returns>Returns the time at which the given part binding moved into "press" state or 0 if there's
/// current no press.</returns>
/// <remarks>
/// If the given part has more than a single binding and/or more than a single bound control, the <em>earliest</em>
/// press time is returned.
/// </remarks>
public double GetPressTime(int partNumber)
{
return m_State.GetCompositePartPressTime(m_BindingIndex, partNumber);
}
internal InputActionState m_State;
internal int m_BindingIndex;
private struct DefaultComparer<TValue> : IComparer<TValue>
where TValue : IComparable<TValue>
{
public int Compare(TValue x, TValue y)
{
return x.CompareTo(y);
}
}
}
}