Class InputBindingComposite

A binding that synthesizes a value from from several component bindings.

Inheritance
Object
InputBindingComposite
OneModifierComposite
TwoModifiersComposite
InputBindingComposite<TValue>
Namespace: UnityEngine.InputSystem
Syntax
public abstract class InputBindingComposite
Remarks

This is the base class for composite bindings. See InputBindingComposite<TValue> for more details about composites and for how to define custom composites.

Properties

valueSizeInBytes

Size of a value read by ReadValue(ref InputBindingCompositeContext, Void*, Int32).

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

Size of values stored in memory buffers by ReadValue(ref InputBindingCompositeContext, Void*, Int32).
Remarks

This is usually implicitly defined by the size of values derived from the type argument to InputBindingComposite<TValue>. E.g. if the type argument is Vector2, this property will be 8.

See Also

valueType

The type of value returned by the composite.

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

Type of value returned by the composite.
Remarks

Just like each InputControl has a specific type of value it will return, each composite has a specific type of value it will return. This is usually implicitly defined by the type parameter of InputBindingComposite<TValue>.

See Also

Methods

EvaluateMagnitude(ref InputBindingCompositeContext)

Determine the current level of actuation of the composite.

Declaration
public virtual float EvaluateMagnitude(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
Single
Remarks

This method by default returns -1, meaning that the composite does not support magnitudes. You can override the method to add support for magnitudes.

See EvaluateMagnitude() for details of how magnitudes work.

See Also

FinishSetup(ref InputBindingCompositeContext)

Called after binding resolution for an InputActionMap is complete.

Declaration
protected virtual void FinishSetup(ref InputBindingCompositeContext context)
Parameters
Type Name Description
InputBindingCompositeContext context
Remarks

Some composites do not have predetermine value types. Two examples of this are OneModifierComposite and TwoModifiersComposite, which both have a "binding" part that can be bound to arbitrary controls. This means that the value type of these bindings can only be determined at runtime.

Overriding this method allows accessing the actual controls bound to each part at runtime.

[InputControl] public int binding;

protected override void FinishSetup(ref InputBindingContext context)
{
    // Get all controls bound to the 'binding' part.
    var controls = context.controls
        .Where(x => x.part == binding)
        .Select(x => x.control);
}

GetExpectedControlLayoutName(String, String)

Return the name of the control layout that is expected for the given part (e.g. "Up") on the given composite (e.g. "Dpad").

Declaration
public static string GetExpectedControlLayoutName(string composite, string part)
Parameters
Type Name Description
String composite

Registration name of the composite.
String part

Name of the part.
Returns
Type Description
String

The layout name (such as "Button") expected for the given part on the composite or null if there is no composite with the given name or no part on the composite with the given name.
Remarks

Expected control layouts can be set on composite parts by setting the layout property on them.

Examples
InputBindingComposite.GetExpectedControlLayoutName("Dpad", "Up") // Returns "Button"

// This is how Dpad communicates that:
[InputControl(layout = "Button")] public int up;

ReadValue(ref InputBindingCompositeContext, Void*, Int32)

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 abstract 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.
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 abstract 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.
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