1 /*
2  * Copyright (C) 2021 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 #pragma once
17 
18 #include <chrono>
19 #include <memory>
20 #include <optional>
21 
22 #include <android/sensor.h>
23 
24 #include "Pose.h"
25 #include "Twist.h"
26 
27 namespace android {
28 namespace media {
29 
30 /**
31  * A utility providing streaming of pose data from motion sensors provided by the Sensor Framework.
32  *
33  * A live instance of this interface keeps around some resources required for accessing sensor
34  * readings (e.g. a thread and a queue). Those would be released when the instance is deleted.
35  *
36  * Once alive, individual sensors can be subscribed to using startSensor() and updates can be
37  * stopped via stopSensor(). Those two methods should not be called concurrently and correct usage
38  * is assumed.
39  */
40 class SensorPoseProvider {
41   public:
42     static constexpr int32_t INVALID_HANDLE = ASENSOR_INVALID;
43 
44     /**
45      * Interface for consuming pose-related sensor events.
46      *
47      * The listener will be provided with a stream of events, each including:
48      * - A handle of the sensor responsible for the event.
49      * - Timestamp.
50      * - Pose.
51      * - Optional twist (time-derivative of pose).
52      *
53      * Sensors having only orientation data will have the translation part of the pose set to
54      * identity.
55      *
56      * Events are delivered in a serialized manner (i.e. callbacks do not need to be reentrant).
57      * Callbacks should not block.
58      */
59     class Listener {
60       public:
61         virtual ~Listener() = default;
62 
63         virtual void onPose(int64_t timestamp, int32_t handle, const Pose3f& pose,
64                             const std::optional<Twist3f>& twist, bool isNewReference) = 0;
65     };
66 
67     /**
68      * Creates a new SensorPoseProvider instance.
69      * Events will be delivered to the listener as long as the returned instance is kept alive.
70      * @param packageName Client's package name.
71      * @param listener The listener that will get the events.
72      * @return The new instance, or nullptr in case of failure.
73      */
74     static std::unique_ptr<SensorPoseProvider> create(const char* packageName, Listener* listener);
75 
76     virtual ~SensorPoseProvider() = default;
77 
78     /**
79      * Start receiving pose updates from a given sensor.
80      * Attempting to start a sensor that has already been started results in undefined behavior.
81      * @param sensor The sensor to subscribe to.
82      * @param samplingPeriod Sampling interval, in microseconds. Actual rate might be slightly
83      * different.
84      * @return true iff succeeded.
85      */
86     virtual bool startSensor(int32_t sensor, std::chrono::microseconds samplingPeriod) = 0;
87 
88     /**
89      * Stop a sensor, previously started with startSensor(). It is not required to stop all sensors
90      * before deleting the SensorPoseProvider instance.
91      * @param handle The sensor handle, as provided to startSensor().
92      */
93     virtual void stopSensor(int32_t handle) = 0;
94 };
95 
96 }  // namespace media
97 }  // namespace android
98