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 gerenciador 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 para o repositório Realidade Misturada Toolkit, o namespace deverá começar com Microsoft.MixedReality.Toolkit (ex: 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".

É recomendável que o código-fonte para provedores de dados seja apresentado em uma hierarquia de pastas, conforme mostrado na imagem a seguir.

Estrutura de pasta de exemplo

Onde 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 os 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 fundação 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 as UnityJoystickManager classes fornecem a implementação necessária IMixedRealityInputDeviceManager .

public class WindowsMixedRealityDeviceManager :
    BaseInputDeviceManager,
    IMixedRealityCapabilityCheck
{ }

IMixedRealityCapabilityCheck é usado pelo WindowsMixedRealityDeviceManager para indicar que ele fornece suporte para um conjunto de recursos de entrada, especificamente; mãos articuladas, mãos de voz de gesto de olhar 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. Essa 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 for 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 são geralmente 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 de WindowsMixedRealityDeviceManager define e implementa as seguintes classes de controlador.

O código-fonte de 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 de controlador opcional.

[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 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 a alterações de estado do IMixedRealityInputHandler controlador, conforme definido no e IMixedRealityInputHandler<T> nas interfaces.

Para controles de tipo digital (botão), aumente 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 (ex: 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 contabilizados. 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 usados com frequência.

É 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

Em Realidade Misturada Toolkit, os provedores de dados são configurados usando perfis.

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 atender melhor à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 espelhar 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 auxiliar o Unity na redução do 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.

Provedores de dados do sistema de entrada registrados

Empacotamento e distribuição

Os provedores de dados que são distribuídos como componentes de terceiros têm os detalhes específicos do empacotamento e da distribuição deixados para a preferência do desenvolvedor. Provavelmente, a solução mais comum será gerar um .unitypackage e distribuir por meio do Unity Asset Store.

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.

Confira também