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 <limits> 19 20 #include "HeadTrackingMode.h" 21 #include "Pose.h" 22 #include "PosePredictorType.h" 23 #include "Twist.h" 24 25 namespace android { 26 namespace media { 27 28 /** 29 * Main entry-point for this library. 30 * This interfaces encompasses all the processing required for determining the head-to-stage pose 31 * used for audio virtualization. 32 * The usage involves periodic setting of the inputs, calling calculate() and obtaining the outputs. 33 * This class is not thread-safe, but thread-compatible. 34 */ 35 class HeadTrackingProcessor { 36 public: 37 virtual ~HeadTrackingProcessor() = default; 38 39 struct Options { 40 float maxTranslationalVelocity = std::numeric_limits<float>::infinity(); 41 float maxRotationalVelocity = std::numeric_limits<float>::infinity(); 42 int64_t freshnessTimeout = std::numeric_limits<int64_t>::max(); 43 float predictionDuration = 0; 44 int64_t autoRecenterWindowDuration = std::numeric_limits<int64_t>::max(); 45 float autoRecenterTranslationalThreshold = std::numeric_limits<float>::infinity(); 46 float autoRecenterRotationalThreshold = std::numeric_limits<float>::infinity(); 47 int64_t screenStillnessWindowDuration = 0; 48 float screenStillnessTranslationalThreshold = std::numeric_limits<float>::infinity(); 49 float screenStillnessRotationalThreshold = std::numeric_limits<float>::infinity(); 50 }; 51 52 /** Sets the desired head-tracking mode. */ 53 virtual void setDesiredMode(HeadTrackingMode mode) = 0; 54 55 /** 56 * Sets the world-to-head pose and head twist (velocity). 57 * headTwist is given in the head coordinate frame. 58 */ 59 virtual void setWorldToHeadPose(int64_t timestamp, const Pose3f& worldToHead, 60 const Twist3f& headTwist) = 0; 61 62 /** 63 * Sets the world-to-screen pose. 64 */ 65 virtual void setWorldToScreenPose(int64_t timestamp, const Pose3f& worldToScreen) = 0; 66 67 /** 68 * Set the screen-to-stage pose, used in all modes. 69 */ 70 virtual void setScreenToStagePose(const Pose3f& screenToStage) = 0; 71 72 /** 73 * Sets the display orientation. 74 * Orientation is expressed in the angle of rotation from the physical "up" side of the screen 75 * to the logical "up" side of the content displayed the screen. Counterclockwise angles, as 76 * viewed while facing the screen are positive. 77 */ 78 virtual void setDisplayOrientation(float physicalToLogicalAngle) = 0; 79 80 /** 81 * Process all the previous inputs and update the outputs. 82 */ 83 virtual void calculate(int64_t timestamp) = 0; 84 85 /** 86 * Get the aggregate head-to-stage pose (primary output of this module). 87 */ 88 virtual Pose3f getHeadToStagePose() const = 0; 89 90 /** 91 * Get the actual head-tracking mode (which may deviate from the desired one as mentioned in the 92 * class documentation above). 93 */ 94 virtual HeadTrackingMode getActualMode() const = 0; 95 96 /** 97 * This causes the current poses for both the head and/or screen to be considered "center". 98 */ 99 virtual void recenter( 100 bool recenterHead = true, bool recenterScreen = true, std::string source = "") = 0; 101 102 /** 103 * Set the predictor type. 104 */ 105 virtual void setPosePredictorType(PosePredictorType type) = 0; 106 107 /** 108 * Dump HeadTrackingProcessor parameters under caller lock. 109 */ 110 virtual std::string toString_l(unsigned level) const = 0; 111 }; 112 /** 113 * Creates an instance featuring a default implementation of the HeadTrackingProcessor interface. 114 */ 115 std::unique_ptr<HeadTrackingProcessor> createHeadTrackingProcessor( 116 const HeadTrackingProcessor::Options& options, 117 HeadTrackingMode initialMode = HeadTrackingMode::STATIC); 118 119 } // namespace media 120 } // namespace android 121