releases/2.5.4mrtk_developmentreleases/2.0.0releases/2.1.0releases/2.2.0releases/2.4.0releases/2.5.0releases/2.5.1releases/2.5.2releases/2.5.3
  • Guides
  • API Documentation

We've moved!

Starting from MRTK 2.6, we are publishing both conceptual docs and API references on docs.microsoft.com. For conceptual docs, please visit our new landing page. For API references, please visit the MRTK-Unity section of the dot net API explorer. Existing content will remain here but will not be updated further.

  • Guides
  • Feature Overviews
  • Input System
  • Input Providers
  • Creating an input data provider

    Show / Hide Table of Contents
    • Getting Started with MRTK
      • Release Notes
      • MRTK Package Contents
      • Updating from earlier versions
      • Upgrading from HTK
      • Building and Deploying MRTK
      • NuGet Packages
      • Getting started with MRTK and XR SDK
      • Performance
      • Hologram Stabilization
    • Architecture
      • Overview
      • Framework and Runtime
      • Input System
        • Terminology
        • Core System
        • Controllers, Pointers, and Focus
      • Systems, Extension Services and Data Providers
    • Feature Overviews
      • Boundary System
        • Boundary System Overview
        • Configuring the Boundary Visualization
      • Camera System
        • Camera System Overview
        • Camera Settings Providers
          • Windows Mixed Reality Camera Settings
          • Unity AR Camera Settings [Experimental]
          • Creating a camera settings provider
      • Cross Platform Support
        • Configure MRTK for iOS and Android
      • Detecting Platform Capabilities
      • Diagnostics System
        • Diagnostics System Overview
        • Configuring the Diagnostics System
        • Using the Visual Profiler
      • Extension Services
        • Extension Service Creation Wizard
        • Scene Transition Service Overview
        • Hand Physics Service Overview
      • Input System
        • Input Overview
        • Input Actions
        • Input Events
        • Input Providers
          • Input Providers Overview
          • Creating an input data provider
        • Controllers
        • Eyes
        • Gaze
        • Gestures
        • Hands
        • How to Add Near Interaction
        • In-Editor Input Simulation
        • Pointers
        • Voice Input
          • Dictation
          • Speech (Command and Control)
      • Multi Scene System
        • Multi Scene System Overview
        • Scene Types
        • Content Scene Loading
        • Monitoring Content Loading
        • Lighting Scene Operations
      • Packaging
        • MRTK Packages
        • MRTK Modularization
      • Profiles
        • Profiles Overview
        • Configuration Guide
      • Rendering
        • Material Instance Overview
        • Shaders
          • MRTK Standard Shader
      • Services
        • What makes a mixed reality feature
        • What are the MixedRealityServiceRegistry and IMixedRealityServiceRegistrar
        • Extension services
      • Spatial Awareness System
        • Spatial Awareness Overview
        • Spatial Observers
          • Configuring Observers for Device
          • Configuring Observers for Editor
          • Controlling Observers via Code
          • Creating a custom Observer
      • Teleport System Overview
      • Tools
        • Dependency Window
        • Extension Service Creation Wizard
        • Holographic Remoting
        • Input Animation Recording
          • Input Animation File Format Specification
        • Optimize Window
        • Runtime tools
          • Controller Mapping tool
      • UX Building Blocks
        • Interactable
        • Button
        • Bounding Box
        • Object Manipulation
        • Sliders
        • Fingertip Visualization
        • App Bar
        • Object Collection
        • Slate
        • System Keyboard
        • Tooltips
        • Solvers
      • Example Scenes
        • Examples Hub
        • Hand Interaction Example
        • Eye Tracking Interaction Example
      • Experimental
        • Scrolling Object Collection
        • Hand Coach UX
        • Pulse Shader
    • Contributing
      • Contributing Overview
      • Coding Guidelines
      • Writing and Running Tests
      • Writing Documentation
      • Pull Requests
      • Experimental Features
      • Breaking Changes
      • How to use DocFX
    • Planning
      • Roadmap
    • Notice
    • Authors

    Creating an input system data provider

    The Mixed Reality Toolkit input system is an extensible system for enabling input device support. To add support for a new hardware platform, a custom input data provider may be required.

    This article describes how to create custom data providers, also called device managers, for the input system. The example code shown here is from the WindowsMixedRealityDeviceManager.

    The complete code used in this example can be found in the MixedRealityToolkit.Providers\WindowsMixedReality folder.

    Namespace and folder structure

    Data providers can be distributed as a third party add-on or as a part of the Microsoft Mixed Reality Toolkit. The approval process for submissions of new data providers to the MRTK will vary on a case-by-case basis and will be communicated at the time of the initial proposal.

    Important

    If an input system data provider is being submitted to the Mixed Reality Toolkit repository, the namespace must begin with Microsoft.MixedReality.Toolkit (ex: Microsoft.MixedReality.Toolkit.WindowsMixedReality) and the code should be located in a folder beneath MixedRealityToolkit.Providers (ex: MixedRealityToolkit.Providers\WindowsMixedReality).

    Namespace

    Data providers are required to have a namespace to mitigate potential name collisions. It is recommended that the namespace includes the following components.

    • Company name
    • Feature area

    For example, an input data provider created by the Contoso company may be "Contoso.MixedReality.Toolkit.Input".

    Recommended folder structure

    It is recommended that the source code for data providers be layed out in a folder hierarchy as shown in the following image.

    Example folder structure

    Where ContosoInput contains the implementation of the data provider, the Editor folder contains the inspector (and any other Unity editor specific code), the Textures folder contains images of the supported controllers, and Profiles contains one or more pre-made profiles.

    Note

    Some common controller images can be found in the MixedRealityToolkit\StandardAssets\Textures folder.

    Implement the data provider

    Specify interface and/or base class inheritance

    All input system data providers must implement the IMixedRealityInputDeviceManager interface, which specifies the minimum functionality required by the input system. The MRTK foundation includes the BaseInputDeviceManager class which provides a default implementation of this required functionality. For devices that build upon Unity's UInput class, the UnityJoystickManager class can be used as a base class.

    Note

    The BaseInputDeviceManager and UnityJoystickManager classes provide the required IMixedRealityInputDeviceManager implementation.

    public class WindowsMixedRealityDeviceManager :
        BaseInputDeviceManager,
        IMixedRealityCapabilityCheck
    { }
    

    IMixedRealityCapabilityCheck is used by the WindowsMixedRealityDeviceManager to indicate that it provides support for a set of input capabilities, specifically; articulated hands, gaze-gesture-voice hands and motion controllers.

    Apply the MixedRealityDataProvider attribute

    A key step of creating an input system data provider is to apply the MixedRealityDataProvider attribute to the class. This step enables setting the default profile and platform(s) for the provider, when selected in the input system profile.

    [MixedRealityDataProvider(
        typeof(IMixedRealityInputSystem),
        SupportedPlatforms.WindowsUniversal,
        "Windows Mixed Reality Device Manager")]
    public class WindowsMixedRealityDeviceManager :
        BaseInputDeviceManager,
        IMixedRealityCapabilityCheck
    { }
    

    Implement the IMixedRealityDataProvider methods

    Once the class has been defined, the next step is to provide the implementation of the IMixedRealityDataProvider interface.

    Note

    The BaseInputDeviceManager class, via the BaseService class, provides only empty implementations for IMixedRealityDataProvider methods. The details of these methods are generally data provider specific.

    The methods that should be implemented by the data provider are:

    • Destroy()
    • Disable()
    • Enable()
    • Initialize()
    • Reset()
    • Update()

    Implement the data provider logic

    The next step is to add the logic for managing the input devices, including any controllers to be supported.

    Implement the controller classes

    The example of the WindowsMixedRealityDeviceManager defines and implements the following controller classes.

    The source code for each of these classes can be found in the MixedRealityToolkit.Providers\WindowsMixedReality folder.

    • WindowsMixedRealityArticulatedHand.cs
    • WindowsMixedRealityController.cs
    • WindowsMixedRealityGGVHand.cs
    Note

    Not all device managers will support multiple controller types.

    Apply the MixedRealityController attribute

    Next, apply the MixedRealityController attribute to the class. This attribute specifies the type of controller (ex: articulated hand), the handedness (ex: left or right) and an optional controller image.

    [MixedRealityController(
        SupportedControllerType.WindowsMixedReality,
        new[] { Handedness.Left, Handedness.Right },
        "StandardAssets/Textures/MotionController")]
    { }
    

    Configure the interaction mappings

    The next step is to define the set of interaction mappings supported by the controller. For devices that receive their data via Unity's Input class, the controller mapping tool is a helpful resource to confirm the correct axis and button mappings to assign to interactions.

    The following example is abbreviated from the GenericOpenVRController class, located in the MixedRealityToolkit.Providers\OpenVR folder.

    public override MixedRealityInteractionMapping[] DefaultLeftHandedInteractions => new[]
    {
        // Controller Pose
        new MixedRealityInteractionMapping(0, "Spatial Pointer", AxisType.SixDof, DeviceInputType.SpatialPointer, MixedRealityInputAction.None),
        // Left Trigger Squeeze
        new MixedRealityInteractionMapping(1, "Trigger Position", AxisType.SingleAxis, DeviceInputType.Trigger, ControllerMappingLibrary.AXIS_9),
        // Left Trigger Press (Select)
        new MixedRealityInteractionMapping(2, "Trigger Press (Select)", AxisType.Digital, DeviceInputType.TriggerPress, KeyCode.JoystickButton14),
    };
    
    Note

    The ControllerMappingLibrary class provides symbolic constants for the Unity input axis and button definitions.

    Raise notification events

    To enable applications to respond to input from the user, the data provider raises notification events corresponding to controller state changes as defined in the IMixedRealityInputHandler and IMixedRealityInputHandler<T> interfaces.

    For digital (button) type controls, raise the OnInputDown and OnInputUp events.

    // inputAction is the input event that is to be raised.
    if (interactionSourceState.touchpadPressed)
    {
        InputSystem?.RaiseOnInputDown(InputSource, ControllerHandedness, inputAction);
    }
    else
    {
        InputSystem?.RaiseOnInputUp(InputSource, ControllerHandedness, inputAction);
    }
    

    For analog controls (ex: touchpad position) the InputChanged event should be raised.

    InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);
    

    Create the profile and inspector

    In the Mixed Reality Toolkit, data providers are configured using profiles.

    Data providers with additional configuration options (ex: InputSimulationService) should create a profile and inspector to allow customers to modify the behavior to best suit the needs of the application.

    The complete code for the example in this section can be found in the MixedRealityToolkit.Services\InputSimulation folder.

    Define the profile

    Profile contents should mirror the accessible properties of the observer (ex: update interval). All of the user configurable properties defined in each interface should be contained with the profile.

    [CreateAssetMenu(
        menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
        fileName = "MixedRealityInputSimulationProfile",
        order = (int)CreateProfileMenuItemIndices.InputSimulation)]
    public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
    { }
    

    The CreateAssetMenu attribute can be applied to the profile class to enable customers to create a profile instance using the Create > Assets > Mixed Reality Toolkit > Profiles menu.

    Implement the inspector

    Profile inspectors are the user interface for configuring and viewing profile contents. Each profile inspector should extend the `BaseMixedRealityToolkitConfigurationProfileInspector class.

    [CustomEditor(typeof(MixedRealityInputSimulationProfile))]
    public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
    { }
    

    The CustomEditor attribute informs Unity the type of asset to which the inspector applies.

    Create assembly definition(s)

    The Mixed Reality Toolkit uses assembly definition (.asmdef) files to specify dependencies between components as well as to assist Unity in reducing compilation time.

    It is recommended that assembly definition files are created for all data providers and their editor components.

    Using the folder structure in the earlier example, there would be two .asmdef files for the ContosoInput data provider.

    The first assembly definition is for the data provider. For this example, it will be called ContosoInput and will be located in the example's ContosoInput folder. This assembly definition must specify a dependency on Microsoft.MixedReality.Toolkit and any other assemblies upon which it depends.

    The ContosoInputEditor assembly definition will specify the profile inspector and any editor specific code. This file must be located in the root folder of the editor code. In this example, the file will be located in the ContosoInput\Editor folder. This assembly definition will contain a reference to the ContosoInput assembly as well as:

    • Microsoft.MixedReality.Toolkit
    • Microsoft.MixedReality.Toolkit.Editor.Inspectors
    • Microsoft.MixedReality.Toolkit.Editor.Utilities

    Register the data provider

    Once created, the data provider can be registered with the input system and be used in the application.

    Registered input system data providers

    Packaging and distribution

    Data providers that are distributed as third party components have the specific details of packaging and distribution left to the preference of the developer. Likely, the most common solution will be to generate a .unitypackage and distribute via the Unity Asset Store.

    If a data provider is submitted and accepted as a part of the Microsoft Mixed Reality Toolkit package, the Microsoft MRTK team will package and distribute it as part of the MRTK offerings.

    See also

    • Input system
    • BaseInputDeviceManager class
    • IMixedRealityInputDeviceManager interface
    • IMixedRealityInputHandler interface
    • IMixedRealityInputHandler<T> interface
    • IMixedRealityDataProvider interface
    • IMixedRealityCapabilityCheck interface
    • Controller Mapping Tool
    • Improve this Doc
    In This Article
    • Namespace and folder structure
      • Namespace
      • Recommended folder structure
    • Implement the data provider
      • Specify interface and/or base class inheritance
        • Apply the MixedRealityDataProvider attribute
      • Implement the IMixedRealityDataProvider methods
      • Implement the data provider logic
      • Implement the controller classes
        • Apply the MixedRealityController attribute
        • Configure the interaction mappings
      • Raise notification events
    • Create the profile and inspector
      • Define the profile
      • Implement the inspector
    • Create assembly definition(s)
    • Register the data provider
    • Packaging and distribution
    • See also
    Back to top Generated by DocFX