Class InputBindingComposite<TValue>

A binding composite arranges several bindings such that they form a "virtual control".

Inheritance
Object
InputBindingComposite
InputBindingComposite<TValue>
CustomComposite
AxisComposite
ButtonWithOneModifier
ButtonWithTwoModifiers
Vector2Composite
Inherited Members
Namespace: UnityEngine.InputSystem
Syntax
[Preserve]
public abstract class InputBindingComposite<TValue> : InputBindingComposite where TValue : struct
Type Parameters
Name Description
TValue

Type of value returned by the composite. This must be a "blittable" type, i.e. a type whose values can simply be copied around.
Remarks

Composite bindings are a special type of InputBinding. Whereas normally an input binding simply references a set of controls and returns whatever input values are generated by those controls, a composite binding sources input from several controls and derives a new value from that.

A good example for that is a classic WASD keyboard binding:

var moveAction = new InputAction(name: "move");
moveAction.AddCompositeBinding("Vector2")
    .With("Up", "<Keyboard>/w")
    .With("Down", "<Keyboard>/s")
    .With("Left", "<Keyboard>/a")
    .With("Right", "<Keyboard>/d")

Here, each direction is represented by a separate binding. "Up" is bound to "W", "Down" is bound to "S", and so on. Each direction individually returns a 0 or 1 depending on whether it is pressed or not.

However, as a composite, the binding to the "move" action returns a combined Vector2 that is computed from the state of each of the directional controls. This is what composites do. They take inputs from their "parts" to derive an input for the binding as a whole.

Note that the properties and methods defined in InputBindingComposite and this class will generally be called internally by the input system and are not generally meant to be called directly from user land.

The set of composites available in the system is extensible. While some composites are such as Vector2Composite and ButtonWithOneModifier are available out of the box, new composites can be implemented by anyone and simply be registered with RegisterBindingComposite<T>(String).

See the "Custom Composite" sample (can be installed from package manager UI) for a detailed example of how to create a custom composite.

Properties

valueSizeInBytes

The size of values returned by the composite, i.e. sizeof(TValue).

Declaration
public override int valueSizeInBytes { get; }
Property Value
Type Description
Int32

Returns sizeof(TValue).
Overrides

valueType

The type of value returned by the composite, i.e. typeof(TValue).

Declaration
public override Type valueType { get; }
Property Value
Type Description
Type

Returns typeof(TValue).
Overrides

Methods

ReadValue(ref InputBindingCompositeContext)

Read a value for the composite given the supplied context.

Declaration
public abstract TValue ReadValue(ref InputBindingCompositeContext context)
Parameters
Type Name Description
InputBindingCompositeContext context

Callback context for the binding composite. Use this to access the values supplied by part bindings.
Returns
Type Description
TValue

The current value of the composite according to the state made accessible through context.
Remarks

This is the main method to implement in custom composites.

public class CustomComposite : InputBindingComposite<float>
{
    [InputControl(layout = "Button")]
    public int button;

    public float scaleFactor = 1;

    public override float ReadValue(ref InputBindingComposite context)
    {
        return context.ReadValue<float>(button) * scaleFactor;
    }
}

The other method to consider overriding is EvaluateMagnitude(ref InputBindingCompositeContext).

See Also

ReadValue(ref InputBindingCompositeContext, Void*, Int32)

Read a value from the composite without having to know the value type (unlike and without allocating GC heap memory (unlike ReadValueAsObject(ref InputBindingCompositeContext)).

Declaration
public override void ReadValue(ref InputBindingCompositeContext context, void *buffer, int bufferSize)
Parameters
Type Name Description
InputBindingCompositeContext context

Callback context for the binding composite. Use this to access the values supplied by part bindings.
Void* buffer

Buffer that receives the value read for the composite.
Int32 bufferSize

Size of the buffer allocated at buffer.
Overrides
Remarks

This API will be used if someone calls ReadValue(Void*, Int32) with the action leading to the composite.

By deriving from InputBindingComposite<TValue>, this will automatically be implemented for you.

Exceptions
Type Condition
ArgumentException

bufferSize is smaller than valueSizeInBytes.
ArgumentNullException

buffer is null.
See Also

ReadValueAsObject(ref InputBindingCompositeContext)

Read the value of the composite as a boxed object. This allows reading the value without having to know the value type and without having to deal with raw byte buffers.

Declaration
public override object ReadValueAsObject(ref InputBindingCompositeContext context)
Parameters
Type Name Description
InputBindingCompositeContext context

Callback context for the binding composite. Use this to access the values supplied by part bindings.
Returns
Type Description
Object

The current value of the composite according to the state passed in through context.
Overrides
Remarks

This API will be used if someone calls ReadValueAsObject() with the action leading to the composite.

By deriving from InputBindingComposite<TValue>, this will automatically be implemented for you.

See Also