Skip to content

Commit dce4c59

Browse files
wiweiwiwei
authored
Merge pull request #3828 from keveleigh/add-porting-doc
Add HTK -> MRTK API porting guide
2 parents 47b0a4a + b782aa1 commit dce4c59

File tree

3 files changed

+136
-1
lines changed

3 files changed

+136
-1
lines changed

‎Documentation/GettingStartedWithTheMRTK.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ To get started with the Mixed Reality Toolkit you will need:
1717

1818
There is not a direct upgrade path from the HoloToolkit to the new Mixed Reality Toolkit due to the rebuilt framework. However, it is possible to import the MRTK into your HoloToolkit project and start work migrating your implementation if you wish.
1919

20-
> The Mixed Reality Team will release a guide in the future on the key differences between HTK and MRTK project implementations.
20+
* [HoloToolkit to Mixed Reality Toolkit Porting Guide](HTKToMRTKPortingGuide.md)
2121

2222
Our recommendation is that if you have an existing HTK project, then it is best to continue with the HTK as it is still a robust and feature rich platform for building HoloLens projects.
2323

‎Documentation/HTKToMRTKPortingGuide.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# Porting Guide
2+
3+
## Controller and hand input
4+
5+
### Setup and configuration
6+
7+
| | HTK 2017 | MRTK v2 |
8+
|---------------------------|----------|-----------|
9+
| Type | Specific events for buttons, with input type info when relevant. | Action / Gesture based input, passed along via events. |
10+
| Setup | Place the InputManager in the scene. | Enable the input system in the Configuration Profile and specify a concrete input system type. |
11+
| Configuration | Configured in the Inspector, on each individual script in the scene. | Configured via the Mixed Reality Input System Profile and its related profile, listed below. |
12+
13+
Related profiles:
14+
* Mixed Reality Controller Mapping Profile
15+
* Mixed Reality Controller Visualization Profile
16+
* Mixed Reality Gestures Profile
17+
* Mixed Reality Input Actions Profile
18+
* Mixed Reality Input Action Rules Profile
19+
* Mixed Reality Pointer Profile
20+
21+
[Gaze Provider](xref:Microsoft.MixedReality.Toolkit.Input.GazeProvider) settings are modified on the Main Camera object in the scene.
22+
23+
Platform support components (e.g., Windows Mixed Reality Device Manager) must be added to their corresponding service's data providers.
24+
25+
### Interface and event mappings
26+
27+
Some events no longer have unique events and now contain a MixedRealityInputAction. These actions are specified in the Input Actions profile and mapped to specific controllers and platforms in the Controller Mapping profile. Events like `OnInputDown` should now check the MixedRealityInputAction type.
28+
29+
| HTK 2017 | MRTK v2 | Action Mapping |
30+
|----------|-----------|----------------|
31+
| `IControllerInputHandler` | [`IMixedRealityInputHandler<Vector2>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) | Mapped to the touchpad or thumbstick |
32+
| `IControllerTouchpadHandler` | [`IMixedRealityInputHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler) | Mapped to the touchpad |
33+
| `IFocusable` | [`IMixedRealityFocusHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityFocusHandler) | |
34+
| `IGamePadHandler` | [`IMixedRealitySourceStateHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealitySourceStateHandler) | |
35+
| `IHoldHandler` | [`IMixedRealityGestureHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityGestureHandler) | Mapped to hold in the Gestures Profile |
36+
| `IInputClickHandler` | [`IMixedRealityPointerHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityPointerHandler) |
37+
| `IInputHandler` | [`IMixedRealityInputHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler) | Mapped to the controller’s buttons or hand tap |
38+
| `IManipulationHandler` | [`IMixedRealityGestureHandler<Vector3>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityGestureHandler`1) | Mapped to manipulation in the Gestures Profile |
39+
| `INavigationHandler` | [`IMixedRealityGestureHandler<Vector3>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityGestureHandler`1) | Mapped to navigation in the Gestures Profile |
40+
| `IPointerSpecificFocusable` | [`IMixedRealityFocusChangedHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityFocusChangedHandler) | |
41+
| `ISelectHandler` | [`IMixedRealityInputHandler<float>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) | Mapped to trigger position |
42+
| `ISourcePositionHandler` | [`IMixedRealityInputHandler<Vector3>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) or [`IMixedRealityInputHandler<MixedRealityPose>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) | Mapped to pointer position or grip position |
43+
| `ISourceRotationHandler` | [`IMixedRealityInputHandler<Quaternion>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) or [`IMixedRealityInputHandler<MixedRealityPose>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) | Mapped to pointer position or grip position |
44+
| `ISourceStateHandler` | [`IMixedRealitySourceStateHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealitySourceStateHandler) | |
45+
| `IXboxControllerHandler` | [`IMixedRealityInputHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler) and [`IMixedRealityInputHandler<Vector2>`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealityInputHandler`1) | Mapped to the various controller buttons and thumbsticks |
46+
47+
## Camera
48+
49+
| | HTK 2017 | MRTK v2 |
50+
|---------------------------|----------|-----------|
51+
| Setup | Delete MainCamera, add MixedRealityCameraParent / MixedRealityCamera / HoloLensCamera prefab to scene **or** use Mixed Reality Toolkit > Configure > Apply Mixed Reality Scene Settings menu item. | MainCamera parented under MixedRealityPlayspace via Mixed Reality Toolkit > Add to Scene and Configure... |
52+
| Configuration | Camera settings configuration performed on prefab instance. | Camera settings configured in the [Mixed Reality Camera Profile](xref:Microsoft.MixedReality.Toolkit.MixedRealityCameraProfile). |
53+
54+
## Speech
55+
56+
### Keyword Recognition
57+
58+
| | HTK 2017 | MRTK v2 |
59+
|---------------------------|----------|-----------|
60+
| Setup | Add a SpeechInputSource to your scene. | Keyword service (e.g., Windows Speech Input Manager) must be added to the input system's data providers. |
61+
| Configuration | Recognized keywords are configured in the SpeechInputSource’s inspector. | Keywords are configured in the [Mixed Reality Speech Commands Profile](Input/Speech.md). |
62+
| Event handlers | `ISpeechHandler` | [`IMixedRealitySpeechHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealitySpeechHandler) |
63+
64+
### Dictation
65+
66+
| | HTK 2017 | MRTK v2 |
67+
|---------------------------|----------|-----------|
68+
| Setup | Add a DictationInputManager to your scene. | Dictation support requires service (e.g., Windows Dictation Input Manager) to be added to the Input System's data providers. |
69+
| Event handlers | `IDictationHandler` | `IMixedRealityDictationHandler`[`IMixedRealitySpeechHandler`](xref:Microsoft.MixedReality.Toolkit.Input.IMixedRealitySpeechHandler) |
70+
71+
## Spatial Awareness / Mapping
72+
73+
### Mesh
74+
75+
| | HTK 2017 | MRTK v2 |
76+
|---------------------------|----------|-----------|
77+
| Setup | Add the SpatialMapping prefab to the scene. | Enable the Spatial Awareness System in the Configuration Profile and add a spatial observer (e.g., Windows Mixed Reality Spatial Mesh Observer) to the Spatial Awareness System's data providers. |
78+
| Configuration | Configure the scene instance in the inspector. | Configure the settings on each spatial observer's profile. |
79+
80+
### Planes
81+
82+
| | HTK 2017 | MRTK v2 |
83+
|---------------------------|----------|-----------|
84+
| Setup | Use the `SurfaceMeshesToPlanes` script. | Not yet implemented. |
85+
86+
### Spatial Understanding
87+
88+
| | HTK 2017 | MRTK v2 |
89+
|---------------------------|----------|-----------|
90+
| Setup | Add the SpatialUnderstanding prefab to the scene. | Not yet implemented. |
91+
| Configuration | Configure the scene instance in the inspector. | Not yet implemented. |
92+
93+
## Boundary
94+
95+
| | HTK 2017 | MRTK v2 |
96+
|---------------------------|----------|-----------|
97+
| Setup | Add the `BoundaryManager` script to the scene. | Enable the Boundary System in the Configuration Profile. |
98+
| Configuration | Configure the scene instance in the inspector. | Configure the settings in the Boundary Visualization profile. |
99+
100+
## Sharing
101+
102+
| | HTK 2017 | MRTK v2 |
103+
|---------------------------|----------|-----------|
104+
| Setup | Sharing service: Add Sharing prefab to the scene. UNet: Use SharingWithUNET example. | In-progress |
105+
| Configuration | Configure the scene instances in the inspector. | In-progress |
106+
107+
## UX
108+
| | HTK 2017 | MRTK v2 |
109+
|---------------------------|----------|-----------|
110+
| Button | [Interactable Objects](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_InteractableObjectExample.md) | [Button](/Documentation/README_Button.md) |
111+
| Interactable | [Interactable Objects](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_InteractableObjectExample.md) | [Interactable](/Documentation/README_Interactable.md) |
112+
| Bounding Box | [Bounding Box](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_BoundingBoxGizmoExample.md) | [Bounding Box](/Documentation/README_BoundingBox.md) |
113+
| App Bar | [App Bar](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_BoundingBoxGizmoExample.md) | [App Bar](/Documentation/README_AppBar.md) |
114+
| One Hand Manipulation (Grb and Move) | [HandDraggable](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit/Input/Scripts/Utilities/Interactions/HandDraggable.cs) | [Manipulation Handler](/Documentation/README_ManipulationHandler.md) |
115+
| Two Hand Manipulation (Grab/Move/Rotate/Scale) | [TwoHandManipulatable](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit/Input/Scripts/Utilities/Interactions/TwoHandManipulatable.cs) | [Manipulation Handler](/Documentation/README_ManipulationHandler.md) |
116+
| Keyboard | [Keyboard prefab]() | [System Keyboard](/Documentation/README_SystemKeyboard.md) |
117+
| Tooltip | [Tooltip](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_TooltipExample.md) | [Tooltip](/Documentation/README_Tooltip.md) |
118+
| Object Collection | [Object Collection](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/UX/Readme/README_ObjectCollection.md) | [Object Collection](/Documentation/README_ObjectCollection.md) |
119+
| Solver | [Solver](https://github.com/Microsoft/MixedRealityToolkit-Unity/blob/htk_release/Assets/HoloToolkit-Examples/Utilities/Readme/README_SolverSystem.md) | [Solver](/Documentation/README_Solver.md) |
120+
121+
122+
## Utilities
123+
124+
Some Utilities have been reconciled as duplicates with the Solver system. Please file an issue if any of your needed scripts are missing.
125+
126+
| HTK 2017 | MRTK v2 |
127+
|----------|-----------|
128+
| Billboard | [`RadialView`](xref:Microsoft.MixedReality.Toolkit.Utilities.Solvers.RadialView) [Solver](/Documentation/README_Solver.md) |
129+
| Tagalong | [`RadialView`](xref:Microsoft.MixedReality.Toolkit.Utilities.Solvers.RadialView) or [`Orbital`](xref:Microsoft.MixedReality.Toolkit.Utilities.Solvers.Orbital) [Solver](/Documentation/README_Solver.md) |
130+
| FixedAngularSize | [`ConstantViewSize`](xref:Microsoft.MixedReality.Toolkit.Utilities.Solvers.ConstantViewSize) [Solver](/Documentation/README_Solver.md) |
131+
| FpsDisplay | [Diagnostics System](Diagnostics/DiagnosticsSystemGettingStarted.md) (in Configuration Profile) |
132+
| NearFade | Built-in to MixedRealityStandard.shader |
133+

‎Documentation/toc.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@
1212
items:
1313
- name: Downloading MRTK
1414
href: DownloadingTheMRTK.md
15+
- name: Upgrading from the HoloToolkit (HTK)
16+
href: HTKToMRTKPortingGuide.md
1517
- name: Core Features
1618
href: TODO.md
1719
items:

0 commit comments

Comments
 (0)