1 /*
2  * Copyright (C) 2023 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 package com.android.server.uwb.correction.pose;
17 
18 import androidx.annotation.NonNull;
19 
20 import com.android.server.uwb.correction.math.Pose;
21 
22 import java.util.EnumSet;
23 
24 /**
25  * Provides pose update information and a way for subscribers to listen for them.
26  */
27 public interface IPoseSource extends AutoCloseable {
28     /** The shortest practical update interval for a pose source. */
29     int MIN_INTERVAL_MS = 1000 / 60; // 60Hz
30 
31     /** The longest practical update interval for a pose source. */
32     int MAX_INTERVAL_MS = 10000; // 0.1Hz.
33 
34     /**
35      * A set of all possible pose source capabilities.
36      */
37     enum Capabilities {
38         YAW, PITCH, ROLL, X, Y, Z,
39         /**
40          * Indicates that a pitch and roll of 0 means that the phone is upright. If this flag
41          * is not present, pitch and roll changes are only relative.
42          */
43         UPRIGHT;
44 
45         public static final EnumSet<Capabilities> ALL = EnumSet.allOf(Capabilities.class);
46         public static final EnumSet<Capabilities> NONE = EnumSet.noneOf(Capabilities.class);
47         public static final EnumSet<Capabilities> ROTATION = EnumSet.of(
48                 Capabilities.YAW,
49                 Capabilities.PITCH,
50                 Capabilities.ROLL
51         );
52         public static final EnumSet<Capabilities> UPRIGHT_ROTATION = EnumSet.of(
53                 Capabilities.YAW,
54                 Capabilities.PITCH,
55                 Capabilities.ROLL,
56                 Capabilities.UPRIGHT);
57         public static final EnumSet<Capabilities> TRANSLATION = EnumSet.of(
58                 Capabilities.X,
59                 Capabilities.Y,
60                 Capabilities.Z);
61     }
62 
63     /**
64      * Stops the pose sensing and removes all listeners.
65      */
66     @Override
close()67     void close();
68 
69     /**
70      * Registers a listener for the pose updates.
71      * @param listener The PoseEventListener that will be notified when the pose changes.
72      */
registerListener(@onNull PoseEventListener listener)73     void registerListener(@NonNull PoseEventListener listener);
74 
75     /**
76      * Unregisters a listener from the pose updates.
77      * @param listener The PoseEventListener that will no longer be notified when the pose changes.
78      * @return True if successfully removed. Note that a listener may be prematurely removed if it
79      *         has thrown an error.
80      */
unregisterListener(@onNull PoseEventListener listener)81     boolean unregisterListener(@NonNull PoseEventListener listener);
82 
83     /**
84      * Gets the current pose.
85      * @return The current pose. May be null.
86      */
getPose()87     Pose getPose();
88 
89     /**
90      * Gets the capabilities of this pose source.
91      * @return An EnumSet of Capabilities.
92      */
93     @NonNull
getCapabilities()94     EnumSet<Capabilities> getCapabilities();
95 }
96