Home | History | Annotate | Download | only in media
      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 /**
     20  * An audio port is a node of the audio framework or hardware that can be connected to or
     21  * disconnect from another audio node to create a specific audio routing configuration.
     22  * Examples of audio ports are an output device (speaker) or an output mix (see AudioMixPort).
     23  * All attributes that are relevant for applications to make routing selection are decribed
     24  * in an AudioPort,  in particular:
     25  * - possible channel mask configurations.
     26  * - audio format (PCM 16bit, PCM 24bit...)
     27  * - gain: a port can be associated with one or more gain controllers (see AudioGain).
     28  *
     29  * This object is always created by the framework and read only by applications.
     30  * A list of all audio port descriptors currently available for applications to control
     31  * is obtained by AudioManager.listAudioPorts().
     32  * An application can obtain an AudioPortConfig for a valid configuration of this port
     33  * by calling AudioPort.buildConfig() and use this configuration
     34  * to create a connection between audio sinks and sources with AudioManager.connectAudioPatch()
     35  *
     36  * @hide
     37  */
     38 public class AudioPort {
     39     private static final String TAG = "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     protected final int mRole;
     71     private final String mName;
     72     private final int[] mSamplingRates;
     73     private final int[] mChannelMasks;
     74     private final int[] mChannelIndexMasks;
     75     private final int[] mFormats;
     76     private final AudioGain[] mGains;
     77     private AudioPortConfig mActiveConfig;
     78 
     79     AudioPort(AudioHandle handle, int role, String name,
     80             int[] samplingRates, int[] channelMasks, int[] channelIndexMasks,
     81             int[] formats, AudioGain[] gains) {
     82 
     83         mHandle = handle;
     84         mRole = role;
     85         mName = name;
     86         mSamplingRates = samplingRates;
     87         mChannelMasks = channelMasks;
     88         mChannelIndexMasks = channelIndexMasks;
     89         mFormats = formats;
     90         mGains = gains;
     91     }
     92 
     93     AudioHandle handle() {
     94         return mHandle;
     95     }
     96 
     97     /**
     98      * Get the system unique device ID.
     99      */
    100     public int id() {
    101         return mHandle.id();
    102     }
    103 
    104 
    105     /**
    106      * Get the audio port role
    107      */
    108     public int role() {
    109         return mRole;
    110     }
    111 
    112     /**
    113      * Get the human-readable name of this port. Perhaps an internal
    114      * designation or an physical device.
    115      */
    116     public String name() {
    117         return mName;
    118     }
    119 
    120     /**
    121      * Get the list of supported sampling rates
    122      * Empty array if sampling rate is not relevant for this audio port
    123      */
    124     public int[] samplingRates() {
    125         return mSamplingRates;
    126     }
    127 
    128     /**
    129      * Get the list of supported channel mask configurations
    130      * (e.g AudioFormat.CHANNEL_OUT_STEREO)
    131      * Empty array if channel mask is not relevant for this audio port
    132      */
    133     public int[] channelMasks() {
    134         return mChannelMasks;
    135     }
    136 
    137     /**
    138      * Get the list of supported channel index mask configurations
    139      * (e.g 0x0003 means 2 channel, 0x000F means 4 channel....)
    140      * Empty array if channel index mask is not relevant for this audio port
    141      */
    142     public int[] channelIndexMasks() {
    143         return mChannelIndexMasks;
    144     }
    145 
    146     /**
    147      * Get the list of supported audio format configurations
    148      * (e.g AudioFormat.ENCODING_PCM_16BIT)
    149      * Empty array if format is not relevant for this audio port
    150      */
    151     public int[] formats() {
    152         return mFormats;
    153     }
    154 
    155     /**
    156      * Get the list of gain descriptors
    157      * Empty array if this port does not have gain control
    158      */
    159     public AudioGain[] gains() {
    160         return mGains;
    161     }
    162 
    163     /**
    164      * Get the gain descriptor at a given index
    165      */
    166     AudioGain gain(int index) {
    167         if (index < 0 || index >= mGains.length) {
    168             return null;
    169         }
    170         return mGains[index];
    171     }
    172 
    173     /**
    174      * Build a specific configuration of this audio port for use by methods
    175      * like AudioManager.connectAudioPatch().
    176      * @param channelMask The desired channel mask. AudioFormat.CHANNEL_OUT_DEFAULT if no change
    177      * from active configuration requested.
    178      * @param format The desired audio format. AudioFormat.ENCODING_DEFAULT if no change
    179      * from active configuration requested.
    180      * @param gain The desired gain. null if no gain changed requested.
    181      */
    182     public AudioPortConfig buildConfig(int samplingRate, int channelMask, int format,
    183                                         AudioGainConfig gain) {
    184         return new AudioPortConfig(this, samplingRate, channelMask, format, gain);
    185     }
    186 
    187     /**
    188      * Get currently active configuration of this audio port.
    189      */
    190     public AudioPortConfig activeConfig() {
    191         return mActiveConfig;
    192     }
    193 
    194     @Override
    195     public boolean equals(Object o) {
    196         if (o == null || !(o instanceof AudioPort)) {
    197             return false;
    198         }
    199         AudioPort ap = (AudioPort)o;
    200         return mHandle.equals(ap.handle());
    201     }
    202 
    203     @Override
    204     public int hashCode() {
    205         return mHandle.hashCode();
    206     }
    207 
    208     @Override
    209     public String toString() {
    210         String role = Integer.toString(mRole);
    211         switch (mRole) {
    212             case ROLE_NONE:
    213                 role = "NONE";
    214                 break;
    215             case ROLE_SOURCE:
    216                 role = "SOURCE";
    217                 break;
    218             case ROLE_SINK:
    219                 role = "SINK";
    220                 break;
    221         }
    222         return "{mHandle: " + mHandle
    223                 + ", mRole: " + role
    224                 + "}";
    225     }
    226 }
    227