共用方式為


建立輸入系統資料提供者 - MRTK2

Mixed Reality工具組輸入系統是一種可延伸的系統,可啟用輸入裝置支援。 若要新增新硬體平臺的支援,可能需要自訂輸入資料提供者。

本文說明如何為輸入系統建立稱為「裝置管理員」的自訂資料提供者。 此處顯示的範例程式碼來自 WindowsMixedRealityDeviceManager

您可以在 MRTK/Providers/WindowsMixedReality 資料夾中找到此範例中使用的完整程式碼。

命名空間和資料夾結構

資料提供者可以散發為協力廠商附加元件或 Microsoft Mixed Reality Toolkit 的一部分。 將新資料提供者提交至 MRTK 的核准程式會依大小寫而有所不同,並在初始提案期間進行通訊。

重要

如果輸入系統資料提供者正在提交至Mixed Reality Toolkit 存放庫,命名空間的開頭必須是Microsoft.MixedReality.Toolkit (:Microsoft.MixedReality.Toolkit.WindowsMixedReality) ,而且程式碼應該位於 MRTK/Providers 底下的資料夾中 (,例如:MRTK/Providers/WindowsMixedReality) 。

命名空間

資料提供者必須有命名空間,才能減輕潛在的名稱衝突。 建議命名空間包含下列元件。

  • 公司名稱
  • 功能區域

例如,Contoso 公司所建立的輸入資料提供者可能是 「Contoso.MixedReality.Toolkit.Input」。

建議將資料提供者的原始程式碼配置在資料夾階層中,如下圖所示。

範例資料夾結構

其中 ContosoInput 包含資料提供者的實作、Editor 資料夾包含 inspector (,以及任何其他 Unity 編輯器特定程式碼) 、Textures 資料夾包含支援的控制器影像,而 Profiles 包含一或多個預先建立的設定檔。

注意

您可以在 MixedRealityToolkit\StandardAssets\Textures 資料夾中找到一些常見的控制器映射。

實作資料提供者

指定介面和/或基類繼承

所有輸入系統資料提供者都必須實 IMixedRealityInputDeviceManager 作 介面,以指定輸入系統所需的最低功能。 MRTK 基礎包含 類別, BaseInputDeviceManager 可提供此必要功能的預設實作。 針對以 Unity UInput 類別建置的裝置, UnityJoystickManager 類別可以當做基類使用。

注意

BaseInputDeviceManagerUnityJoystickManager 類別提供必要的 IMixedRealityInputDeviceManager 實作。

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

IMixedRealityCapabilityCheck 是由 WindowsMixedRealityDeviceManager 使用 來指出它提供一組輸入功能的支援,具體來說,就是表達的手部、注視手勢語音和運動控制器。

套用 MixedRealityDataProvider 屬性

建立輸入系統資料提供者的關鍵步驟是將 MixedRealityDataProvider 屬性套用至 類別。 此步驟可在輸入系統設定檔中選取時,為提供者設定預設設定檔和平臺 (s) 。

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

實作 IMixedRealityDataProvider 方法

定義類別之後,下一個步驟是提供 介面的實作 IMixedRealityDataProvider

注意

類別 BaseInputDeviceManager 透過 BaseService 類別,只提供方法的 IMixedRealityDataProvider 空白實作。 這些方法的詳細資料通常是特定資料提供者。

資料提供者應該實作的方法如下:

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

實作資料提供者邏輯

下一個步驟是新增用於管理輸入裝置的邏輯,包括支援的任何控制器。

實作控制器類別

WindowsMixedRealityDeviceManager 範例會定義並實作下列控制器類別。

您可以在 MRTK/Providers/WindowsMixedReality 資料夾中找到每個類別的原始程式碼。

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

注意

並非所有裝置管理員都支援多個控制器類型。

套用 MixedRealityController 屬性

接下來,將 MixedRealityController 屬性套用至 類別。 此屬性會指定控制器類型 (例如:已表達的手) 、手部 (例如:左或右) 和選擇性控制器映射。

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

設定互動對應

下一個步驟是定義控制器支援的一組互動對應。 對於透過 Unity 的輸入類別接收其資料的裝置, 控制器對應工具 是一項實用的資源,可確認指派給互動的正確座標軸和按鈕對應。

