Orientation​Sensor Orientation​Sensor Orientation​Sensor Class

Definition

Represents an orientation sensor.

This sensor returns a rotation matrix and a Quaternion that can be used to adjust the user's perspective in a game application.

public sealed class OrientationSensor : IOrientationSensor, IOrientationSensor2, IOrientationSensorDeviceIdpublic sealed class OrientationSensor : IOrientationSensor, IOrientationSensor2, IOrientationSensorDeviceIdPublic NotInheritable Class OrientationSensor Implements IOrientationSensor, IOrientationSensor2, IOrientationSensorDeviceId
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Sensor data is provided relative to the device's fixed sensor coordinate system, and is independent of display orientation. For applications that rely on sensor data for input control or to manipulate elements on the screen, the developer must take current display orientation into account and compensate the data appropriately. For more info about the sensor coordinate system, see Sensor data and display orientation.

The following example demonstrates how a Windows Store app built with XAML and C# uses the GetDefault method to establish a connection to an orientation sensor. If no orientation sensor is found, the method will return a null value.

_sensor = OrientationSensor.GetDefault();

The following example demonstrates how a Windows Store app built with XAML registers a ReadingChanged event handler.

private void ScenarioEnable(object sender, RoutedEventArgs e)
{
    if (_sensor != null)
    {
        // Establish the report interval
        _sensor.ReportInterval = _desiredReportInterval;

        Window.Current.VisibilityChanged += new WindowVisibilityChangedEventHandler(VisibilityChanged);
        _sensor.ReadingChanged += new TypedEventHandler<OrientationSensor, OrientationSensorReadingChangedEventArgs>(ReadingChanged);

        ScenarioEnableButton.IsEnabled = false;
        ScenarioDisableButton.IsEnabled = true;
    }
    else
    {
        rootPage.NotifyUser("No orientation sensor found", NotifyType.StatusMessage);
    }
}

The following example shows the ReadingChanged event handler.

async private void ReadingChanged(object sender, OrientationSensorReadingChangedEventArgs e)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OrientationSensorReading reading = e.Reading;

        // Quaternion values
        SensorQuaternion quaternion = reading.Quaternion;   // get a reference to the object to avoid re-creating it for each access
        ScenarioOutput_X.Text = String.Format("{0,8:0.00000}", quaternion.X);
        ScenarioOutput_Y.Text = String.Format("{0,8:0.00000}", quaternion.Y);
        ScenarioOutput_Z.Text = String.Format("{0,8:0.00000}", quaternion.Z);
        ScenarioOutput_W.Text = String.Format("{0,8:0.00000}", quaternion.W);

        // Rotation Matrix values
        SensorRotationMatrix rotationMatrix = reading.RotationMatrix;
        ScenarioOutput_M11.Text = String.Format("{0,8:0.00000}", rotationMatrix.M11);
        ScenarioOutput_M12.Text = String.Format("{0,8:0.00000}", rotationMatrix.M12);
        ScenarioOutput_M13.Text = String.Format("{0,8:0.00000}", rotationMatrix.M13);
        ScenarioOutput_M21.Text = String.Format("{0,8:0.00000}", rotationMatrix.M21);
        ScenarioOutput_M22.Text = String.Format("{0,8:0.00000}", rotationMatrix.M22);
        ScenarioOutput_M23.Text = String.Format("{0,8:0.00000}", rotationMatrix.M23);
        ScenarioOutput_M31.Text = String.Format("{0,8:0.00000}", rotationMatrix.M31);
        ScenarioOutput_M32.Text = String.Format("{0,8:0.00000}", rotationMatrix.M32);
        ScenarioOutput_M33.Text = String.Format("{0,8:0.00000}", rotationMatrix.M33);
    });
}

Properties

DeviceId DeviceId DeviceId

Gets the device identifier.

public PlatForm::String DeviceId { get; }public string DeviceId { get; }Public ReadOnly Property DeviceId As string
Value
string string string

The device identifier.

Attributes

MinimumReportInterval MinimumReportInterval MinimumReportInterval

Gets the minimum report interval supported by the sensor.

public unsigned short MinimumReportInterval { get; }public uint MinimumReportInterval { get; }Public ReadOnly Property MinimumReportInterval As uint
Value
uint uint uint

