AudioPort.java revision 2754fd0cd3f055b1d5f7f2ea1470b4d84011b379 
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
17package android.media;
18
19
20/**
21 * An audio port is a node of the audio framework or hardware that can be connected to or
22 * disconnect from another audio node to create a specific audio routing configuration.
23 * Examples of audio ports are an output device (speaker) or an output mix (see AudioMixPort).
24 * All attributes that are relevant for applications to make routing selection are decribed
25 * in an AudioPort,  in particular:
26 * - possible channel mask configurations.
27 * - audio format (PCM 16bit, PCM 24bit...)
28 * - gain: a port can be associated with one or more gain controllers (see AudioGain).
29 *
30 * This object is always created by the framework and read only by applications.
31 * A list of all audio port descriptors currently available for applications to control
32 * is obtained by AudioManager.listAudioPorts().
33 * An application can obtain an AudioPortConfig for a valid configuration of this port
34 * by calling AudioPort.buildConfig() and use this configuration
35 * to create a connection between audio sinks and sources with AudioManager.connectAudioPatch()
36 *
37 * @hide
38 */
39public class AudioPort {
40
41    /**
42     * For use by the audio framework.
43     */
44    public static final int ROLE_NONE = 0;
45    /**
46     * The audio port is a source (produces audio)
47     */
48    public static final int ROLE_SOURCE = 1;
49    /**
50     * The audio port is a sink (consumes audio)
51     */
52    public static final int ROLE_SINK = 2;
53
54    /**
55     * audio port type for use by audio framework implementation
56     */
57    public static final int TYPE_NONE = 0;
58    /**
59     */
60    public static final int TYPE_DEVICE = 1;
61    /**
62     */
63    public static final int TYPE_SUBMIX = 2;
64    /**
65     */
66    public static final int TYPE_SESSION = 3;
67
68
69    AudioHandle mHandle;
70    private final int mRole;
71    private final int[] mSamplingRates;
72    private final int[] mChannelMasks;
73    private final int[] mFormats;
74    private final AudioGain[] mGains;
75    private AudioPortConfig mActiveConfig;
76
77    AudioPort(AudioHandle handle, int role, int[] samplingRates, int[] channelMasks,
78            int[] formats, AudioGain[] gains) {
79        mHandle = handle;
80        mRole = role;
81        mSamplingRates = samplingRates;
82        mChannelMasks = channelMasks;
83        mFormats = formats;
84        mGains = gains;
85    }
86
87    AudioHandle handle() {
88        return mHandle;
89    }
90
91    /**
92     * Get the audio port role
93     */
94    public int role() {
95        return mRole;
96    }
97
98    /**
99     * Get the list of supported sampling rates
100     * Empty array if sampling rate is not relevant for this audio port
101     */
102    public int[] samplingRates() {
103        return mSamplingRates;
104    }
105
106    /**
107     * Get the list of supported channel mask configurations
108     * (e.g AudioFormat.CHANNEL_OUT_STEREO)
109     * Empty array if channel mask is not relevant for this audio port
110     */
111    public int[] channelMasks() {
112        return mChannelMasks;
113    }
114
115    /**
116     * Get the list of supported audio format configurations
117     * (e.g AudioFormat.ENCODING_PCM_16BIT)
118     * Empty array if format is not relevant for this audio port
119     */
120    public int[] formats() {
121        return mFormats;
122    }
123
124    /**
125     * Get the list of gain descriptors
126     * Empty array if this port does not have gain control
127     */
128    public AudioGain[] gains() {
129        return mGains;
130    }
131
132    /**
133     * Get the gain descriptor at a given index
134     */
135    AudioGain gain(int index) {
136        if (index < 0 || index >= mGains.length) {
137            return null;
138        }
139        return mGains[index];
140    }
141
142    /**
143     * Build a specific configuration of this audio port for use by methods
144     * like AudioManager.connectAudioPatch().
145     * @param channelMask The desired channel mask. AudioFormat.CHANNEL_OUT_DEFAULT if no change
146     * from active configuration requested.
147     * @param format The desired audio format. AudioFormat.ENCODING_DEFAULT if no change
148     * from active configuration requested.
149     * @param gain The desired gain. null if no gain changed requested.
150     */
151    public AudioPortConfig buildConfig(int samplingRate, int channelMask, int format,
152                                        AudioGainConfig gain) {
153        return new AudioPortConfig(this, samplingRate, channelMask, format, gain);
154    }
155
156    /**
157     * Get currently active configuration of this audio port.
158     */
159    public AudioPortConfig activeConfig() {
160        return mActiveConfig;
161    }
162
163    @Override
164    public boolean equals(Object o) {
165        if (o == null || !(o instanceof AudioPort)) {
166            return false;
167        }
168        AudioPort ap = (AudioPort)o;
169        return mHandle.equals(ap.handle());
170    }
171
172    @Override
173    public int hashCode() {
174        return mHandle.hashCode();
175    }
176
177    @Override
178    public String toString() {
179        return "{mHandle:" + mHandle
180                + ", mRole:" + mRole
181                + "}";
182    }
183}
184