下列範例是從 類別縮寫 GenericOpenVRController ,位於 MRTK/Providers/OpenVR 資料夾中。

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),
};

注意

類別 ControllerMappingLibrary 提供 Unity 輸入軸和按鈕定義的符號常數。

引發通知事件

為了讓應用程式回應使用者的輸入,資料提供者會引發與 和 IMixedRealityInputHandler<T> 介面中所 IMixedRealityInputHandler 定義之控制器狀態變更對應的通知事件。

對於數位 (按鈕) 類型控制項,請引發 OnInputDown 和 OnInputUp 事件。

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

針對類比控制項 (例如:應該引發 InputChanged 事件的觸控板位置) 。

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

新增 Unity Profiler 檢測

混合實境應用程式中的效能非常重要。 每個元件都會增加應用程式必須負責的一些額外負荷。 為此,所有輸入資料提供者都務必在內部迴圈中包含 Unity Profiler 檢測,以及經常使用的程式碼路徑。

建議在檢測自訂提供者時實作 MRTK 所使用的模式。

        private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");

        private async void GetOrAddController(InteractionSourceState interactionSourceState)
        {
            using (GetOrAddControllerPerfMarker.Auto())
            {
                // Code to be measured.
            }
        }

注意

用來識別分析工具標記的名稱是任意的。 MRTK 使用下列模式。

「[product] className.methodName - 選擇性附注」

建議自訂資料提供者遵循類似的模式,以協助簡化分析追蹤時的特定元件和方法的識別。

建立設定檔和偵測器

在 Mixed Reality Toolkit 中,資料提供者是使用設定檔進行設定。

具有其他組態選項的資料提供者 (例如 :InputSimulationService) 應該建立設定檔和偵測器,以允許客戶修改行為,以符合應用程式的需求。

本節範例的完整程式碼可以在 MRTK 中找到。Services/InputSimulation 資料夾。

定義設定檔

設定檔內容應該鏡像觀察者 (的可存取屬性,例如:更新間隔) 。 每個介面中定義的所有使用者可設定屬性都應該包含在設定檔中。

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

屬性 CreateAssetMenu 可以套用至設定檔類別,讓客戶能夠使用 [建立 > 資產 > Mixed Reality工具組 > 設定檔] 功能表來建立設定檔實例。

實作偵測器

設定檔偵測器是用來設定和檢視設定檔內容的使用者介面。 每個設定檔偵測器都應該擴充 'BaseMixedRealityToolkitConfigurationProfileInspector 類別。

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

屬性 CustomEditor 會通知 Unity 套用偵測器的資產類型。

建立元件定義 (s)

Mixed Reality工具組使用元件定義 (.asmdef) 檔案來指定元件之間的相依性,以及協助 Unity 減少編譯時間。

建議針對所有資料提供者及其編輯器元件建立元件定義檔案。

使用先前範例中的 資料夾結構 ,ContosoInput 資料提供者會有兩個 .asmdef 檔案。

第一個元件定義適用于資料提供者。 在此範例中,它會稱為 ContosoInput,而且會位於範例的 ContosoInput 資料夾中。 此元件定義必須指定 Microsoft.MixedReality.Toolkit 的相依性,以及它相依的任何其他元件。

ContosoInputEditor 元件定義會指定設定檔偵測器和任何編輯器特定程式碼。 此檔案必須位於編輯器程式碼的根資料夾中。 在此範例中,檔案會位於 ContosoInput\Editor 資料夾中。 此元件定義將包含 ContosoInput 元件的參考,以及:

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

註冊資料提供者

建立之後,即可向輸入系統註冊資料提供者,並在應用程式中使用。

已註冊的輸入系統資料提供者

封裝和散發

散發為協力廠商元件的資料提供者具有開發人員喜好設定的封裝和散發的特定詳細資料。 可能,最常見的解決方案是產生 .unitypackage,並透過 Unity 資產存放區散發。

如果提交並接受資料提供者作為 Microsoft Mixed Reality Toolkit 套件的一部分,Microsoft MRTK 小組將會封裝並散發為 MRTK 供應專案的一部分。

另請參閱