The minimum ReportInterval supported by the sensor.

Attributes

ReadingTransform ReadingTransform ReadingTransform

Gets or sets the transformation that needs to be applied to sensor data. Transformations to be applied are tied to the display orientation with which to align the sensor data.

public DisplayOrientations ReadingTransform { get; set; }public DisplayOrientations ReadingTransform { get; set; }Public ReadWrite Property ReadingTransform As DisplayOrientations
Value
DisplayOrientations DisplayOrientations DisplayOrientations

A DisplayOrientations -typed value that specifies the display orientation with which to align the sensor data.

Attributes

ReadingType ReadingType ReadingType

Gets the sensor reading type.

public SensorReadingType ReadingType { get; }public SensorReadingType ReadingType { get; }Public ReadOnly Property ReadingType As SensorReadingType
Value
SensorReadingType SensorReadingType SensorReadingType

A SensorReadingType -typed value that specifies the sensor reading type.

Attributes

ReportInterval ReportInterval ReportInterval

Gets or sets the report interval supported by the sensor.

public unsigned short ReportInterval { get; set; }public uint ReportInterval { get; set; }Public ReadWrite Property ReportInterval As uint
Value
uint uint uint

The report interval supported by the sensor.

Attributes

Remarks

The report interval is specified in milliseconds.

The report interval will be set to a default value that will vary based on the sensor driver’s implementation. If your app does not want to use this default value, you should set the report interval to a non-zero value prior to registering an event handler or calling GetCurrentReading. The sensor will then attempt to allocate resources to satisfy the application’s requirements but the sensor also has to balance the needs of other apps using the sensor.

Changes to the report interval after an event handler has been registered or GetCurrentReading has been called may apply to the delivery of subsequent sensor readings.

Conversely, when an application is finished with the sensor, it should explicitly return the sensor to its default report interval by setting it to zero. This is important for power conservation, especially when using a language that may keep the sensor object active for an indefinite period prior to garbage collection.

The application should consult the MinimumReportInterval property prior to setting the report interval to ensure that the sensor can honor the requested report interval. Setting a value below the minimum supported interval will either trigger an exception or have undefined results.

Although the application can set this value to request a particular report interval, the driver will determine the actual report interval, based on internal logic. For example, the driver might use the shortest report interval that is requested by any caller.

Setting a value of zero requests the driver to use its default report interval. As with requesting a specific interval, the driver may choose a different interval based on other client requests and internal logic.

The Sensor platform automatically sets the change sensitivity for orientation sensors based on the current report interval. This table specifies the change sensitivity values for given intervals.

Current report interval (specified in milliseconds)Change sensitivity (specified in degrees)
1 ms – 16 ms0.01 degreees
17 ms – 32 ms0.5 degrees
>= 33 ms2 degrees

Methods

GetCurrentReading() GetCurrentReading() GetCurrentReading()

Gets the current sensor reading.

public OrientationSensorReading GetCurrentReading()public OrientationSensorReading GetCurrentReading()Public Function GetCurrentReading() As OrientationSensorReading
Returns
Attributes

Remarks

An application may use this method to poll the sensor for the current reading as an alternative to registering a ReadingChanged event handler. This would be the preferred alternative for an application that updates its user interface at a specific frame rate. Whether polling once or many times, the application must establish a desired ReportInterval. This informs the sensor driver that resources should be allocated to satisfy subsequent polling requests

Before using the return value from this method, the application must first check that the value is not null. (If the value is null and you attempt to retrieve it, Windows will generate an exception.)

The following example demonstrates how a Windows Store app built with XAML and C# retrieves the current reading for the orientation sensor.

