Merge pull request #3731 from cre8ivepark/mrtk_development_hl2_README

Adding new README files

Author: keveleigh

Documentation/GettingStartedWithTheMRTK.md

@@ -162,4 +162,20 @@ For more information on the rest of the toolkit, please check the following guid
 * [Creating interactions between the player and your project]() (Coming Soon)
 * [Configuration Profile Usage Guide]() (Coming Soon)
 * [Guide to building Registered Services]() (Coming Soon)
-* [Guide to Pointers documentation]() (Coming Soon)
+* [Guide to Pointers documentation]() (Coming Soon)
+
+## Building blocks for UI and Interactions
+|  [![Button](/External/ReadMeImages/Button/MRTK_Button_Main.png)](/Documentation/README_Button.md) [Button](/Documentation/README_Button.md) | [![Bounding Box](/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Main.png)](/Documentation/README_BoundingBox.md) [Bounding Box](/Documentation/README_BoundingBox.md) | [![Manipulation Handler](/External/ReadMeImages/ManipulationHandler/MRTK_Manipulation_Main.png)](/Documentation/README_ManipulationHandler.md) [Manipulation Handler](/Documentation/README_ManipulationHandler.md) |
+|:--- | :--- | :--- |
+| A button control which supports various input methods including HoloLens2's articulated hand | Standard UI for manipulating objects in 3D space | Script for manipulating objects with one or two hands |
+|  [![Slate](/External/ReadMeImages/Slate/MRTK_Slate_Main.png)](/Documentation/README_Slate.md) [Slate](/Documentation/README_Slate.md) | [![System Keyboard](/External/ReadMeImages/SystemKeyboard/MRTK_SystemKeyboard_Main.png)](/Documentation/README_SystemKeyboard.md) [System Keyboard](/Documentation/README_SystemKeyboard.md) | [![Interactable](/External/ReadMeImages/Interactable/InteractableExamples.png)](/Documentation/README_Interactable.md) [Interactable](/Documentation/README_Interactable.md) |
+| 2D style plane which supports scrolling with articulated hand input | Example script of using the system keyboard in Unity  | A script for making objects interactable with visual states and theme support |
+|  [![Solver](/External/ReadMeImages/Solver/MRTK_Solver_Main.png)](/Documentation/README_Solver.md) [Solver](/Documentation/README_Solver.md) | [![Object Collection](/External/ReadMeImages/ObjectCollection/MRTK_ObjectCollection_Main.png)](/Documentation/README_ObjectCollection.md) [Object Collection](/Documentation/README_ObjectCollection.md) | [![Tooltip](/External/ReadMeImages/Tooltip/MRTK_Tooltip_Main.png)](/Documentation/README_Tooltip.md) [Tooltip](/Documentation/README_Tooltip.md) |
+| Various object positioning behaviors such as tag-along, body-lock, constant view size and surface magnetism | Script for lay out an array of objects in a three-dimensional shape | Annotation UI with flexible anchor/pivot system which can be used for labeling motion controllers and object. |
+|  [![App Bar](/External/ReadMeImages/AppBar/MRTK_AppBar_Main.png)](/Documentation/README_AppBar.md) [App Bar](/Documentation/README_AppBar.md) | [![Pointers](/External/ReadMeImages/Pointers/MRTK_Pointer_Main.png)](/Documentation/README_Pointers.md) [Pointers](/Documentation/README_Pointers.md) | [![Fingertip Visualization](/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_Main.png)](/Documentation/README_FingertipVisualization.md) [Fingertip Visualization](/Documentation/README_FingertipVisualization.md) |
+| UI for Bounding Box's manual activation | Learn about various types of pointers | Visual affordance on the fingertip which improves the confidence for the direct interaction |
+
+## Example Scene
+You can find various types of interactions and UI controls in this example scene.
+
+[![Button](/External/ReadMeImages/MRTK_Examples.png)](/Documentation/README_HandInteractionExamples.md)

Documentation/README_AppBar.md

@@ -0,0 +1,12 @@
+# App Bar
+![App Bar](/External/ReadMeImages/AppBar/MRTK_AppBar_Main.png)
+
+App Bar is a UI component used with Bounding Box. Using the 'Adjust' button, you can turn on/off the Bounding Box interface for manipulating object.
+
+## How to use App Bar
+Drog and drop **AppBar** prefab into the scene hierarchy. In the inspector panel of the AppBar, you will see **Bounding Box** under **Target Bounding Box** section. Assign any objects that has Bounding Box. **Important: Target object's Bounding Box activation option should be 'Activate Manually'**
+
+<img src="/External/ReadMeImages/AppBar/MRTK_AppBar_Setup1.png" width="450">
+
+<img src="/External/ReadMeImages/AppBar/MRTK_AppBar_Setup2.png" width="450">
+

