Skip to content

Commit 55f2803

Browse files
ritamerklritamerkl
committed
restructure processors documentation
1 parent fb786d2 commit 55f2803

4 files changed

Lines changed: 117 additions & 100 deletions

File tree

‎Packages/com.unity.inputsystem/Documentation~/HowToApplyProcessors.md‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
---
2+
uid: input-system-processors
3+
---
4+
# How to apply Processors
5+
6+
The particularities between the three different ways of applying Processors to input events. For more information on the general usage of Processors refer to [Using Processors](UsingProcessors.md).
7+
8+
* [Processors on Bindings](#processors-on-bindings)
9+
* [Processors on Actions](#processors-on-actions)
10+
* [Processors on Controls](#processors-on-controls)
11+
12+
## Processors on Bindings
13+
14+
When you create Bindings for your [actions](Actions.md), you can choose to add Processors to the Bindings. These process the values from the controls they bind to, before the system applies them to the Action value. For instance, you might want to invert the `Vector2` values from the controls along the Y axis before passing these values to the Action that drives the input logic for your application. To do this, you can add an [Invert Vector2](#invert-vector-2) Processor to your Binding.
15+
16+
If you're using Actions defined in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md), you can add any Processor to your Bindings in the Input Action editor. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding. Select the Add (+) icon on the __Processors__ foldout to open a list of all available Processors that match your control type, then choose a Processor type to add a Processor instance of that type. The Processor now appears under the __Processors__ foldout. If the Processor has any parameters, you can edit them in the __Processors__ foldout.
17+
18+
![Binding Processors](Images/BindingProcessors.png)
19+
20+
To remove a Processor, click the Remove (-) icon next to it. You can also use the up and down arrows to change the order of Processors. This affects the order in which the system processes values.
21+
22+
If you create your Bindings in code, you can add Processors like this:
23+
24+
```CSharp
25+
var action = new InputAction();
26+
action.AddBinding("<Gamepad>/leftStick")
27+
.WithProcessor("invertVector2(invertX=false)");
28+
```
29+
30+
## Processors on Actions
31+
32+
Processors on Actions work in the same way as Processors on Bindings, but they affect all controls bound to an Action, rather than just the controls from a specific Binding. If there are Processors on both the Binding and the Action, the system processes the ones from the Binding first.
33+
34+
You can add and edit Processors on Actions in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md) the [same way](#processors-on-bindings) as you would for Bindings: select an Action to edit, then add one or more Processors in the right window pane.
35+
36+
If you create your Actions in code, you can add Processors like this:
37+
38+
```CSharp
39+
var action = new InputAction(processors: "invertVector2(invertX=false)");
40+
```
41+
42+
## Processors on Controls
43+
44+
You can have any number of Processors directly on an [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), which then process the values read from the Control. Whenever you call [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) on a Control, all Processors on that Control process the value before it gets returned to you. You can use [`ReadUnprocessedValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) on a Control to bypass the Processors.
45+
46+
The Input System adds Processors to a Control during device creation, if they're specified in the Control's [layout](Layouts.md). You can't add Processors to existing Controls after they've been created, so you can only add Processors to Controls when you're [creating custom devices](Devices.md#creating-custom-devices). The devices that the Input System supports out of the box already have some useful Processors added on their Controls. For instance, sticks on gamepads have a [Stick Deadzone](#stick-deadzone) Processor.
47+
48+
If you're using a layout generated by the Input System from a [state struct](Devices.md#step-1-the-state-struct) using [`InputControlAttributes`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html), you can specify the Processors you want to use via the [`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors) property of the attribute, like this:
49+
50+
```CSharp
51+
public struct MyDeviceState : IInputStateTypeInfo
52+
{
53+
public FourCC format => return new FourCC('M', 'Y', 'D', 'V');
54+
55+
// Add an axis deadzone to the Control to ignore values
56+
// smaller then 0.2, as our Control does not have a stable
57+
// resting position.
58+
[InputControl(layout = "Axis", processors = "AxisDeadzone(min=0.2)")]
59+
public short axis;
60+
}
61+
```
62+
63+
If you [create a layout from JSON](Layouts.md#layout-from-json), you can specify Processors on your Controls like this:
64+
65+
```CSharp
66+
{
67+
"name" : "MyDevice",
68+
"extend" : "Gamepad", // Or some other thing
69+
"controls" : [
70+
{
71+
"name" : "axis",
72+
"layout" : "Axis",
73+
"offset" : 4,
74+
"format" : "FLT",
75+
"processors" : "AxisDeadzone(min=0.2)"
76+
}
77+
]
78+
}
79+
```

Packages/com.unity.inputsystem/Documentation~/Processors.md renamed to Packages/com.unity.inputsystem/Documentation~/ProcessorTypes.md

Lines changed: 2 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,10 @@
11
---
22
uid: input-system-processors
33
---
4-
# Processors
4+
# Processor Types
55

6-
An Input Processor takes a value and returns a processed result for it. The received value and result value must be of the same type. For example, you can use a [clamp](#clamp) Processor to clamp values from a control to a certain range.
6+
Below you will find predefined processors, furthermore it's possible to create custom Processors. For more information on when to use which type of processor please refer to [Using Processors](UsingProcessors.md).
77

8-
>__Note__: To convert received input values into different types, see [composite Bindings](ActionBindings.md#composite-bindings).
9-
10-
* [Using Processors](#using-processors)
11-
* [Processors on Bindings](#processors-on-bindings)
12-
* [Processors on Actions](#processors-on-actions)
13-
* [Processors on Controls](#processors-on-controls)
148
* [Predefined Processors](#predefined-processors)
159
* [Clamp](#clamp)
1610
* [Invert](#invert)
@@ -26,97 +20,6 @@ An Input Processor takes a value and returns a processed result for it. The rece
2620
* [Stick deadzone](#stick-deadzone)
2721
* [Writing custom Processors](#writing-custom-processors)
2822

29-
## Using Processors
30-
31-
You can install Processors on [bindings](ActionBindings.md), [actions](Actions.md) or on [controls](Controls.md).
32-
33-
Each Processor is [registered](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) using a unique name. To replace an existing Processor, register your own Processor under an existing name.
34-
35-
Processors can have parameters which can be booleans, integers, or floating-point numbers. When created in data such as [bindings](./ActionBindings.md), processors are described as strings that look like function calls:
36-
37-
```CSharp
38-
// This references the processor registered as "scale" and sets its "factor"
39-
// parameter (a floating-point value) to a value of 2.5.
40-
41-
"scale(factor=2.5)"
42-
43-
// Multiple processors can be chained together. They are processed
44-
// from left to right.
45-
//
46-
// Example: First invert the value, then normalize [0..10] values to [0..1].
47-
48-
"invert,normalize(min=0,max=10)"
49-
```
50-
51-
### Processors on Bindings
52-
53-
When you create Bindings for your [actions](Actions.md), you can choose to add Processors to the Bindings. These process the values from the controls they bind to, before the system applies them to the Action value. For instance, you might want to invert the `Vector2` values from the controls along the Y axis before passing these values to the Action that drives the input logic for your application. To do this, you can add an [Invert Vector2](#invert-vector-2) Processor to your Binding.
54-
55-
If you're using Actions defined in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md), you can add any Processor to your Bindings in the Input Action editor. Select the Binding you want to add Processors to so that the right pane of the window displays the properties for that Binding. Select the Add (+) icon on the __Processors__ foldout to open a list of all available Processors that match your control type, then choose a Processor type to add a Processor instance of that type. The Processor now appears under the __Processors__ foldout. If the Processor has any parameters, you can edit them in the __Processors__ foldout.
56-
57-
![Binding Processors](Images/BindingProcessors.png)
58-
59-
To remove a Processor, click the Remove (-) icon next to it. You can also use the up and down arrows to change the order of Processors. This affects the order in which the system processes values.
60-
61-
If you create your Bindings in code, you can add Processors like this:
62-
63-
```CSharp
64-
var action = new InputAction();
65-
action.AddBinding("<Gamepad>/leftStick")
66-
.WithProcessor("invertVector2(invertX=false)");
67-
```
68-
69-
### Processors on Actions
70-
71-
Processors on Actions work in the same way as Processors on Bindings, but they affect all controls bound to an Action, rather than just the controls from a specific Binding. If there are Processors on both the Binding and the Action, the system processes the ones from the Binding first.
72-
73-
You can add and edit Processors on Actions in the [Input Actions Editor](ActionsEditor.md), or in an [Action Asset](ActionAssets.md) the [same way](#processors-on-bindings) as you would for Bindings: select an Action to edit, then add one or more Processors in the right window pane.
74-
75-
If you create your Actions in code, you can add Processors like this:
76-
77-
```CSharp
78-
var action = new InputAction(processors: "invertVector2(invertX=false)");
79-
```
80-
81-
### Processors on Controls
82-
83-
You can have any number of Processors directly on an [`InputControl`](../api/UnityEngine.InputSystem.InputControl.html), which then process the values read from the Control. Whenever you call [`ReadValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadValue) on a Control, all Processors on that Control process the value before it gets returned to you. You can use [`ReadUnprocessedValue`](../api/UnityEngine.InputSystem.InputControl-1.html#UnityEngine_InputSystem_InputControl_1_ReadUnprocessedValue) on a Control to bypass the Processors.
84-
85-
The Input System adds Processors to a Control during device creation, if they're specified in the Control's [layout](Layouts.md). You can't add Processors to existing Controls after they've been created, so you can only add Processors to Controls when you're [creating custom devices](Devices.md#creating-custom-devices). The devices that the Input System supports out of the box already have some useful Processors added on their Controls. For instance, sticks on gamepads have a [Stick Deadzone](#stick-deadzone) Processor.
86-
87-
If you're using a layout generated by the Input System from a [state struct](Devices.md#step-1-the-state-struct) using [`InputControlAttributes`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html), you can specify the Processors you want to use via the [`processors`](../api/UnityEngine.InputSystem.Layouts.InputControlAttribute.html#UnityEngine_InputSystem_Layouts_InputControlAttribute_processors) property of the attribute, like this:
88-
89-
```CSharp
90-
public struct MyDeviceState : IInputStateTypeInfo
91-
{
92-
public FourCC format => return new FourCC('M', 'Y', 'D', 'V');
93-
94-
// Add an axis deadzone to the Control to ignore values
95-
// smaller then 0.2, as our Control does not have a stable
96-
// resting position.
97-
[InputControl(layout = "Axis", processors = "AxisDeadzone(min=0.2)")]
98-
public short axis;
99-
}
100-
```
101-
102-
If you [create a layout from JSON](Layouts.md#layout-from-json), you can specify Processors on your Controls like this:
103-
104-
```CSharp
105-
{
106-
"name" : "MyDevice",
107-
"extend" : "Gamepad", // Or some other thing
108-
"controls" : [
109-
{
110-
"name" : "axis",
111-
"layout" : "Axis",
112-
"offset" : 4,
113-
"format" : "FLT",
114-
"processors" : "AxisDeadzone(min=0.2)"
115-
}
116-
]
117-
}
118-
```
119-
12023
## Predefined Processors
12124

12225
The Input System package comes with a set of useful Processors you can use.

‎Packages/com.unity.inputsystem/Documentation~/TableOfContents.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,10 @@
1717
* [Interactions](Interactions.md)
1818
* [Devices](Devices.md)
1919
* [Controls](Controls.md)
20-
* [Processors](Processors.md)
20+
* [Processors]()
21+
* [Using Processors](UsingProcessors.md)
22+
* [How to apply Processors](HowToApplyProcessors.md)
23+
* [Processor Types](ProcessorTypes.md)
2124
* [Player Input Component](PlayerInput.md)
2225
* [Player Input Manager Component](PlayerInputManager.md)
2326
* [Input settings](Settings.md)

‎Packages/com.unity.inputsystem/Documentation~/UsingProcessors.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
uid: input-system-processors
3+
---
4+
# Using Processors
5+
6+
An Input Processor takes a value and returns a processed result for it. The received value and result value must be of the same type. For example, you can use a [clamp](#clamp) Processor to clamp values from a control to a certain range.
7+
8+
>__Note__: To convert received input values into different types, see [composite Bindings](ActionBindings.md#composite-bindings).
9+
10+
* [Using Processors](#using-processors)
11+
12+
## Using Processors
13+
14+
You can install Processors on [bindings](ActionBindings.md), [actions](Actions.md) or on [controls](Controls.md).
15+
16+
Each Processor is [registered](../api/UnityEngine.InputSystem.InputSystem.html#UnityEngine_InputSystem_InputSystem_RegisterProcessor__1_System_String_) using a unique name. To replace an existing Processor, register your own Processor under an existing name.
17+
18+
Processors can have parameters which can be booleans, integers, or floating-point numbers. When created in data such as [bindings](./ActionBindings.md), processors are described as strings that look like function calls:
19+
20+
```CSharp
21+
// This references the processor registered as "scale" and sets its "factor"
22+
// parameter (a floating-point value) to a value of 2.5.
23+
24+
"scale(factor=2.5)"
25+
26+
// Multiple processors can be chained together. They are processed
27+
// from left to right.
28+
//
29+
// Example: First invert the value, then normalize [0..10] values to [0..1].
30+
31+
"invert,normalize(min=0,max=10)"
32+
```

0 commit comments

Comments
 (0)