diff options
Diffstat (limited to 'include/media')
| -rw-r--r-- | include/media/AudioRecord.h | 75 | ||||
| -rw-r--r-- | include/media/AudioSystem.h | 26 | ||||
| -rw-r--r-- | include/media/AudioTrack.h | 63 | ||||
| -rw-r--r-- | include/media/EffectsFactoryApi.h | 18 | ||||
| -rw-r--r-- | include/media/IAudioFlinger.h | 3 | ||||
| -rw-r--r-- | include/media/IAudioPolicyService.h | 5 | ||||
| -rw-r--r-- | include/media/SoundPool.h | 6 | ||||
| -rw-r--r-- | include/media/nbaio/NBAIO.h | 14 |
8 files changed, 118 insertions, 92 deletions
diff --git a/include/media/AudioRecord.h b/include/media/AudioRecord.h index 156c592..f9f6e8d 100644 --- a/include/media/AudioRecord.h +++ b/include/media/AudioRecord.h @@ -43,15 +43,15 @@ public: */ enum event_type { EVENT_MORE_DATA = 0, // Request to read more data from PCM buffer. - EVENT_OVERRUN = 1, // PCM buffer overrun occured. + EVENT_OVERRUN = 1, // PCM buffer overrun occurred. EVENT_MARKER = 2, // Record head is at the specified marker position // (See setMarkerPosition()). EVENT_NEW_POS = 3, // Record head is at a new position // (See setPositionUpdatePeriod()). }; - /* Create Buffer on the stack and pass it to obtainBuffer() - * and releaseBuffer(). + /* Client should declare Buffer on the stack and pass address to obtainBuffer() + * and releaseBuffer(). See also callback_t for EVENT_MORE_DATA. */ class Buffer @@ -63,26 +63,30 @@ public: uint32_t flags; int channelCount; audio_format_t format; - size_t frameCount; + + size_t frameCount; // number of sample frames corresponding to size; + // on input it is the number of frames available, + // on output is the number of frames actually drained + size_t size; // total size in bytes == frameCount * frameSize union { void* raw; - short* i16; - int8_t* i8; + short* i16; // signed 16-bit + int8_t* i8; // unsigned 8-bit, offset by 0x80 }; }; /* As a convenience, if a callback is supplied, a handler thread * is automatically created with the appropriate priority. This thread - * invokes the callback when a new buffer becomes ready or an overrun condition occurs. + * invokes the callback when a new buffer becomes ready or various conditions occur. * Parameters: * * event: type of event notified (see enum AudioRecord::event_type). * user: Pointer to context for use by the callback receiver. * info: Pointer to optional parameter according to event type: * - EVENT_MORE_DATA: pointer to AudioRecord::Buffer struct. The callback must not read - * more bytes than indicated by 'size' field and update 'size' if less bytes are - * read. + * more bytes than indicated by 'size' field and update 'size' if fewer bytes are + * consumed. * - EVENT_OVERRUN: unused. * - EVENT_MARKER: pointer to const uint32_t containing the marker position in frames. * - EVENT_NEW_POS: pointer to const uint32_t containing the new position in frames. @@ -108,7 +112,7 @@ public: */ AudioRecord(); - /* Creates an AudioRecord track and registers it with AudioFlinger. + /* Creates an AudioRecord object and registers it with AudioFlinger. * Once created, the track needs to be started before it can be used. * Unspecified values are set to the audio hardware's current * values. @@ -120,10 +124,13 @@ public: * format: Audio format (e.g AUDIO_FORMAT_PCM_16_BIT for signed * 16 bits per sample). * channelMask: Channel mask. - * frameCount: Total size of track PCM buffer in frames. This defines the - * latency of the track. + * frameCount: Minimum size of track PCM buffer in frames. This defines the + * application's contribution to the + * latency of the track. The actual size selected by the AudioRecord could + * be larger if the requested size is not compatible with current audio HAL + * latency. Zero means to use a default value. * cbf: Callback function. If not null, this function is called periodically - * to provide new PCM data. + * to consume new PCM data. * user: Context for use by the callback receiver. * notificationFrames: The callback function is called each time notificationFrames PCM * frames are ready in record track output buffer. @@ -154,7 +161,7 @@ public: * - BAD_VALUE: invalid parameter (channels, format, sampleRate...) * - NO_INIT: audio server or audio hardware not initialized * - PERMISSION_DENIED: recording is not allowed for the requesting process - * */ + */ status_t set(audio_source_t inputSource = AUDIO_SOURCE_DEFAULT, uint32_t sampleRate = 0, audio_format_t format = AUDIO_FORMAT_DEFAULT, @@ -168,14 +175,14 @@ public: /* Result of constructing the AudioRecord. This must be checked - * before using any AudioRecord API (except for set()), using + * before using any AudioRecord API (except for set()), because using * an uninitialized AudioRecord produces undefined results. * See set() method above for possible return codes. */ status_t initCheck() const; - /* Returns this track's latency in milliseconds. - * This includes the latency due to AudioRecord buffer size + /* Returns this track's estimated latency in milliseconds. + * This includes the latency due to AudioRecord buffer size, * and audio hardware driver. */ uint32_t latency() const; @@ -191,7 +198,7 @@ public: /* After it's created the track is not active. Call start() to * make it active. If set, the callback will start being called. - * if event is not AudioSystem::SYNC_EVENT_NONE, the capture start will be delayed until + * If event is not AudioSystem::SYNC_EVENT_NONE, the capture start will be delayed until * the specified event occurs on the specified trigger session. */ status_t start(AudioSystem::sync_event_t event = AudioSystem::SYNC_EVENT_NONE, @@ -199,12 +206,12 @@ public: /* Stop a track. If set, the callback will cease being called and * obtainBuffer returns STOPPED. Note that obtainBuffer() still works - * and will fill up buffers until the pool is exhausted. + * and will drain buffers until the pool is exhausted. */ void stop(); bool stopped() const; - /* get sample rate for this record track + /* Get sample rate for this record track in Hz. */ uint32_t getSampleRate() const; @@ -258,7 +265,7 @@ public: */ status_t getPosition(uint32_t *position) const; - /* returns a handle on the audio input used by this AudioRecord. + /* Returns a handle on the audio input used by this AudioRecord. * * Parameters: * none. @@ -268,7 +275,7 @@ public: */ audio_io_handle_t getInput() const; - /* returns the audio session ID associated with this AudioRecord. + /* Returns the audio session ID associated with this AudioRecord. * * Parameters: * none. @@ -278,22 +285,30 @@ public: */ int getSessionId() const; - /* obtains a buffer of "frameCount" frames. The buffer must be - * filled entirely. If the track is stopped, obtainBuffer() returns + /* Obtains a buffer of "frameCount" frames. The buffer must be + * drained entirely, and then released with releaseBuffer(). + * If the track is stopped, obtainBuffer() returns * STOPPED instead of NO_ERROR as long as there are buffers available, * at which point NO_MORE_BUFFERS is returned. - * Buffers will be returned until the pool (buffercount()) + * Buffers will be returned until the pool * is exhausted, at which point obtainBuffer() will either block * or return WOULD_BLOCK depending on the value of the "blocking" * parameter. + * + * Interpretation of waitCount: + * +n limits wait time to n * WAIT_PERIOD_MS, + * -1 causes an (almost) infinite wait time, + * 0 non-blocking. */ enum { - NO_MORE_BUFFERS = 0x80000001, + NO_MORE_BUFFERS = 0x80000001, // same name in AudioFlinger.h, ok to be different value STOPPED = 1 }; status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount); + + /* Release an emptied buffer of "frameCount" frames for AudioFlinger to re-fill. */ void releaseBuffer(Buffer* audioBuffer); @@ -302,16 +317,16 @@ public: */ ssize_t read(void* buffer, size_t size); - /* Return the amount of input frames lost in the audio driver since the last call of this + /* Return the number of input frames lost in the audio driver since the last call of this * function. Audio driver is expected to reset the value to 0 and restart counting upon * returning the current value by this function call. Such loss typically occurs when the * user space process is blocked longer than the capacity of audio driver buffers. - * Unit: the number of input audio frames + * Units: the number of input audio frames. */ unsigned int getInputFramesLost() const; private: - /* copying audio tracks is not allowed */ + /* copying audio record objects is not allowed */ AudioRecord(const AudioRecord& other); AudioRecord& operator = (const AudioRecord& other); @@ -355,7 +370,7 @@ private: bool mActive; // protected by mLock // for client callback handler - callback_t mCbf; + callback_t mCbf; // callback handler for events, or NULL void* mUserData; // for notification APIs diff --git a/include/media/AudioSystem.h b/include/media/AudioSystem.h index 49e1afc..2218fad 100644 --- a/include/media/AudioSystem.h +++ b/include/media/AudioSystem.h @@ -87,9 +87,12 @@ public: static float linearToLog(int volume); static int logToLinear(float volume); - static status_t getOutputSamplingRate(int* samplingRate, audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); - static status_t getOutputFrameCount(int* frameCount, audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); - static status_t getOutputLatency(uint32_t* latency, audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); + static status_t getOutputSamplingRate(int* samplingRate, + audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); + static status_t getOutputFrameCount(int* frameCount, + audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); + static status_t getOutputLatency(uint32_t* latency, + audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); static status_t getSamplingRate(audio_io_handle_t output, audio_stream_type_t streamType, int* samplingRate); @@ -126,7 +129,8 @@ public: // - BAD_VALUE: invalid parameter // NOTE: this feature is not supported on all hardware platforms and it is // necessary to check returned status before using the returned values. - static status_t getRenderPosition(uint32_t *halFrames, uint32_t *dspFrames, audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); + static status_t getRenderPosition(uint32_t *halFrames, uint32_t *dspFrames, + audio_stream_type_t stream = AUDIO_STREAM_DEFAULT); // return the number of input frames lost by HAL implementation, or 0 if the handle is invalid static unsigned int getInputFramesLost(audio_io_handle_t ioHandle); @@ -147,8 +151,8 @@ public: NUM_CONFIG_EVENTS }; - // audio output descriptor used to cache output configurations in client process to avoid frequent calls - // through IAudioFlinger + // audio output descriptor used to cache output configurations in client process to avoid + // frequent calls through IAudioFlinger class OutputDescriptor { public: OutputDescriptor() @@ -162,8 +166,8 @@ public: }; // Events used to synchronize actions between audio sessions. - // For instance SYNC_EVENT_PRESENTATION_COMPLETE can be used to delay recording start until playback - // is complete on another audio session. + // For instance SYNC_EVENT_PRESENTATION_COMPLETE can be used to delay recording start until + // playback is complete on another audio session. // See definitions in MediaSyncEvent.java enum sync_event_t { SYNC_EVENT_SAME = -1, // used internally to indicate restart with same event @@ -183,8 +187,10 @@ public: // // IAudioPolicyService interface (see AudioPolicyInterface for method descriptions) // - static status_t setDeviceConnectionState(audio_devices_t device, audio_policy_dev_state_t state, const char *device_address); - static audio_policy_dev_state_t getDeviceConnectionState(audio_devices_t device, const char *device_address); + static status_t setDeviceConnectionState(audio_devices_t device, audio_policy_dev_state_t state, + const char *device_address); + static audio_policy_dev_state_t getDeviceConnectionState(audio_devices_t device, + const char *device_address); static status_t setPhoneState(audio_mode_t state); static status_t setForceUse(audio_policy_force_use_t usage, audio_policy_forced_cfg_t config); static audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage); diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h index 34108b3..76af2f8 100644 --- a/include/media/AudioTrack.h +++ b/include/media/AudioTrack.h @@ -49,13 +49,17 @@ public: }; /* Events used by AudioTrack callback function (audio_track_cblk_t). + * Keep in sync with frameworks/base/media/java/android/media/AudioTrack.java NATIVE_EVENT_*. */ enum event_type { EVENT_MORE_DATA = 0, // Request to write more data to PCM buffer. - EVENT_UNDERRUN = 1, // PCM buffer underrun occured. - EVENT_LOOP_END = 2, // Sample loop end was reached; playback restarted from loop start if loop count was not 0. - EVENT_MARKER = 3, // Playback head is at the specified marker position (See setMarkerPosition()). - EVENT_NEW_POS = 4, // Playback head is at a new position (See setPositionUpdatePeriod()). + EVENT_UNDERRUN = 1, // PCM buffer underrun occurred. + EVENT_LOOP_END = 2, // Sample loop end was reached; playback restarted from + // loop start if loop count was not 0. + EVENT_MARKER = 3, // Playback head is at the specified marker position + // (See setMarkerPosition()). + EVENT_NEW_POS = 4, // Playback head is at a new position + // (See setPositionUpdatePeriod()). EVENT_BUFFER_END = 5 // Playback head is at the end of the buffer. }; @@ -70,7 +74,7 @@ public: MUTE = 0x00000001 }; uint32_t flags; // 0 or MUTE - audio_format_t format; // but AUDIO_FORMAT_PCM_8_BIT -> AUDIO_FORMAT_PCM_16_BIT + audio_format_t format; // but AUDIO_FORMAT_PCM_8_BIT -> AUDIO_FORMAT_PCM_16_BIT // accessed directly by WebKit ANP callback int channelCount; // will be removed in the future, do not use @@ -123,7 +127,7 @@ public: */ AudioTrack(); - /* Creates an audio track and registers it with AudioFlinger. + /* Creates an AudioTrack object and registers it with AudioFlinger. * Once created, the track needs to be started before it can be used. * Unspecified values are set to the audio hardware's current * values. @@ -137,12 +141,13 @@ public: * 16 bits per sample). * channelMask: Channel mask. * frameCount: Minimum size of track PCM buffer in frames. This defines the + * application's contribution to the * latency of the track. The actual size selected by the AudioTrack could be * larger if the requested size is not compatible with current audio HAL * latency. Zero means to use a default value. * flags: See comments on audio_output_flags_t in <system/audio.h>. * cbf: Callback function. If not null, this function is called periodically - * to request new PCM data. + * to provide new PCM data. * user: Context for use by the callback receiver. * notificationFrames: The callback function is called each time notificationFrames PCM * frames have been consumed from track input buffer. @@ -162,18 +167,6 @@ public: int notificationFrames = 0, int sessionId = 0); - // DEPRECATED - explicit AudioTrack( int streamType, - uint32_t sampleRate = 0, - int format = AUDIO_FORMAT_DEFAULT, - int channelMask = 0, - int frameCount = 0, - uint32_t flags = (uint32_t) AUDIO_OUTPUT_FLAG_NONE, - callback_t cbf = 0, - void* user = 0, - int notificationFrames = 0, - int sessionId = 0); - /* Creates an audio track and registers it with AudioFlinger. With this constructor, * the PCM data to be rendered by AudioTrack is passed in a shared memory buffer * identified by the argument sharedBuffer. This prototype is for static buffer playback. @@ -206,7 +199,7 @@ public: * - INVALID_OPERATION: AudioTrack is already initialized * - BAD_VALUE: invalid parameter (channelMask, format, sampleRate...) * - NO_INIT: audio server or audio hardware not initialized - * */ + */ status_t set(audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT, uint32_t sampleRate = 0, audio_format_t format = AUDIO_FORMAT_DEFAULT, @@ -290,7 +283,7 @@ public: status_t setAuxEffectSendLevel(float level); void getAuxEffectSendLevel(float* level) const; - /* Set sample rate for this track, mostly used for games' sound effects + /* Set sample rate for this track in Hz, mostly used for games' sound effects */ status_t setSampleRate(int sampleRate); uint32_t getSampleRate() const; @@ -312,7 +305,8 @@ public: /* Sets marker position. When playback reaches the number of frames specified, a callback with * event type EVENT_MARKER is called. Calling setMarkerPosition with marker == 0 cancels marker * notification callback. - * If the AudioTrack has been opened with no callback function associated, the operation will fail. + * If the AudioTrack has been opened with no callback function associated, the operation will + * fail. * * Parameters: * @@ -330,7 +324,8 @@ public: * a callback with event type EVENT_NEW_POS is called. * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification * callback. - * If the AudioTrack has been opened with no callback function associated, the operation will fail. + * If the AudioTrack has been opened with no callback function associated, the operation will + * fail. * * Parameters: * @@ -359,7 +354,8 @@ public: * Returned status (from utils/Errors.h) can be: * - NO_ERROR: successful operation * - INVALID_OPERATION: the AudioTrack is not stopped. - * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack buffer + * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack + * buffer */ status_t setPosition(uint32_t position); status_t getPosition(uint32_t *position); @@ -413,7 +409,7 @@ public: * If the track is stopped, obtainBuffer() returns * STOPPED instead of NO_ERROR as long as there are buffers available, * at which point NO_MORE_BUFFERS is returned. - * Buffers will be returned until the pool (buffercount()) + * Buffers will be returned until the pool * is exhausted, at which point obtainBuffer() will either block * or return WOULD_BLOCK depending on the value of the "blocking" * parameter. @@ -517,16 +513,21 @@ protected: bool mActive; // protected by mLock callback_t mCbf; // callback handler for events, or NULL - void* mUserData; - uint32_t mNotificationFramesReq; // requested number of frames between each notification callback - uint32_t mNotificationFramesAct; // actual number of frames between each notification callback + void* mUserData; // for client callback handler + + // for notification APIs + uint32_t mNotificationFramesReq; // requested number of frames between each + // notification callback + uint32_t mNotificationFramesAct; // actual number of frames between each + // notification callback sp<IMemory> mSharedBuffer; int mLoopCount; uint32_t mRemainingFrames; - uint32_t mMarkerPosition; + uint32_t mMarkerPosition; // in frames bool mMarkerReached; - uint32_t mNewPosition; - uint32_t mUpdatePeriod; + uint32_t mNewPosition; // in frames + uint32_t mUpdatePeriod; // in frames + bool mFlushed; // FIXME will be made obsolete by making flush() synchronous audio_output_flags_t mFlags; int mSessionId; diff --git a/include/media/EffectsFactoryApi.h b/include/media/EffectsFactoryApi.h index 65c26f4..b1ed7b0 100644 --- a/include/media/EffectsFactoryApi.h +++ b/include/media/EffectsFactoryApi.h @@ -74,7 +74,8 @@ int EffectQueryNumberEffects(uint32_t *pNumEffects); // -ENOENT no more effect available // -ENODEV factory failed to initialize // -EINVAL invalid pDescriptor -// -ENOSYS effect list has changed since last execution of EffectQueryNumberEffects() +// -ENOSYS effect list has changed since last execution of +// EffectQueryNumberEffects() // *pDescriptor: updated with the effect descriptor. // //////////////////////////////////////////////////////////////////////////////// @@ -91,12 +92,12 @@ int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor); // // Input: // pEffectUuid: pointer to the effect uuid. -// sessionId: audio session to which this effect instance will be attached. All effects created -// with the same session ID are connected in series and process the same signal stream. -// Knowing that two effects are part of the same effect chain can help the library implement -// some kind of optimizations. -// ioId: identifies the output or input stream this effect is directed to at audio HAL. For future -// use especially with tunneled HW accelerated effects +// sessionId: audio session to which this effect instance will be attached. All effects +// created with the same session ID are connected in series and process the same signal +// stream. Knowing that two effects are part of the same effect chain can help the +// library implement some kind of optimizations. +// ioId: identifies the output or input stream this effect is directed to at audio HAL. +// For future use especially with tunneled HW accelerated effects // // Input/Output: // pHandle: address where to return the effect handle. @@ -109,7 +110,8 @@ int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor); // *pHandle: updated with the effect handle. // //////////////////////////////////////////////////////////////////////////////// -int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, effect_handle_t *pHandle); +int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t ioId, + effect_handle_t *pHandle); //////////////////////////////////////////////////////////////////////////////// // diff --git a/include/media/IAudioFlinger.h b/include/media/IAudioFlinger.h index 5170a87..359780e 100644 --- a/include/media/IAudioFlinger.h +++ b/include/media/IAudioFlinger.h @@ -123,7 +123,8 @@ public: virtual status_t setParameters(audio_io_handle_t ioHandle, const String8& keyValuePairs) = 0; - virtual String8 getParameters(audio_io_handle_t ioHandle, const String8& keys) const = 0; + virtual String8 getParameters(audio_io_handle_t ioHandle, const String8& keys) + const = 0; // register a current process for audio output change notifications virtual void registerClient(const sp<IAudioFlingerClient>& client) = 0; diff --git a/include/media/IAudioPolicyService.h b/include/media/IAudioPolicyService.h index cc2e069..f5b0604 100644 --- a/include/media/IAudioPolicyService.h +++ b/include/media/IAudioPolicyService.h @@ -44,9 +44,10 @@ public: audio_policy_dev_state_t state, const char *device_address) = 0; virtual audio_policy_dev_state_t getDeviceConnectionState(audio_devices_t device, - const char *device_address) = 0; + const char *device_address) = 0; virtual status_t setPhoneState(audio_mode_t state) = 0; - virtual status_t setForceUse(audio_policy_force_use_t usage, audio_policy_forced_cfg_t config) = 0; + virtual status_t setForceUse(audio_policy_force_use_t usage, + audio_policy_forced_cfg_t config) = 0; virtual audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage) = 0; virtual audio_io_handle_t getOutput(audio_stream_type_t stream, uint32_t samplingRate = 0, diff --git a/include/media/SoundPool.h b/include/media/SoundPool.h index 002b045..7bf3069 100644 --- a/include/media/SoundPool.h +++ b/include/media/SoundPool.h @@ -65,8 +65,10 @@ public: sp<IMemory> getIMemory() { return mData; } // hack - void init(int numChannels, int sampleRate, audio_format_t format, size_t size, sp<IMemory> data ) { - mNumChannels = numChannels; mSampleRate = sampleRate; mFormat = format; mSize = size; mData = data; } + void init(int numChannels, int sampleRate, audio_format_t format, size_t size, + sp<IMemory> data ) { + mNumChannels = numChannels; mSampleRate = sampleRate; mFormat = format; mSize = size; + mData = data; } private: void init(); diff --git a/include/media/nbaio/NBAIO.h b/include/media/nbaio/NBAIO.h index 81f42ed..f5d6eb5 100644 --- a/include/media/nbaio/NBAIO.h +++ b/include/media/nbaio/NBAIO.h @@ -45,17 +45,15 @@ enum { // Negotiation of format is based on the data provider and data sink, or the data consumer and // data source, exchanging prioritized arrays of offers and counter-offers until a single offer is // mutually agreed upon. Each offer is an NBAIO_Format. For simplicity and performance, -// NBAIO_Format is an enum that ties together the most important combinations of the various +// NBAIO_Format is a typedef that ties together the most important combinations of the various // attributes, rather than a struct with separate fields for format, sample rate, channel count, // interleave, packing, alignment, etc. The reason is that NBAIO_Format tries to abstract out only -// the combinations that are actually needed within AudioFligner. If the list of combinations grows +// the combinations that are actually needed within AudioFlinger. If the list of combinations grows // too large, then this decision should be re-visited. -enum NBAIO_Format { - Format_Invalid, - Format_SR44_1_C2_I16, // 44.1 kHz PCM stereo interleaved 16-bit signed - Format_SR48_C2_I16, // 48 kHz PCM stereo interleaved 16-bit signed - Format_SR44_1_C1_I16, // 44.1 kHz PCM mono interleaved 16-bit signed - Format_SR48_C1_I16, // 48 kHz PCM mono interleaved 16-bit signed +// Sample rate and channel count are explicit, PCM interleaved 16-bit is assumed. +typedef unsigned NBAIO_Format; +enum { + Format_Invalid }; // Return the frame size of an NBAIO_Format in bytes |