Chapter 47 Sensors and Microsoft.Devices

SensorBase<TSensorReading> supplies CurrentValue, IsDataValid, TimeBetweenUpdates (default 2 ms), CurrentValueChanged, and abstract Start/Stop. Do not touch GraphicsDevice or other main-thread-only objects in a sensor handler; transfer the reading through a synchronized queue.

Desktop Accelerometer and Gyroscope install an SDL event watch rather than a polling thread. SDL_EVENT_SENSOR_UPDATE is handled on the thread that pushes it. Acceleration is converted from SI units to $g$ by division by 9.80665; angular velocity is already in radians per second. Readings receive UTC wall-clock timestamps.

Android Compass and Motion use ASensorManager, event queues, and ALooper on worker threads, without JNI. A Motion instance can own six workers for rotation, game rotation, gravity, linear acceleration, gyroscope, and magnetic field. The native route expects Android API 24 or later.

Disposal is claimed atomically so only one racing caller performs cleanup. A losing caller waits for terminal state, and an RAII guard publishes that state even if cleanup throws. Accelerometer and Gyroscope track callbacks in flight so a handler can dispose its own sensor without waiting for itself.

Current value and validity are published under one lock by SetCurrentValueAndMarkDataValid. Separate locks previously allowed a reader to observe IsDataValid=true with the prior value. Update throttling compares elapsed time at the configured interval’s coarser resolution; the earlier reverse conversion overflowed signed 64-bit ticks for TimeSpan.MaxValue.

Compass and Motion use a two-phase start/stop protocol: reserve under the owner mutex, invoke the backend without that lock, then commit or roll back. A condition variable prevents a new start while an orphaned start’s cleanup call is still in flight. Stop deliberately remains able to supersede a start without waiting on it.

Exceptions cannot cross SDL, Android C callbacks, or raw thread entry points. CNA records backend, operation, native error, device, timestamp, and severity through a noexcept diagnostic channel. The Android bridge distinguishes std::exception::what() from an unknown throw. Other device paths still retain older ad hoc counters, so the shared diagnostic record is not yet universal.

Compass uses upright heading when gravity meets the $\cos {45}^{\circ }$ threshold; otherwise it derives flat heading from the quaternion. Results are normalized to $[0,360)$, and an invalid quaternion maps to $0^{\circ }$. Accuracy values High/Medium/Low/Unreliable map to 5/15/20/180 degrees. Without declination data, TrueHeading equals MagneticHeading.

Motion normalizes Android’s rotation quaternion and derives pitch, yaw, and roll. A process-wide CNAEXT landscape remap affects acceleration, rotation rate, gravity, and linear acceleration, but not Attitude: the requested axis reflection has determinant $-1$ and cannot be represented by a quaternion. Fusion accepts the latest readings within 500 ms; it does not interpolate them to one timestamp.

VibrateController is a process-lifetime singleton. Start(TimeSpan) accepts the WP7 range $[0,5\text{s}]$; Start(TimeSpan,float) and StartLeftRight are CNAEXT intensity controls. SDL’s Android haptic route blends motor intensities; independent left/right controller rumble is available through GamePad, not this phone-style API.

DevicesShutdownCoordinator::Shutdown() must precede the application’s SDL_Quit(). It prevents the singleton’s later static destructor from closing an SDL device after SDL has already released native state. One global mutex serializes sensor and haptic subsystem initialization and preserves the documented per-instance-before-global lock order.

All four concrete sensors expose Dispose(bool) publicly even though the base declares it protected. External Dispose(false) marks the instance disposed without stopping it, decrementing use counts, or releasing SDL ownership. This is an open API/lifetime defect; call the parameterless public Dispose().

Focused tests cover math, throttling, lifecycle, fake backends, reentrancy, and TSan stress. They do not constitute hardware QA. The Android source notes that its sign and zero conventions have not been checked on a physical device, and the Android demo is an older copy of the desktop demo. Android behavior is source-proven and host-tested where fakes permit, not device-verified.