1a198a29250acb7c3e918f1566727190966bb336fEric Laurent/* 2a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Copyright (C) 2014 The Android Open Source Project 3a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 4a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Licensed under the Apache License, Version 2.0 (the "License"); 5a198a29250acb7c3e918f1566727190966bb336fEric Laurent * you may not use this file except in compliance with the License. 6a198a29250acb7c3e918f1566727190966bb336fEric Laurent * You may obtain a copy of the License at 7a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 8a198a29250acb7c3e918f1566727190966bb336fEric Laurent * http://www.apache.org/licenses/LICENSE-2.0 9a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 10a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Unless required by applicable law or agreed to in writing, software 11a198a29250acb7c3e918f1566727190966bb336fEric Laurent * distributed under the License is distributed on an "AS IS" BASIS, 12a198a29250acb7c3e918f1566727190966bb336fEric Laurent * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13a198a29250acb7c3e918f1566727190966bb336fEric Laurent * See the License for the specific language governing permissions and 14a198a29250acb7c3e918f1566727190966bb336fEric Laurent * limitations under the License. 15a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 16a198a29250acb7c3e918f1566727190966bb336fEric Laurent 17a198a29250acb7c3e918f1566727190966bb336fEric Laurentpackage android.media; 18a198a29250acb7c3e918f1566727190966bb336fEric Laurent 19a198a29250acb7c3e918f1566727190966bb336fEric Laurent/** 20a198a29250acb7c3e918f1566727190966bb336fEric Laurent * The AudioGain describes a gain controller. Gain controllers are exposed by 21a198a29250acb7c3e918f1566727190966bb336fEric Laurent * audio ports when the gain is configurable at this port's input or output. 22a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Gain values are expressed in millibels. 23a198a29250acb7c3e918f1566727190966bb336fEric Laurent * A gain controller has the following attributes: 24a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - mode: defines modes of operation or features 25a198a29250acb7c3e918f1566727190966bb336fEric Laurent * MODE_JOINT: all channel gains are controlled simultaneously 26a198a29250acb7c3e918f1566727190966bb336fEric Laurent * MODE_CHANNELS: each channel gain is controlled individually 27a198a29250acb7c3e918f1566727190966bb336fEric Laurent * MODE_RAMP: ramps can be applied when gain changes 28a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - channel mask: indicates for which channels the gain can be controlled 29a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - min value: minimum gain value in millibel 30a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - max value: maximum gain value in millibel 31a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - default value: gain value after reset in millibel 32a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - step value: granularity of gain control in millibel 33a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - min ramp duration: minimum ramp duration in milliseconds 34a198a29250acb7c3e918f1566727190966bb336fEric Laurent * - max ramp duration: maximum ramp duration in milliseconds 35a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 36a198a29250acb7c3e918f1566727190966bb336fEric Laurent * This object is always created by the framework and read only by applications. 37a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Applications get a list of AudioGainDescriptors from AudioPortDescriptor.gains() and can build a 38a198a29250acb7c3e918f1566727190966bb336fEric Laurent * valid gain configuration from AudioGain.buildConfig() 39a198a29250acb7c3e918f1566727190966bb336fEric Laurent * @hide 40a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 41a198a29250acb7c3e918f1566727190966bb336fEric Laurentpublic class AudioGain { 42a198a29250acb7c3e918f1566727190966bb336fEric Laurent 43a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 44a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Bit of AudioGain.mode() field indicating that 45a198a29250acb7c3e918f1566727190966bb336fEric Laurent * all channel gains are controlled simultaneously 46a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 47a198a29250acb7c3e918f1566727190966bb336fEric Laurent public static final int MODE_JOINT = 1; 48a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 49a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Bit of AudioGain.mode() field indicating that 50a198a29250acb7c3e918f1566727190966bb336fEric Laurent * each channel gain is controlled individually 51a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 52a198a29250acb7c3e918f1566727190966bb336fEric Laurent public static final int MODE_CHANNELS = 2; 53a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 54a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Bit of AudioGain.mode() field indicating that 55a198a29250acb7c3e918f1566727190966bb336fEric Laurent * ramps can be applied when gain changes. The type of ramp (linear, log etc...) is 56a198a29250acb7c3e918f1566727190966bb336fEric Laurent * implementation specific. 57a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 58a198a29250acb7c3e918f1566727190966bb336fEric Laurent public static final int MODE_RAMP = 4; 59a198a29250acb7c3e918f1566727190966bb336fEric Laurent 60a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mIndex; 61a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mMode; 62a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mChannelMask; 63a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mMinValue; 64a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mMaxValue; 65a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mDefaultValue; 66a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mStepValue; 67a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mRampDurationMinMs; 68a198a29250acb7c3e918f1566727190966bb336fEric Laurent private final int mRampDurationMaxMs; 69a198a29250acb7c3e918f1566727190966bb336fEric Laurent 70a198a29250acb7c3e918f1566727190966bb336fEric Laurent // The channel mask passed to the constructor is as specified in AudioFormat 71a198a29250acb7c3e918f1566727190966bb336fEric Laurent // (e.g. AudioFormat.CHANNEL_OUT_STEREO) 72a198a29250acb7c3e918f1566727190966bb336fEric Laurent AudioGain(int index, int mode, int channelMask, 73a198a29250acb7c3e918f1566727190966bb336fEric Laurent int minValue, int maxValue, int defaultValue, int stepValue, 74a198a29250acb7c3e918f1566727190966bb336fEric Laurent int rampDurationMinMs, int rampDurationMaxMs) { 75a198a29250acb7c3e918f1566727190966bb336fEric Laurent mIndex = index; 76a198a29250acb7c3e918f1566727190966bb336fEric Laurent mMode = mode; 77a198a29250acb7c3e918f1566727190966bb336fEric Laurent mChannelMask = channelMask; 78a198a29250acb7c3e918f1566727190966bb336fEric Laurent mMinValue = minValue; 79a198a29250acb7c3e918f1566727190966bb336fEric Laurent mMaxValue = maxValue; 80a198a29250acb7c3e918f1566727190966bb336fEric Laurent mDefaultValue = defaultValue; 81a198a29250acb7c3e918f1566727190966bb336fEric Laurent mStepValue = stepValue; 82a198a29250acb7c3e918f1566727190966bb336fEric Laurent mRampDurationMinMs = rampDurationMinMs; 83a198a29250acb7c3e918f1566727190966bb336fEric Laurent mRampDurationMaxMs = rampDurationMaxMs; 84a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 85a198a29250acb7c3e918f1566727190966bb336fEric Laurent 86a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 87a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Bit field indicating supported modes of operation 88a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 89a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int mode() { 90a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mMode; 91a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 92a198a29250acb7c3e918f1566727190966bb336fEric Laurent 93a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 94a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Indicates for which channels the gain can be controlled 95a198a29250acb7c3e918f1566727190966bb336fEric Laurent * (e.g. AudioFormat.CHANNEL_OUT_STEREO) 96a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 97a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int channelMask() { 98a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mChannelMask; 99a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 100a198a29250acb7c3e918f1566727190966bb336fEric Laurent 101a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 102a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Minimum gain value in millibel 103a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 104a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int minValue() { 105a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mMinValue; 106a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 107a198a29250acb7c3e918f1566727190966bb336fEric Laurent 108a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 109a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Maximum gain value in millibel 110a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 111a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int maxValue() { 112a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mMaxValue; 113a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 114a198a29250acb7c3e918f1566727190966bb336fEric Laurent 115a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 116a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Default gain value in millibel 117a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 118a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int defaultValue() { 119a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mDefaultValue; 120a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 121a198a29250acb7c3e918f1566727190966bb336fEric Laurent 122a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 123a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Granularity of gain control in millibel 124a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 125a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int stepValue() { 126a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mStepValue; 127a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 128a198a29250acb7c3e918f1566727190966bb336fEric Laurent 129a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 130a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Minimum ramp duration in milliseconds 131a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 0 if MODE_RAMP not set 132a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 133a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int rampDurationMinMs() { 134a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mRampDurationMinMs; 135a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 136a198a29250acb7c3e918f1566727190966bb336fEric Laurent 137a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 138a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Maximum ramp duration in milliseconds 139a198a29250acb7c3e918f1566727190966bb336fEric Laurent * 0 if MODE_RAMP not set 140a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 141a198a29250acb7c3e918f1566727190966bb336fEric Laurent public int rampDurationMaxMs() { 142a198a29250acb7c3e918f1566727190966bb336fEric Laurent return mRampDurationMaxMs; 143a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 144a198a29250acb7c3e918f1566727190966bb336fEric Laurent 145a198a29250acb7c3e918f1566727190966bb336fEric Laurent /** 146a198a29250acb7c3e918f1566727190966bb336fEric Laurent * Build a valid gain configuration for this gain controller for use by 147a198a29250acb7c3e918f1566727190966bb336fEric Laurent * AudioPortDescriptor.setGain() 148a198a29250acb7c3e918f1566727190966bb336fEric Laurent * @param mode: desired mode of operation 149a198a29250acb7c3e918f1566727190966bb336fEric Laurent * @param channelMask: channels of which the gain should be modified. 150a198a29250acb7c3e918f1566727190966bb336fEric Laurent * @param values: gain values for each channels. 151a198a29250acb7c3e918f1566727190966bb336fEric Laurent * @param rampDurationMs: ramp duration if mode MODE_RAMP is set. 152a198a29250acb7c3e918f1566727190966bb336fEric Laurent * ignored if MODE_JOINT. 153a198a29250acb7c3e918f1566727190966bb336fEric Laurent */ 154a198a29250acb7c3e918f1566727190966bb336fEric Laurent public AudioGainConfig buildConfig(int mode, int channelMask, 155a198a29250acb7c3e918f1566727190966bb336fEric Laurent int[] values, int rampDurationMs) { 156a198a29250acb7c3e918f1566727190966bb336fEric Laurent //TODO: check params here 157a198a29250acb7c3e918f1566727190966bb336fEric Laurent return new AudioGainConfig(mIndex, this, mode, channelMask, values, rampDurationMs); 158a198a29250acb7c3e918f1566727190966bb336fEric Laurent } 159a198a29250acb7c3e918f1566727190966bb336fEric Laurent} 160