Criando um provedor de dados do sistema de entrada – MRTK2
O sistema de entrada Realidade Misturada Toolkit é um sistema extensível para habilitar o suporte ao dispositivo de entrada. Para adicionar suporte a uma nova plataforma de hardware, um provedor de dados de entrada personalizado pode ser necessário.
Este artigo descreve como criar provedores de dados personalizados, também chamados de gerenciadores de dispositivos, para o sistema de entrada. O código de exemplo mostrado aqui é do WindowsMixedRealityDeviceManager.
O código completo usado neste exemplo pode ser encontrado na pasta MRTK/Providers/WindowsMixedReality.
Estrutura de namespace e pasta
Os provedores de dados podem ser distribuídos como um complemento de terceiros ou como parte do Microsoft Realidade Misturada Toolkit. O processo de aprovação para envios de novos provedores de dados ao MRTK variará caso a caso e será comunicado no momento da proposta inicial.
Importante
Se um provedor de dados do sistema de entrada estiver sendo enviado ao repositório Realidade Misturada Toolkit, o namespace deverá começar com Microsoft.MixedReality.Toolkit (por exemplo: Microsoft.MixedReality.Toolkit.WindowsMixedReality) e o código deverá estar localizado em uma pasta abaixo de MRTK/Providers (por exemplo, MRTK/Providers/WindowsMixedReality).
Namespace
Os provedores de dados devem ter um namespace para atenuar possíveis colisões de nome. É recomendável que o namespace inclua os seguintes componentes.
- Nome da empresa
- Área do recurso
Por exemplo, um provedor de dados de entrada criado pela empresa Contoso pode ser "Contoso.MixedReality.Toolkit.Input".
Estrutura de pastas recomendada
É recomendável que o código-fonte para provedores de dados seja apresentado em uma hierarquia de pastas, conforme mostrado na imagem a seguir.
Quando ContosoInput contém a implementação do provedor de dados, a pasta Editor contém o inspetor (e qualquer outro código específico do editor do Unity), a pasta Texturas contém imagens dos controladores com suporte e Perfis contém um ou mais perfis pré-feitos.
Observação
Algumas imagens comuns do controlador podem ser encontradas na pasta MixedRealityToolkit\StandardAssets\Textures.
Implementar o provedor de dados
Especificar herança de interface e/ou classe base
Todos os provedores de dados do sistema de entrada devem implementar a IMixedRealityInputDeviceManager interface , que especifica a funcionalidade mínima exigida pelo sistema de entrada. A base do MRTK inclui a BaseInputDeviceManager classe que fornece uma implementação padrão dessa funcionalidade necessária. Para dispositivos que se baseiam na classe UInput do Unity, a UnityJoystickManager classe pode ser usada como uma classe base.
Observação
As BaseInputDeviceManager classes e UnityJoystickManager fornecem a implementação necessária IMixedRealityInputDeviceManager .
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
IMixedRealityCapabilityChecké usado peloWindowsMixedRealityDeviceManagerpara indicar que ele fornece suporte para um conjunto de recursos de entrada, especificamente; mãos articuladas, mãos de olhar-gesto-voz e controladores de movimento.
Aplicar o atributo MixedRealityDataProvider
Uma etapa fundamental da criação de um provedor de dados do sistema de entrada é aplicar o MixedRealityDataProvider atributo à classe . Esta etapa permite definir o perfil padrão e as plataformas para o provedor, quando selecionado no perfil do sistema de entrada.
[MixedRealityDataProvider(
typeof(IMixedRealityInputSystem),
SupportedPlatforms.WindowsUniversal,
"Windows Mixed Reality Device Manager")]
public class WindowsMixedRealityDeviceManager :
BaseInputDeviceManager,
IMixedRealityCapabilityCheck
{ }
Implementar os métodos IMixedRealityDataProvider
Depois que a classe tiver sido definida, a próxima etapa será fornecer a implementação da IMixedRealityDataProvider interface.
Observação
A BaseInputDeviceManager classe , por meio da BaseService classe , fornece apenas implementações vazias para IMixedRealityDataProvider métodos. Os detalhes desses métodos geralmente são específicos do provedor de dados.
Os métodos que devem ser implementados pelo provedor de dados são:
Destroy()Disable()Enable()Initialize()Reset()Update()
Implementar a lógica do provedor de dados
A próxima etapa é adicionar a lógica para gerenciar os dispositivos de entrada, incluindo todos os controladores a serem compatíveis.
Implementar as classes do controlador
O exemplo do WindowsMixedRealityDeviceManager define e implementa as seguintes classes de controlador.
O código-fonte para cada uma dessas classes pode ser encontrado na pasta MRTK/Providers/WindowsMixedReality.
- WindowsMixedRealityArticulatedHand.cs
- WindowsMixedRealityController.cs
- WindowsMixedRealityGGVHand.cs
Observação
Nem todos os gerenciadores de dispositivos darão suporte a vários tipos de controlador.
Aplicar o atributo MixedRealityController
Em seguida, aplique o MixedRealityController atributo à classe . Esse atributo especifica o tipo de controlador (ex: mão articulada), a entrega (ex: esquerda ou direita) e uma imagem opcional do controlador.
[MixedRealityController(
SupportedControllerType.WindowsMixedReality,
new[] { Handedness.Left, Handedness.Right },
"StandardAssets/Textures/MotionController")]
{ }
Configurar os mapeamentos de interação
A próxima etapa é definir o conjunto de mapeamentos de interação com suporte do controlador. Para dispositivos que recebem seus dados por meio da classe De entrada do Unity, a ferramenta de mapeamento do controlador é um recurso útil para confirmar o eixo correto e os mapeamentos de botão a serem atribuídos às interações.
O exemplo a seguir é abreviado da GenericOpenVRController classe , localizada na pasta 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),
};
Observação
A ControllerMappingLibrary classe fornece constantes simbólicas para o eixo de entrada do Unity e definições de botão.
Gerar eventos de notificação
Para permitir que os aplicativos respondam à entrada do usuário, o provedor de dados gera eventos de notificação correspondentes às alterações de estado do IMixedRealityInputHandler controlador, conforme definido nas interfaces e IMixedRealityInputHandler<T> .
Para controles de tipo digital (botão), gere os eventos OnInputDown e 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);
}
Para controles analógicos (por exemplo, posição do touchpad), o evento InputChanged deve ser gerado.
InputSystem?.RaisePositionInputChanged(InputSource, ControllerHandedness, interactionMapping.MixedRealityInputAction, interactionSourceState.touchpadPosition);
Adicionar instrumentação do Unity Profiler
O desempenho é fundamental em aplicativos de realidade misturada. Cada componente adiciona alguma quantidade de sobrecarga para a qual os aplicativos devem ser contabilados. Para isso, é importante que todos os provedores de dados de entrada contenham instrumentação do Unity Profiler em loop interno e caminhos de código frequentemente utilizados.
É recomendável implementar o padrão utilizado pelo MRTK ao instrumentar provedores personalizados.
private static readonly ProfilerMarker GetOrAddControllerPerfMarker = new ProfilerMarker("[MRTK] WindowsMixedRealityDeviceManager.GetOrAddController");
private async void GetOrAddController(InteractionSourceState interactionSourceState)
{
using (GetOrAddControllerPerfMarker.Auto())
{
// Code to be measured.
}
}
Observação
O nome usado para identificar o marcador do criador de perfil é arbitrário. O MRTK usa o padrão a seguir.
"[product] className.methodName - observação opcional"
É recomendável que os provedores de dados personalizados sigam um padrão semelhante para ajudar a simplificar a identificação de componentes e métodos específicos ao analisar rastreamentos.
Criar o perfil e o inspetor
No Realidade Misturada Toolkit, os provedores de dados são configurados usando perfis.
Os provedores de dados com opções de configuração adicionais (por exemplo, InputSimulationService) devem criar um perfil e um inspetor para permitir que os clientes modifiquem o comportamento para melhor atender às necessidades do aplicativo.
O código completo para o exemplo nesta seção pode ser encontrado no MRTK. Pasta Services/InputSimulation.
Definir o perfil
O conteúdo do perfil deve espelho as propriedades acessíveis do observador (por exemplo: intervalo de atualização). Todas as propriedades configuráveis do usuário definidas em cada interface devem estar contidas com o perfil.
[CreateAssetMenu(
menuName = "Mixed Reality Toolkit/Profiles/Mixed Reality Simulated Input Profile",
fileName = "MixedRealityInputSimulationProfile",
order = (int)CreateProfileMenuItemIndices.InputSimulation)]
public class MixedRealityInputSimulationProfile : BaseMixedRealityProfile
{ }
O CreateAssetMenu atributo pode ser aplicado à classe de perfil para permitir que os clientes criem uma instância de perfil usando o menu Criar > Ativos > Realidade Misturada Perfis do Kit de Ferramentas>.
Implementar o inspetor
Os inspetores de perfil são a interface do usuário para configurar e exibir o conteúdo do perfil. Cada inspetor de perfil deve estender a classe 'BaseMixedRealityToolkitConfigurationProfileInspector .
[CustomEditor(typeof(MixedRealityInputSimulationProfile))]
public class MixedRealityInputSimulationProfileInspector : BaseMixedRealityToolkitConfigurationProfileInspector
{ }
O CustomEditor atributo informa ao Unity o tipo de ativo ao qual o inspetor se aplica.
Criar definições de assembly
Realidade Misturada Toolkit usa arquivos de definição de assembly (.asmdef) para especificar dependências entre componentes, bem como para ajudar o Unity a reduzir o tempo de compilação.
É recomendável que os arquivos de definição de assembly sejam criados para todos os provedores de dados e seus componentes do editor.
Usando a estrutura de pastas no exemplo anterior, haveria dois arquivos .asmdef para o provedor de dados ContosoInput.
A primeira definição de assembly é para o provedor de dados. Para este exemplo, ele será chamado contosoInput e estará localizado na pasta ContosoInput do exemplo. Essa definição de assembly deve especificar uma dependência em Microsoft.MixedReality.Toolkit e quaisquer outros assemblies dos quais ela depende.
A definição do assembly ContosoInputEditor especificará o inspetor de perfil e qualquer código específico do editor. Esse arquivo deve estar localizado na pasta raiz do código do editor. Neste exemplo, o arquivo estará localizado na pasta ContosoInput\Editor. Essa definição de assembly conterá uma referência ao assembly ContosoInput, bem como:
- Microsoft.MixedReality.Toolkit
- Microsoft.MixedReality.Toolkit.Editor.Inspectors
- Microsoft.MixedReality.Toolkit.Editor.Utilities
Registrar o provedor de dados
Depois de criado, o provedor de dados pode ser registrado com o sistema de entrada e ser usado no aplicativo.
Empacotamento e distribuição
Os provedores de dados distribuídos como componentes de terceiros têm os detalhes específicos de empacotamento e distribuição deixados para a preferência do desenvolvedor. Provavelmente, a solução mais comum será gerar um .unitypackage e distribuir por meio do Repositório de Ativos do Unity.
Se um provedor de dados for enviado e aceito como parte do pacote microsoft Realidade Misturada Toolkit, a equipe do Microsoft MRTK o empacotará e distribuirá como parte das ofertas do MRTK.