private void DisplayCurrentReading(object sender, object args)
{
    OrientationSensorReading reading = _sensor.GetCurrentReading();
    if (reading != null)
    {
        // Quaternion values
        SensorQuaternion quaternion = reading.Quaternion;   // get a reference to the object to avoid re-creating it for each access
        ScenarioOutput_X.Text = String.Format("{0,8:0.00000}", quaternion.X);
        ScenarioOutput_Y.Text = String.Format("{0,8:0.00000}", quaternion.Y);
        ScenarioOutput_Z.Text = String.Format("{0,8:0.00000}", quaternion.Z);
        ScenarioOutput_W.Text = String.Format("{0,8:0.00000}", quaternion.W);

        // Rotation Matrix values
        SensorRotationMatrix rotationMatrix = reading.RotationMatrix;
        ScenarioOutput_M11.Text = String.Format("{0,8:0.00000}", rotationMatrix.M11);
        ScenarioOutput_M12.Text = String.Format("{0,8:0.00000}", rotationMatrix.M12);
        ScenarioOutput_M13.Text = String.Format("{0,8:0.00000}", rotationMatrix.M13);
        ScenarioOutput_M21.Text = String.Format("{0,8:0.00000}", rotationMatrix.M21);
        ScenarioOutput_M22.Text = String.Format("{0,8:0.00000}", rotationMatrix.M22);
        ScenarioOutput_M23.Text = String.Format("{0,8:0.00000}", rotationMatrix.M23);
        ScenarioOutput_M31.Text = String.Format("{0,8:0.00000}", rotationMatrix.M31);
        ScenarioOutput_M32.Text = String.Format("{0,8:0.00000}", rotationMatrix.M32);
        ScenarioOutput_M33.Text = String.Format("{0,8:0.00000}", rotationMatrix.M33);
    }
}

The following example demonstrates how a Windows Store app built for Windows using JavaScript retrieves the current reading for the orientation sensor.

function getCurrentReading() {
    var reading = sensor.getCurrentReading();
    if (reading) {
        // Quaternion values
        var quaternion = reading.quaternion;    // get a reference to the object to avoid re-creating it for each access
        document.getElementById("readingOutputQuaternion").innerHTML =
               "W: " + quaternion.w.toFixed(6)
            + " X: " + quaternion.x.toFixed(6)
            + " Y: " + quaternion.y.toFixed(6)
            + " Z: " + quaternion.z.toFixed(6);

        // Rotation Matrix values
        var rotationMatrix = reading.rotationMatrix;
        document.getElementById("readingOutputRotationMatrix").innerHTML =
               "M11: " + rotationMatrix.m11.toFixed(6)
            + " M12: " + rotationMatrix.m12.toFixed(6)
            + " M13: " + rotationMatrix.m13.toFixed(6)
            + " M21: " + rotationMatrix.m21.toFixed(6)
            + " M22: " + rotationMatrix.m22.toFixed(6)
            + " M23: " + rotationMatrix.m23.toFixed(6)
            + " M31: " + rotationMatrix.m31.toFixed(6)
            + " M32: " + rotationMatrix.m32.toFixed(6)
            + " M33: " + rotationMatrix.m33.toFixed(6);
    }
}

GetDefault() GetDefault() GetDefault()

Gets the default orientation sensor.

public static OrientationSensor GetDefault()public static OrientationSensor GetDefault()Public Static Function GetDefault() As OrientationSensor
Returns

The default orientation sensor or null if no orientation sensors are found.

Attributes

Remarks

This method only returns values for hardware that has been integrated into the computer by the manufacturer. (The orientation-sensor readings are derived from multiple sensors.) A null value will be returned if the specified sensor is not available in the system.

When a system is in Connected Standby, a call to the GetDefault method will return immediately with a null result.

The following example demonstrates how a Windows Store app built with XAML and C# used this method to establish a connection to the orientation sensor.

_sensor = OrientationSensor.GetDefault();

The following example demonstrates how a Windows Store app built for Windows using JavaScript used this method to establish a connection to the orientation sensor.

sensor = Windows.Devices.Sensors.OrientationSensor.getDefault();

GetDefault(SensorReadingType) GetDefault(SensorReadingType) GetDefault(SensorReadingType)

Gets the default orientation sensor, taking into account accuracy preferences.

public static OrientationSensor GetDefault(SensorReadingType sensorReadingtype)public static OrientationSensor GetDefault(SensorReadingType sensorReadingtype)Public Static Function GetDefault(sensorReadingtype As SensorReadingType) As OrientationSensor
Parameters
sensorReadingtype
SensorReadingType SensorReadingType SensorReadingType

