1 /* 2 * Copyright 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 17 package android.media; 18 19 import android.media.ISpatializerHeadTrackingCallback; 20 import android.media.SpatializationLevel; 21 import android.media.SpatializationMode; 22 import android.media.SpatializerHeadTrackingMode; 23 24 25 /** 26 * The ISpatializer interface is used to control the native audio service implementation 27 * of the spatializer stage with headtracking when present on a platform. 28 * It is intended for exclusive use by the java AudioService running in system_server. 29 * It provides APIs to discover the feature availability and options as well as control and report 30 * the active state and modes of the spatializer and head tracking effect. 31 * {@hide} 32 */ 33 interface ISpatializer { 34 /** Releases a ISpatializer interface previously acquired. */ release()35 void release(); 36 37 /** Reports the list of supported spatialization levels (see SpatializationLevel.aidl). 38 * The list should never be empty if an ISpatializer interface was successfully 39 * retrieved with IAudioPolicyService.getSpatializer(). 40 */ getSupportedLevels()41 SpatializationLevel[] getSupportedLevels(); 42 43 /** Selects the desired spatialization level (see SpatializationLevel.aidl). Selecting a level 44 * different from SpatializationLevel.NONE with create the specialized multichannel output 45 * mixer, create and enable the spatializer effect and let the audio policy attach eligible 46 * AudioTrack to this output stream. 47 */ setLevel(SpatializationLevel level)48 void setLevel(SpatializationLevel level); 49 50 /** Gets the selected spatialization level (see SpatializationLevel.aidl) */ getLevel()51 SpatializationLevel getLevel(); 52 53 /** Reports if the spatializer engine supports head tracking or not. 54 * This is a pre condition independent of the fact that a head tracking sensor is 55 * registered or not. 56 */ isHeadTrackingSupported()57 boolean isHeadTrackingSupported(); 58 59 /** Reports the list of supported head tracking modes (see SpatializerHeadTrackingMode.aidl). 60 * The list always contains SpatializerHeadTrackingMode.DISABLED and can include other modes 61 * if the spatializer effect implementation supports head tracking. 62 * The result does not depend on currently connected sensors but reflects the capabilities 63 * when sensors are available. 64 */ getSupportedHeadTrackingModes()65 SpatializerHeadTrackingMode[] getSupportedHeadTrackingModes(); 66 67 /** Selects the desired head tracking mode (see SpatializerHeadTrackingMode.aidl) */ setDesiredHeadTrackingMode(SpatializerHeadTrackingMode mode)68 void setDesiredHeadTrackingMode(SpatializerHeadTrackingMode mode); 69 70 /** Gets the actual head tracking mode. Can be different from the desired mode if conditions to 71 * enable the desired mode are not met (e.g if the head tracking device was removed) 72 */ getActualHeadTrackingMode()73 SpatializerHeadTrackingMode getActualHeadTrackingMode(); 74 75 /** Reset the head tracking algorithm to consider current head pose as neutral */ recenterHeadTracker()76 void recenterHeadTracker(); 77 78 /** Set the screen to stage transform to use by the head tracking algorithm 79 * The screen to stage transform is conveyed as a vector of 6 elements, 80 * where the first three are a translation vector and 81 * the last three are a rotation vector. 82 */ setGlobalTransform(in float[] screenToStage)83 void setGlobalTransform(in float[] screenToStage); 84 85 /** 86 * Set the sensor that is to be used for head-tracking. 87 * -1 can be used to disable head-tracking. 88 */ setHeadSensor(int sensorHandle)89 void setHeadSensor(int sensorHandle); 90 91 /** 92 * Set the sensor that is to be used for screen-tracking. 93 * -1 can be used to disable screen-tracking. 94 */ setScreenSensor(int sensorHandle)95 void setScreenSensor(int sensorHandle); 96 97 /** 98 * Sets the display orientation. 99 * 100 * This is the rotation of the displayed content relative to its natural orientation. 101 * 102 * Orientation is expressed in the angle of rotation from the physical "up" side of the screen 103 * to the logical "up" side of the content displayed the screen. Counterclockwise angles, as 104 * viewed while facing the screen are positive. 105 * 106 * Note: DisplayManager currently only returns this in increments of 90 degrees, 107 * so the values will be 0, PI/2, PI, 3PI/2. 108 */ setDisplayOrientation(float physicalToLogicalAngle)109 void setDisplayOrientation(float physicalToLogicalAngle); 110 111 /** 112 * Sets the hinge angle for foldable devices. 113 * 114 * Per the hinge angle sensor, this returns a value from 0 to 2PI. 115 * The value of 0 is considered closed, and PI is considered flat open. 116 */ setHingeAngle(float hingeAngle)117 void setHingeAngle(float hingeAngle); 118 119 /** 120 * Sets whether a foldable is considered "folded" or not. 121 * 122 * The fold state may affect which physical screen is active for display. 123 */ setFoldState(boolean folded)124 void setFoldState(boolean folded); 125 126 /** Reports the list of supported spatialization modess (see SpatializationMode.aidl). 127 * The list should never be empty if an ISpatializer interface was successfully 128 * retrieved with IAudioPolicyService.getSpatializer(). 129 */ getSupportedModes()130 SpatializationMode[] getSupportedModes(); 131 132 /** 133 * Registers a callback to monitor head tracking functions. 134 * Only one callback can be registered on a Spatializer. 135 * The last callback registered wins and passing a nullptr unregisters 136 * last registered callback. 137 */ registerHeadTrackingCallback(@ullable ISpatializerHeadTrackingCallback callback)138 void registerHeadTrackingCallback(@nullable ISpatializerHeadTrackingCallback callback); 139 140 /** 141 * Sets a parameter to the spatializer engine. Used by effect implementor for vendor 142 * specific configuration. 143 */ setParameter(int key, in byte[] value)144 void setParameter(int key, in byte[] value); 145 146 /** 147 * Gets a parameter from the spatializer engine. Used by effect implementor for vendor 148 * specific configuration. 149 */ getParameter(int key, inout byte[] value)150 void getParameter(int key, inout byte[] value); 151 152 /** 153 * Gets the io handle of the output stream the spatializer is connected to. 154 */ getOutput()155 int getOutput(); 156 } 157