docs.unity3d.com
    Show / Hide Table of Contents

    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 IEnumerable<InputBindingCompositeContext.PartBinding> controls { get; }
    Property Value
    Type Description
    IEnumerable<InputBindingCompositeContext.PartBinding>
    See Also
    FinishSetup(InputBindingCompositeContext)

    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, TComparer>(Int32, TComparer)
    ReadValue()

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

    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
    Vector2MagnitudeComparer
    Vector3MagnitudeComparer

    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
    ButtonControl
    defaultButtonPressPoint

    ReadValueAsObject(Int32)

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

    See Also

    InputBindingComposite
    InputBindingComposite<TValue>
    ReadValue(InputBindingCompositeContext)
    Back to top
    Terms of use
    Copyright © 2023 Unity Technologies — Terms of use
    • Legal
    • Privacy Policy
    • Cookies
    • Do Not Sell or Share My Personal Information
    • Your Privacy Choices (Cookie Settings)
    "Unity", Unity logos, and other Unity trademarks are trademarks or registered trademarks of Unity Technologies or its affiliates in the U.S. and elsewhere (more info here). Other names or brands are trademarks of their respective owners.
    Generated by DocFX on 18 October 2023