Struct InputBindingCompositeContext

Contextual data made available when processing values of composite bindings.

Namespace: UnityEngine.InputSystem
Syntax
public struct InputBindingCompositeContext
Remarks

An instance of this struct is passed to 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 ReadValue. The data it retrieves is only valid during the callback.

Properties

controls

Enumerate all the controls that are part of the composite.

Declaration
public readonly IEnumerable<InputBindingCompositeContext.PartBinding> controls { get; }
Property Value
Type Description
IEnumerable<InputBindingCompositeContext.PartBinding>
See Also

Methods

EvaluateMagnitude(Int32)

Declaration
public float EvaluateMagnitude(int partNumber)
Parameters
Type Name Description
Int32 partNumber
Returns
Type Description
Single

ReadValue(Int32, Void*, Int32)

Declaration
public void ReadValue(int partNumber, void *buffer, int bufferSize)
Parameters
Type Name Description
Int32 partNumber
Void* buffer
Int32 bufferSize

ReadValue<TValue>(Int32)

Read the value of the giving part binding.

Declaration
public TValue ReadValue<TValue>(int partNumber)
    where TValue : struct, IComparable<TValue>
Parameters
Type Name Description
Int32 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.
Returns
Type Description
TValue

The value read from the part bindings.
Type Parameters
Name Description
TValue

Type of value to read. This must match the value type expected from controls bound to the part.
Remarks

If no control is bound to the given part, the return value will always be default(TValue). 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 IComparable implemented by TValue.

Note that this method only works with values that are IComparable. To read a value type that is not IComparable or to supply a custom comparer, use ReadValue<TValue, TComparer>(Int32, TComparer).

If an invalid partNumber is supplied, the return value will simply be default(TValue). No exception is thrown.

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;
    }
}
See Also

ReadValue<TValue>(Int32, out InputControl)

Same as ReadValue<TValue>(Int32) but also return the control from which the value was read.

Declaration
public TValue ReadValue<TValue>(int partNumber, out InputControl sourceControl)
    where TValue : struct, IComparable<TValue>
Parameters
Type Name Description
Int32 partNumber

Number of the part to read. This is assigned automatically by the input system and should be treated as an opaque identifier.
InputControl sourceControl

Receives the 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 null if partNumber is not a valid part or if no controls are bound to the part.
Returns
Type Description
TValue

The value read from the part bindings.
Type Parameters
Name Description
TValue

Type of value to read. This must match the value type expected from controls bound to the part.
Remarks

Like ReadValue<TValue>(Int32), this method relies on using IComparable implemented by TValue to determine the greatest value if multiple controls are bound to the specified part.

See Also

ReadValue<TValue, TComparer>(Int32, TComparer)

Read the value of the given part bindings and use the given comparer to determine which value to return if multiple controls are bound to the part.

Declaration
public TValue ReadValue<TValue, TComparer>(int partNumber, TComparer comparer = null)
    where TValue : struct where TComparer : IComparer<TValue>
Parameters
Type Name Description
Int32 partNumber

Number of the part to read. This is assigned automatically by the input system and should be treated as an opaque identifier.
TComparer comparer

Instance of TComparer for comparing multiple values.
Returns
Type Description
TValue

The value read from the part bindings.
Type Parameters
Name Description
TValue

Type of value to read. This must match the value type expected from controls bound to the part.
TComparer

Comparer to use if multiple controls are bound to the given part. All values will be compared using TComparer.Compare and the greatest value will be returned.
Remarks

This method is a useful alternative to ReadValue<TValue>(Int32) for value types that do not implement IComparable or when the default comparison behavior is undesirable.

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);
    }
}
See Also

ReadValue<TValue, TComparer>(Int32, out InputControl, TComparer)

Like ReadValue<TValue, TComparer>(Int32, TComparer) but also return the control from which the value has ultimately been read.

Declaration
public TValue ReadValue<TValue, TComparer>(int partNumber, out InputControl sourceControl, TComparer comparer = null)
    where TValue : struct where TComparer : IComparer<TValue>
Parameters
Type Name Description
Int32 partNumber

Number of the part to read. This is assigned automatically by the input system and should be treated as an opaque identifier.
InputControl sourceControl

Receives the 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 null if partNumber is not a valid part or if no controls are bound to the part.
TComparer comparer

Instance of TComparer for comparing multiple values.
Returns
Type Description
TValue

The value read from the part bindings.
Type Parameters
Name Description
TValue

Type of value to read. This must match the value type expected from controls bound to the part.
TComparer

Comparer to use if multiple controls are bound to the given part. All values will be compared using TComparer.Compare and the greatest value will be returned.

ReadValueAsButton(Int32)

Like ReadValue<TValue>(Int32) but treat bound controls as buttons. This means that custom pressPoint are respected and that floating-point values from non-ButtonControls will be compared to defaultButtonPressPoint.

Declaration
public bool ReadValueAsButton(int partNumber)
Parameters
Type Name Description
Int32 partNumber

Number of the part to read. This is assigned automatically by the input system and should be treated as an opaque identifier.
Returns
Type Description
Boolean

True if any button bound to the part is pressed.
Remarks

This method expects all controls bound to the part to be of type InputControl<float>.

This method is different from just calling ReadValue<TValue>(Int32) with a float parameter and comparing the result to defaultButtonPressPoint in that custom press points set on individual ButtonControls will be respected.

See Also

ReadValueAsObject(Int32)

Declaration
public object ReadValueAsObject(int partNumber)
Parameters
Type Name Description
Int32 partNumber
Returns
Type Description
Object

See Also