The type of sensor to retrieve. An Absolute SensorReadingType returns an OrientationSensor using an accelerometer, a gyromoter, and magnetometer to determine the orientation with respect to magnetic North. A Relative SensorReadingType returns an OrientationSensor using an accelerometer and gyrometer only (no magnetometer), measuring relative to where the sensor was first instantiated.”

Returns

The default orientation sensor or null if no orientation sensors are found.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

This method only returns values for hardware that has been integrated into the computer by the manufacturer. (The orientation-sensor readings are derived from multiple sensors.) A null value will be returned if the specified sensor is not available in the system.

When a system is in Connected Standby, a call to the GetDefault method will return immediately with a null result.

GetDefault(SensorReadingType, SensorOptimizationGoal) GetDefault(SensorReadingType, SensorOptimizationGoal) GetDefault(SensorReadingType, SensorOptimizationGoal)

Gets the default orientation sensor, taking into account power and accuracy preferences.

public static OrientationSensor GetDefault(SensorReadingType sensorReadingType, SensorOptimizationGoal optimizationGoal)public static OrientationSensor GetDefault(SensorReadingType sensorReadingType, SensorOptimizationGoal optimizationGoal)Public Static Function GetDefault(sensorReadingType As SensorReadingType, optimizationGoal As SensorOptimizationGoal) As OrientationSensor
Parameters
sensorReadingType
SensorReadingType SensorReadingType SensorReadingType

The type of sensor to retrieve. An Absolute SensorReadingType returns an OrientationSensor using an accelerometer, a gyromoter, and magnetometer to determine the orientation with respect to magnetic North. A Relative SensorReadingType returns an OrientationSensor using an accelerometer and gyrometer only (no magnetometer), measuring relative to where the sensor was first instantiated.”

optimizationGoal
SensorOptimizationGoal SensorOptimizationGoal SensorOptimizationGoal

Indicates the preferences of optimization for the sensor. This field is only used if an Absolute SensorReadingType is specified. An optimizationGoal of Precision will return an OrientationSensor using an accelereometer, a gyrometer, and a magnetometer to determine orientation with respect to magnetic North. This has the potential to use a lot of power due to it’s use of a gyrometer. In contrast, specifying an optimizationGoal of PowerEfficiency will return an OrientationSensor using an accelerometer and magnetometer only (no gyrometer) to save power at the a cost of some accuracy (readings will still be relatively accurate in most circumstances).

Returns

The default orientation sensor or null if no orientation sensors are found.

Attributes
Additional features and requirements
Device family
Windows 10 Anniversary Edition (introduced v10.0.14393.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v3)

Remarks

This method only returns values for hardware that has been integrated into the computer by the manufacturer. (The orientation-sensor readings are derived from multiple sensors.) A null value will be returned if the specified sensor is not available in the system.

When a system is in Connected Standby, a call to the GetDefault method will return immediately with a null result.

The optimizationGoal parameter is dependent on the hardware available. It will attempt to choose the best sensor available based on your provided preference for optimization. It only has an effect if the sensorReadingType is Absolute.

GetDefaultForRelativeReadings() GetDefaultForRelativeReadings() GetDefaultForRelativeReadings()

Gets the default orientation sensor.

public static OrientationSensor GetDefaultForRelativeReadings()public static OrientationSensor GetDefaultForRelativeReadings()Public Static Function GetDefaultForRelativeReadings() As OrientationSensor
Returns

The default orientation sensor or null if no orientation sensors are found.

Attributes

Events

ReadingChanged ReadingChanged ReadingChanged

Occurs each time the orientation sensor reports a new sensor reading.

public event TypedEventHandler ReadingChangedpublic event TypedEventHandler ReadingChangedPublic Event ReadingChanged
Attributes

Remarks

An application may register this event handler to obtain sensor readings. The application must establish a desired ReportInterval. This informs the sensor driver that resources should be allocated to satisfy the requirements of the application.

The OrientationSensor returns a quaternion and a rotation matrix.

The following example demonstrates how a Windows Store app built with C# and XAML registers its ReadingChanged event handler.

