1 /*
2  * Copyright (C) 2014 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.compat.annotation.UnsupportedAppUsage;
20 
21 /**
22  * The AudioGain describes a gain controller. Gain controllers are exposed by
23  * audio ports when the gain is configurable at this port's input or output.
24  * Gain values are expressed in millibels.
25  * A gain controller has the following attributes:
26  * - mode: defines modes of operation or features
27  *    MODE_JOINT: all channel gains are controlled simultaneously
28  *    MODE_CHANNELS: each channel gain is controlled individually
29  *    MODE_RAMP: ramps can be applied when gain changes
30  * - channel mask: indicates for which channels the gain can be controlled
31  * - min value: minimum gain value in millibel
32  * - max value: maximum gain value in millibel
33  * - default value: gain value after reset in millibel
34  * - step value: granularity of gain control in millibel
35  * - min ramp duration: minimum ramp duration in milliseconds
36  * - max ramp duration: maximum ramp duration in milliseconds
37  *
38  * This object is always created by the framework and read only by applications.
39  * Applications get a list of AudioGainDescriptors from AudioPortDescriptor.gains() and can build a
40  * valid gain configuration from AudioGain.buildConfig()
41  * @hide
42  */
43 public class AudioGain {
44 
45     /**
46      * Bit of AudioGain.mode() field indicating that
47      * all channel gains are controlled simultaneously
48      */
49     public static final int MODE_JOINT = 1;
50     /**
51      * Bit of AudioGain.mode() field indicating that
52      * each channel gain is controlled individually
53      */
54     public static final int MODE_CHANNELS = 2;
55     /**
56      * Bit of AudioGain.mode() field indicating that
57      * ramps can be applied when gain changes. The type of ramp (linear, log etc...) is
58      * implementation specific.
59      */
60     public static final int MODE_RAMP = 4;
61 
62     private final int mIndex;
63     private final int mMode;
64     private final int mChannelMask;
65     private final int mMinValue;
66     private final int mMaxValue;
67     private final int mDefaultValue;
68     private final int mStepValue;
69     private final int mRampDurationMinMs;
70     private final int mRampDurationMaxMs;
71 
72     // The channel mask passed to the constructor is as specified in AudioFormat
73     // (e.g. AudioFormat.CHANNEL_OUT_STEREO)
74     @UnsupportedAppUsage
AudioGain(int index, int mode, int channelMask, int minValue, int maxValue, int defaultValue, int stepValue, int rampDurationMinMs, int rampDurationMaxMs)75     AudioGain(int index, int mode, int channelMask,
76                         int minValue, int maxValue, int defaultValue, int stepValue,
77                         int rampDurationMinMs, int rampDurationMaxMs) {
78         mIndex = index;
79         mMode = mode;
80         mChannelMask = channelMask;
81         mMinValue = minValue;
82         mMaxValue = maxValue;
83         mDefaultValue = defaultValue;
84         mStepValue = stepValue;
85         mRampDurationMinMs = rampDurationMinMs;
86         mRampDurationMaxMs = rampDurationMaxMs;
87     }
88 
89     /**
90      * Bit field indicating supported modes of operation
91      */
mode()92     public int mode() {
93         return mMode;
94     }
95 
96     /**
97      * Indicates for which channels the gain can be controlled
98      * (e.g. AudioFormat.CHANNEL_OUT_STEREO)
99      */
channelMask()100     public int channelMask() {
101         return mChannelMask;
102     }
103 
104     /**
105      * Minimum gain value in millibel
106      */
minValue()107     public int minValue() {
108         return mMinValue;
109     }
110 
111     /**
112      * Maximum gain value in millibel
113      */
maxValue()114     public int maxValue() {
115         return mMaxValue;
116     }
117 
118     /**
119      * Default gain value in millibel
120      */
defaultValue()121     public int defaultValue() {
122         return mDefaultValue;
123     }
124 
125     /**
126      * Granularity of gain control in millibel
127      */
stepValue()128     public int stepValue() {
129         return mStepValue;
130     }
131 
132     /**
133      * Minimum ramp duration in milliseconds
134      * 0 if MODE_RAMP not set
135      */
rampDurationMinMs()136     public int rampDurationMinMs() {
137         return mRampDurationMinMs;
138     }
139 
140     /**
141      * Maximum ramp duration in milliseconds
142      * 0 if MODE_RAMP not set
143      */
rampDurationMaxMs()144     public int rampDurationMaxMs() {
145         return mRampDurationMaxMs;
146     }
147 
148     /**
149      * Build a valid gain configuration for this gain controller for use by
150      * AudioPortDescriptor.setGain()
151      * @param mode: desired mode of operation
152      * @param channelMask: channels of which the gain should be modified.
153      * @param values: gain values for each channels.
154      * @param rampDurationMs: ramp duration if mode MODE_RAMP is set.
155      * ignored if MODE_JOINT.
156      */
buildConfig(int mode, int channelMask, int[] values, int rampDurationMs)157     public AudioGainConfig buildConfig(int mode, int channelMask,
158                                        int[] values, int rampDurationMs) {
159         //TODO: check params here
160         return new AudioGainConfig(mIndex, this, mode, channelMask, values, rampDurationMs);
161     }
162 }
163