Documentation/README_BoundingBox.md

@@ -0,0 +1,64 @@
+# Bounding Box #
+![Bounding Box](/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Main.png)
+
+The `BoundingBox` script provides basic functionality for transforming objects in Windows Mixed Reality. Using handles on the corners and edges, you can scale or rotate the object. On HoloLens 2, the bounding box responds to your finger's proximity. It shows visual feedback to help perceive the distance from the object. MRTK's bounding box provides various options which allow you to easily customize the interactions and visuals. 
+
+For more information please see [App Bar and Bounding Box](https://docs.microsoft.com/en-us/windows/mixed-reality/app-bar-and-bounding-box) on Windows Dev Center.
+
+### How to use Bounding Box ###
+You can enable Bounding Box by simply assigning the `BoundingBox` script to any GameObject.
+
+![Bounding Box](/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Assign.png)
+
+### Example Scene ###
+You can find bounding box examples in the *HandInteractionExamples.unity* scene:
+
+<img src="/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Examples.png" width="550">
+
+### Inspector Properties ###
+![Bounding Box](/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Structure.png)
+
+#### Target Object ####
+This specifies which object will get transformed by the bounding box manipulation. If no object is set, the bounding box defaults to the owner object.
+
+#### Bounds Override ####
+Allows to alternatively set a box collider from another object for bounds computation.
+
+#### Activation Behavior #### 
+There are several options to activate the bounding box interface.
+ 
+- **Activate On Start** : Bounding Box becomes visible once the scene is started.
+- **Activate By Proximity** : Bounding Box becomes visible when an articulated hand is close to the object.
+- **Activate By Pointer** : Bounding Box becomes visible when it is targeted by a hand-ray pointer.
+- **Activate Manually** : Bounding Box does not become visible automatically. You can manually activate it through a script by accessing the boundingBox.Active property.
+
+#### Scale Minimum ####
+The minimum allowed scale.
+
+#### Scale Maximum ####
+The maximum allowed scale.
+ 
+#### Box Display #### 
+Various bounding box visualization options.
+
+If Flatten Axis is set to *Flatten Auto*, the script will disallow manipulation along the axis with the smallest extent. This results in a 2D bounding box, which is usually used for thin objects.
+ 
+#### Handles #### 
+You can assign the material and prefab to override the handle style. If no handles are assigned, they will be displayed in the default style.
+ 
+#### Events #### 
+Bounding Box provides the following events. The example uses these events to play audio feedback.
+
+- **Rotate Started**
+- **Rotate Ended**
+- **Scale Started**
+- **Scale Ended**
+
+<img src="/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_Events.png" width="450">
+
+### Make an object movable with Manipulation Handler ###
+If you want to make the object movable using far interaction, you can combine [`ManipulationHandler.cs`](README_ManipulationHandler.md) with `BoundingBox.cs`. [ManipulationHandler](README_ManipulationHandler.md) supports both one and two-handed interactions. To make [`ManipulationHandler.cs`](README_ManipulationHandler.md) work with near interaction, you should add `NearInteractionGrabbable.cs` too.
+
+<img src="/External/ReadMeImages/BoundingBox/MRTK_BoundingBox_ManipulationHandler.png" width="450">
+
+In order for the bounding box edges to be highlighted the same way when moving it using [`ManipulationHandler`](README_ManipulationHandler.md)'s far interaction, it is advised to connect its events for **On Manipulation Started** / **On Manipulation Ended** to `BoundingBox.HightlightWires` / `BoundingBox.UnhighlightWires` respectively, as shown in the screenshot above.

Documentation/README_Button.md

@@ -0,0 +1,84 @@
+# Button #
+![Button](/External/ReadMeImages/Button/MRTK_Button_Main.png)
+The button supports all available input methods including articulated hand input for the near interactions and gaze + air-tap for the far interactions. You can also use voice command to trigger the button.
+
+## How to use the Pressable Button prefab
+Simply drag [PressableButton.prefab](/Assets/MixedRealityToolkit.SDK/Features/UX/Interactable/Prefabs/PressableButton.prefab) or [PressableButtonPlated.prefab](/Assets/MixedRealityToolkit.SDK/Features/UX/Interactable/Prefabs/PressableButtonPlated.prefab) into the scene. These button prefabs are already configured to have audio-visual feedback for the various types of inputs, including articulated hand input and gaze. The events exposed in the `PressableButton` and the [`Interactable`](README_Interactable.md) component can be used to trigger additional actions. 
+
+The Pressable Buttons in the HandInteractionExamples scene use [`Interactable`](README_Interactable.md)'s *OnClick* event to trigger a change in the color of a cube. This event gets triggered for different types of input methods such as gaze, air-tap, hand-ray, as well as physical button presses through the `PressableButton` script.
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_HowToUse_Interactable.png" width="450">
+
+You can configure when the `PressableButton` fires the [`Interactable`](README_Interactable.md)'s *OnClick* event via the `PhysicalPressEventRouter` on the button. For example, you can set *OnClick* to fire when the button is first pressed, as opposed to be pressed, and then released, by setting *Interactable On Click* to *Event On Press*.
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_HowTo_Events.png" width="450">
+
+To leverage specific articulated hand input state information, you can use `PressableButton`'s events - *Touch Begin*, *Touch End*, *Button Pressed*, *Button Released*. These events will not fire in response to air-tap, hand-ray, or eye inputs, however.
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_HowTo_PressableButton.png" width="450">
+
+## Interaction States
+In the idle state, the button's front plate is not visible. As a finger approaches or a cursor from gaze input targets the surface, the front plate's glowing border becomes visible. There is additional highlighting of the fingertip position on the front plate surface. When pushed with a finger, the front plate moves with the fingertip. When the fingertip touches the surface of the front plate, it shows a subtle pulse effect to give visual feedback of the touch point.
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_InteractionStates.png" width="600">
+
+The subtle pulse effect is triggerd by the `PressableButton.` The `PressableButton` looks for `ProximityLight(s)` that live on the currently interacting pointer. If any `ProximityLight(s)` are found, the ProximityLight.Pulse method is called which automatically animates shader parameters to display a pulse.
+
+## Property Inspector of PressableButton 
+![Button](/External/ReadMeImages/Button/MRTK_Button_Structure.png)
+
+The Pressable Button prefab is consists of the following elements:
+
+#### Box Collider
+`Box Collider` for the button's front plate.
+
+#### Pressable Button
+The logic for the button movement with hand press interaction.
+
+#### Physical Press Event Router
+This script sends events from hand press interaction to [`Interactable`](README_Interactable.md).
+
+#### Interactable
+[`Interactable`](README_Interactable.md) handles various types of interaction states and events. HoloLens gaze, gesture, and voice input and immersive headset motion controller input are directly handled by this script.
+
+#### Audio Source
+Unity `Audio Source` for the audio feedback clips
+
+#### NearInteractionTouchable.cs
+Required to make any object touchable with articulated hand input.
+
+### Prefab Layout
+![Button](/External/ReadMeImages/Button/MRTK_Button_Layout.png)
+
+The *ButtonContent* object contains front plate, text label and icon. The *FrontPlate* responds to the proximity of the index fingertip using the *Button_Box* shader. It shows glowing borders, proximity light, and a pulse effect on touch. The text label is made with TextMesh Pro. *SeeItSayItLabel*'s visibility is controlled by [`Interactable`](README_Interactable.md)'s theme.
+
+## Voice command ('See-it, Say-it')
+
+#### Speech Input Handler
+The [`Interactable`](README_Interactable.md) script in Pressable Button already implements IMixedRealitySpeechHandler. A voice command keyword can be set here. 
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Speech1.png" width="450">
+
+#### Speech Input Profile
+Additionally, you need to register the voice command keyword in the global `Speech Commands Profile`. 
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Speech2.png" width="450">
+
+#### See-it, Say-it label
+The Pressable Button prefab has a placeholder TextMesh Pro label under the *SeeItSayItLabel* object. You can use this label to communicate the voice command keyword for the button to the user.
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Speech3.png" width="450">
+
+## Using PressableButton on other types of objects
+
+You can use the `PressableButton`s script to configure an object to react to finger pushes.
+
+In the HandInteractionExamples scene, you can take a look at the piano and round button examples which are both using `PressableButton`. 
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Custom1.png" width="450">
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Custom2.png" width="450">
+
+Each piano key has a `PressableButton` and a `NearInteractionTouchable` script assigned. It is important to verify that the *Local Forward* direction of `NearInteractionTouchable` is correct. It is represented by a white arrow in the editor. Make sure the arrow points away from the button's front face:
+
+<img src="/External/ReadMeImages/Button/MRTK_Button_Custom3.png" width="450">

Documentation/README_FingertipVisualization.md

@@ -0,0 +1,38 @@
+# Fingertip Visualization
+![Fingertip Visualization](/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_Main.png)
+
+The fingertip affordance helps the user recognize the distance from the target object. The ring shape visual adjusts its size based on the distance from the fingertip to the object. The fingertip visualization is primarily controlled by the `FingerCursor` prefab (and script) which is spawned as the cursor prefab of the `PokePointer`. Other components of the visualization include the `ProximityLight` script, and `MixedRealityStandard` shader.
+
+### How to use the Fingertip Visualization ###
+
+By default the fingertip visualization will work in any Unity scene that is configured to spawn a FingerCursor. Spawning of the FingerCursor occurs in the `DefaultMixedRealityToolkitConfigurationProfile` under: 
+
+- DefaultMixedRealityInputSystemProfile
+    - DefaultMixedRealityInputPointerProfile
+        - PokePointer
+            - FingerCursor
+
+At a high level the fingertip visualization works by using a proximity light to project a colored gradient on any nearby surfaces that accept proximity lights. The finger cursor then looks for any nearby interactible surfaces, which are determined by parent IMixedRealityNearPointer(s), to align the finger ring with a surface as the finger moves towards a surface. As a finger approaches a surface the finger ring is also dynamically animated using the round corner properties of the MixedRealityStandard shader.
+
+### Example Scene ###
+
+You can find fingertip visualization examples in almost any scene that works with articulated hands, but is prominent in the HandInteractionExamples.unity scene.
+
+![Fingertip Visualization](/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_States.png)
+
+### Inspector Properties ###
+
+#### FingerCursor ####
+<img src="/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_Finger_Cursor_Inspector.png" width="600">
+
+Many of the FingerCursor properties are inherited from the BaseCursor class. Important properties include the far/near surface margins and widths which drive the finger ring animation in the MixedRealityStandard shader. For other properties please hover over the inspector tool tips.
+
+#### ProximityLight ####
+![Fingertip Visualization](/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_Proximity_Light_Inspector.png)
+
+The proximity light settings control how the light looks when near and far from a surface. The center, middle, and outer colors control the gradient look of the light and can be custom tailored for the color palette of your application. Note, the colors are HDR (High Dynamic Range) to allow users to brighten the proximity light to values above one. For other properties please hover over the inspector tool tips.
+
+#### MixedRealityStandard Shader ####
+<img src="/External/ReadMeImages/Fingertip/MRTK_FingertipVisualization_Mixed_Reality_Standard_Shader_Inspector.png" width="600">
+
+The MixedRealityStandard shader is used for many effects in the MRTK. The two settings important for fingertip visualization are "Near Fade" and "Proximity Light." Near Fade allows objects to fade in/out as a camera or light nears them. Make sure to check "Light" to allow proximity lights to drive the fade (rather than the camera). You can reverse the values of "Fade Begin" and "Fade Complete" to reverse a fade. Check "Proximity Light" for any surface you would like the proximity light to brighten. For other properties please hover over the inspector tool tips.

Documentation/README_HandInteractionExamples.md

@@ -0,0 +1,34 @@
+# Hand Interaction Examples scene
+![Hand Interaction Examples](/External/ReadMeImages/MRTK_Examples.png)
+
+In this example scene, you can find various types of interactions and UI controls that supports HoloLens2's articulated hand input.
+You can find the **HandInteractionExamples.unity** scene under **Assets\MixedRealityToolkit.Examples\Demos\HandTracking\Scenes**
+
+*This example scene uses **TextMesh Pro**. Please click **'Import TMP Essentials'** button when you see this prompt. Unity will import TextMesh Pro packages*
+
+<img src="/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_TMP2.png" width="450">
+
+*If you see big text after TextMesh Pro import, please open other Unity scene and open this scene again.*
+
+<img src="/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_TMP1.png" width="350">
+
+
+## Pressable Button
+See [Button](README_Button.md) page for the details.
+![Hand Interaction Examples](/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_PressTouch.png)
+
+## Bounding Box
+See [Bounding Box](README_BoundingBox.md) page for the details.
+![Hand Interaction Examples](/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_BoundingBox.png)
+
+## Manipulation Handler
+See [Manipulation Handler](README_ManipulationHandler.md) page for the details.
+![Hand Interaction Examples](/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_Manipulation.png)
+
+## Slate
+See [Slate](README_Slate.md) page for the details.
+![Hand Interaction Examples](/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_Slate.png)
+
+## System Keyboard
+See [System Keyboard](README_SystemKeyboard.md) page for the details.
+![Hand Interaction Examples](/External/ReadMeImages/HandInteractionExamples/MRTK_Examples_Keyboard.png)