private void ScenarioEnable(object sender, RoutedEventArgs e)
{
    if (_sensor != null)
    {
        // Establish the report interval
        _sensor.ReportInterval = _desiredReportInterval;

        Window.Current.VisibilityChanged += new WindowVisibilityChangedEventHandler(VisibilityChanged);
        _sensor.ReadingChanged += new TypedEventHandler<OrientationSensor, OrientationSensorReadingChangedEventArgs>(ReadingChanged);

        ScenarioEnableButton.IsEnabled = false;
        ScenarioDisableButton.IsEnabled = true;
    }
    else
    {
        rootPage.NotifyUser("No orientation sensor found", NotifyType.StatusMessage);
    }
}

The following example shows the ReadingChanged event handler.

async private void ReadingChanged(object sender, OrientationSensorReadingChangedEventArgs e)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OrientationSensorReading reading = e.Reading;

        // Quaternion values
        SensorQuaternion quaternion = reading.Quaternion;   // get a reference to the object to avoid re-creating it for each access
        ScenarioOutput_X.Text = String.Format("{0,8:0.00000}", quaternion.X);
        ScenarioOutput_Y.Text = String.Format("{0,8:0.00000}", quaternion.Y);
        ScenarioOutput_Z.Text = String.Format("{0,8:0.00000}", quaternion.Z);
        ScenarioOutput_W.Text = String.Format("{0,8:0.00000}", quaternion.W);

        // Rotation Matrix values
        SensorRotationMatrix rotationMatrix = reading.RotationMatrix;
        ScenarioOutput_M11.Text = String.Format("{0,8:0.00000}", rotationMatrix.M11);
        ScenarioOutput_M12.Text = String.Format("{0,8:0.00000}", rotationMatrix.M12);
        ScenarioOutput_M13.Text = String.Format("{0,8:0.00000}", rotationMatrix.M13);
        ScenarioOutput_M21.Text = String.Format("{0,8:0.00000}", rotationMatrix.M21);
        ScenarioOutput_M22.Text = String.Format("{0,8:0.00000}", rotationMatrix.M22);
        ScenarioOutput_M23.Text = String.Format("{0,8:0.00000}", rotationMatrix.M23);
        ScenarioOutput_M31.Text = String.Format("{0,8:0.00000}", rotationMatrix.M31);
        ScenarioOutput_M32.Text = String.Format("{0,8:0.00000}", rotationMatrix.M32);
        ScenarioOutput_M33.Text = String.Format("{0,8:0.00000}", rotationMatrix.M33);
    });
}

The following example demonstrates how a Windows Store app built with JavaScript registers its ReadingChanged event handler.

function enableReadingChangedScenario() {
    if (sensor) {
        // Set the reportInterval to enable the sensor events
        sensor.reportInterval = reportInterval;

        document.addEventListener("msvisibilitychange", msVisibilityChangeHandler, false);
        sensor.addEventListener("readingchanged", onDataChanged);
        document.getElementById("scenario1Open").disabled = true;
        document.getElementById("scenario1Revoke").disabled = false;
    } else {
        WinJS.log && WinJS.log("No orientation sensor found", "sample", "error");
    }
}

The following example shows the ReadingChanged event handler.

function onDataChanged(e) {
    var reading = e.reading;

    // Quaternion values
    var quaternion = reading.quaternion;    // get a reference to the object to avoid re-creating it for each access
    document.getElementById("eventOutputQuaternion").innerHTML =
           "W: " + quaternion.w.toFixed(6)
        + " X: " + quaternion.x.toFixed(6)
        + " Y: " + quaternion.y.toFixed(6)
        + " Z: " + quaternion.z.toFixed(6);

    // Rotation Matrix values
    var rotationMatrix = reading.rotationMatrix;
    document.getElementById("eventOutputRotationMatrix").innerHTML =
           "M11: " + rotationMatrix.m11.toFixed(6)
        + " M12: " + rotationMatrix.m12.toFixed(6)
        + " M13: " + rotationMatrix.m13.toFixed(6)
        + " M21: " + rotationMatrix.m21.toFixed(6)
        + " M22: " + rotationMatrix.m22.toFixed(6)
        + " M23: " + rotationMatrix.m23.toFixed(6)
        + " M31: " + rotationMatrix.m31.toFixed(6)
        + " M32: " + rotationMatrix.m32.toFixed(6)
        + " M33: " + rotationMatrix.m33.toFixed(6);
}

See Also