Class InputBindingComposite<TValue>

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

Inheritance

object

InputBindingComposite

InputBindingComposite<TValue>

AxisComposite

ButtonWithOneModifier

ButtonWithTwoModifiers

Vector2Composite

Vector3Composite

Inherited Members

InputBindingComposite.EvaluateMagnitude(ref InputBindingCompositeContext)

InputBindingComposite.FinishSetup(ref InputBindingCompositeContext)

InputBindingComposite.GetExpectedControlLayoutName(string, string)

Namespace: UnityEngine.InputSystem

Assembly: Unity.InputSystem.dll

Syntax

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, that is, 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 autodiscover or manually 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
int	Returns sizeof(TValue).

Overrides

InputBindingComposite.valueSizeInBytes

See Also

RegisterBindingComposite<T>(string)

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

InputBindingComposite.valueType

See Also

RegisterBindingComposite<T>(string)

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<TValue>()

ReadValue<TValue>()

ReadValue(ref InputBindingCompositeContext, void*, int)

Read a value from the composite without having to know the value type (unlike ReadValue(ref InputBindingCompositeContext) 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.
int	bufferSize	Size of the buffer allocated at buffer.

Overrides

InputBindingComposite.ReadValue(ref InputBindingCompositeContext, void*, int)

Remarks

This API will be used if someone calls ReadValue(void*, int) 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

ReadValue(void*, int)

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

InputBindingComposite.ReadValueAsObject(ref InputBindingCompositeContext)

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

RegisterBindingComposite<T>(string)

See Also

RegisterBindingComposite<T>(string)