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 /**
     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  */
     39 public 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     protected 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         String role = Integer.toString(mRole);
    180         switch (mRole) {
    181             case ROLE_NONE:
    182                 role = "NONE";
    183                 break;
    184             case ROLE_SOURCE:
    185                 role = "SOURCE";
    186                 break;
    187             case ROLE_SINK:
    188                 role = "SINK";
    189                 break;
    190         }
    191         return "{mHandle: " + mHandle
    192                 + ", mRole: " + role
    193                 + "}";
    194     }
    195 }
    196