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 can be empty if the spatializer implementation does not support head tracking or if
61      * no head tracking sensor is registered (see setHeadSensor() and setScreenSensor()).
62      */
getSupportedHeadTrackingModes()63     SpatializerHeadTrackingMode[] getSupportedHeadTrackingModes();
64 
65     /** Selects the desired head tracking mode (see SpatializerHeadTrackingMode.aidl) */
setDesiredHeadTrackingMode(SpatializerHeadTrackingMode mode)66     void setDesiredHeadTrackingMode(SpatializerHeadTrackingMode mode);
67 
68     /** Gets the actual head tracking mode. Can be different from the desired mode if conditions to
69      * enable the desired mode are not met (e.g if the head tracking device was removed)
70      */
getActualHeadTrackingMode()71     SpatializerHeadTrackingMode getActualHeadTrackingMode();
72 
73     /** Reset the head tracking algorithm to consider current head pose as neutral */
recenterHeadTracker()74     void recenterHeadTracker();
75 
76     /** Set the screen to stage transform to use by the head tracking algorithm
77      * The screen to stage transform is conveyed as a vector of 6 elements,
78      * where the first three are a translation vector and
79      * the last three are a rotation vector.
80      */
setGlobalTransform(in float[] screenToStage)81     void setGlobalTransform(in float[] screenToStage);
82 
83     /**
84      * Set the sensor that is to be used for head-tracking.
85      * -1 can be used to disable head-tracking.
86      */
setHeadSensor(int sensorHandle)87     void setHeadSensor(int sensorHandle);
88 
89     /**
90      * Set the sensor that is to be used for screen-tracking.
91      * -1 can be used to disable screen-tracking.
92      */
setScreenSensor(int sensorHandle)93     void setScreenSensor(int sensorHandle);
94 
95     /**
96      * Sets the display orientation.
97      * Orientation is expressed in the angle of rotation from the physical "up" side of the screen
98      * to the logical "up" side of the content displayed the screen. Counterclockwise angles, as
99      * viewed while facing the screen are positive.
100      */
setDisplayOrientation(float physicalToLogicalAngle)101     void setDisplayOrientation(float physicalToLogicalAngle);
102 
103     /**
104      * Sets the hinge angle for foldable devices.
105      */
setHingeAngle(float hingeAngle)106     void setHingeAngle(float hingeAngle);
107 
108     /** Reports the list of supported spatialization modess (see SpatializationMode.aidl).
109      * The list should never be empty if an ISpatializer interface was successfully
110      * retrieved with IAudioPolicyService.getSpatializer().
111      */
getSupportedModes()112     SpatializationMode[] getSupportedModes();
113 
114     /**
115      * Registers a callback to monitor head tracking functions.
116      * Only one callback can be registered on a Spatializer.
117      * The last callback registered wins and passing a nullptr unregisters
118      * last registered callback.
119      */
registerHeadTrackingCallback(@ullable ISpatializerHeadTrackingCallback callback)120     void registerHeadTrackingCallback(@nullable ISpatializerHeadTrackingCallback callback);
121 
122     /**
123      * Sets a parameter to the spatializer engine. Used by effect implementor for vendor
124      * specific configuration.
125      */
setParameter(int key, in byte[] value)126      void setParameter(int key, in byte[] value);
127 
128     /**
129      * Gets a parameter from the spatializer engine. Used by effect implementor for vendor
130      * specific configuration.
131      */
getParameter(int key, inout byte[] value)132      void getParameter(int key, inout byte[] value);
133 
134     /**
135      * Gets the io handle of the output stream the spatializer is connected to.
136      */
getOutput()137      int getOutput();
138 }
139