Xamarin.Essentials: Sensor de orientação

A classe OrientationSensor permite monitorar a orientação de um dispositivo no espaço tridimensional.

Introdução

Para começar a usar essa API, leia o guia de introdução para Xamarin.Essentials garantir que a biblioteca esteja instalada e configurada corretamente em seus projetos.

Uso do OrientationSensor

Adicione uma referência a Xamarin.Essentials em sua classe:

using Xamarin.Essentials;

O OrientationSensor é habilitado pela chamada do método Start, para monitorar as alterações da orientação do dispositivo, e desabilitado chamando o método Stop. Todas as alterações são enviadas de volta por meio do evento ReadingChanged. Veja um exemplo de uso:

public class OrientationSensorTest
{
    // Set speed delay for monitoring changes.
    SensorSpeed speed = SensorSpeed.UI;

    public OrientationSensorTest()
    {
        // Register for reading changes, be sure to unsubscribe when finished
        OrientationSensor.ReadingChanged += OrientationSensor_ReadingChanged;
    }

    void OrientationSensor_ReadingChanged(object sender, OrientationSensorChangedEventArgs e)
    {
        var data = e.Reading;
        Console.WriteLine($"Reading: X: {data.Orientation.X}, Y: {data.Orientation.Y}, Z: {data.Orientation.Z}, W: {data.Orientation.W}");
        // Process Orientation quaternion (X, Y, Z, and W)
    }

    public void ToggleOrientationSensor()
    {
        try
        {
            if (OrientationSensor.IsMonitoring)
                OrientationSensor.Stop();
            else
                OrientationSensor.Start(speed);
        }
        catch (FeatureNotSupportedException fnsEx)
        {
            // Feature not supported on device
        }
        catch (Exception ex)
        {
            // Other error has occurred.
        }
    }
}

As leituras OrientationSensor são apresentadas na forma de um Quaternion que descreve a orientação do dispositivo com base em dois sistemas de coordenadas 3D:

O dispositivo (geralmente um telefone ou tablet) possui um sistema de coordenadas 3D com os seguintes eixos:

• O eixo positivo X aponta para o canto direito do visor no modo retrato.
• O eixo positivo Y aponta para o canto superior do dispositivo no modo retrato.
• O eixo positivo Z aponta para fora da tela.

O sistema de coordenadas 3D da Terra tem os seguintes eixos:

• O eixo positivo X é a tangente da superfície da Terra e aponta para leste.
• O eixo positivo Y também é a tangente da superfície da Terra e aponta para norte.
• O eixo positivo Z é perpendicular à superfície da Terra e aponta para cima.

O Quaternion descreve a rotação do sistema de coordenadas do dispositivo em relação ao sistema de coordenadas da Terra.

Um valor Quaternion está muito intimamente relacionado à rotação em torno de um eixo. Se um eixo de rotação for o vetor normalizado (a_x, a_y, a_z) e o ângulo de rotação for Θ, então, os componentes (X, Y, Z, W) do quatérnio serão:

(a_x·sin(Θ/2), a_y·sin(Θ/2), a_z·sin(Θ/2), cos(Θ/2))

Estes são sistemas de coordenadas à direita, portanto, com o polegar da mão direita apontado na direção positiva do eixo de rotação, a curva dos dedos indica a direção da rotação para ângulos positivos.

Exemplos:

• Os dois sistemas de coordenadas estarão alinhados quando o dispositivo estiver em uma mesa com a tela voltada para cima e a parte superior do dispositivo (no modo retrato) estiver apontando para norte. O valor Quaternion representa o quatérnio da identidade (0, 0, 0, 1). Todas as rotações podem ser analisadas em relação a essa posição.

• O valor Quaternion será (0, 0, 0.707, 0.707) quando dispositivo estiver em uma mesa com a tela voltada para cima e a parte superior do dispositivo (no modo retrato) estiver apontando para oeste. O dispositivo girou 90 graus em torno do eixo Z da Terra.

• O dispositivo terá girado 90 graus ao redor do eixo X quando for colocado na posição vertical de modo que a parte superior (no modo retrato) aponte para o céu e a parte de trás do dispositivo fique voltada para norte. O valor Quaternion é (0.707, 0, 0, 0.707).

• Se o dispositivo estiver posicionado de forma que sua borda esquerda fique em uma mesa e a parte superior apontar para o norte, o dispositivo foi girado –90 graus em torno do eixo Y (ou 90 graus em torno do eixo Y negativo). O valor Quaternion é (0, -0.707, 0, 0.707).

Sensor de velocidade

• Mais rápido – obtenha os dados do sensor o mais rápido possível (não é garantido retornar no thread de interface do usuário).
• Jogo – taxa adequada para jogos (não é garantido retornar no thread de interface do usuário).
• Padrão – Taxa padrão adequada para alterações na orientação da tela.
• Interface do usuário – taxa adequada para a interface do usuário geral.

Se o manipulador de eventos não tiver a garantia de ser executado no thread da interface do usuário e se precisar acessar os elementos de interface do usuário, use o método MainThread.BeginInvokeOnMainThread para executar esse código no thread da interface do usuário.

API

• Código-fonte do OrientationSensor
• Documentação da API do OrientationSensor