diff options
Diffstat (limited to 'include/media/AudioTrack.h')
| -rw-r--r-- | include/media/AudioTrack.h | 131 |
1 files changed, 82 insertions, 49 deletions
diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h index 34108b3..f1b77ab 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. }; @@ -66,14 +70,6 @@ public: class Buffer { public: - enum { - MUTE = 0x00000001 - }; - uint32_t flags; // 0 or MUTE - 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 - size_t frameCount; // number of sample frames corresponding to size; // on input it is the number of frames desired, // on output is the number of frames actually filled @@ -114,7 +110,7 @@ public: * - NO_INIT: audio server or audio hardware not initialized */ - static status_t getMinFrameCount(int* frameCount, + static status_t getMinFrameCount(size_t* frameCount, audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT, uint32_t sampleRate = 0); @@ -123,7 +119,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 +133,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 +159,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 +191,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, @@ -238,13 +223,13 @@ public: audio_stream_type_t streamType() const; audio_format_t format() const; - int channelCount() const; + uint32_t channelCount() const; uint32_t frameCount() const; /* Return channelCount * (bit depth per channel / 8). * channelCount is determined from channelMask, and bit depth comes from format. */ - size_t frameSize() const; + size_t frameSize() const { return mFrameSize; } sp<IMemory>& sharedBuffer(); @@ -280,9 +265,14 @@ public: /* Set volume for this track, mostly used for games' sound effects * left and right volumes. Levels must be >= 0.0 and <= 1.0. + * This is the older API. New applications should use setVolume(float) when possible. */ status_t setVolume(float left, float right); - void getVolume(float* left, float* right) const; + + /* Set volume for all channels. This is the preferred API for new applications, + * especially for multi-channel content. + */ + status_t setVolume(float volume); /* Set the send level for this track. An auxiliary effect should be attached * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0. @@ -290,9 +280,11 @@ 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); + status_t setSampleRate(uint32_t sampleRate); + + /* Return current sample rate in Hz, or 0 if unknown */ uint32_t getSampleRate() const; /* Enables looping and sets the start and end points of looping. @@ -312,7 +304,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 +323,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 +353,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 +408,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. @@ -422,6 +417,18 @@ public: * +n limits wait time to n * WAIT_PERIOD_MS, * -1 causes an (almost) infinite wait time, * 0 non-blocking. + * + * Buffer fields + * On entry: + * frameCount number of frames requested + * After error return: + * frameCount 0 + * size 0 + * raw undefined + * After successful return: + * frameCount actual number of frames available, <= number requested + * size actual number of bytes available + * raw pointer to the buffer */ enum { @@ -482,11 +489,11 @@ protected: // body of AudioTrackThread::threadLoop() bool processAudioBuffer(const sp<AudioTrackThread>& thread); + // caller must hold lock on mLock for all _l methods status_t createTrack_l(audio_stream_type_t streamType, uint32_t sampleRate, audio_format_t format, - audio_channel_mask_t channelMask, - int frameCount, + size_t frameCount, audio_output_flags_t flags, const sp<IMemory>& sharedBuffer, audio_io_handle_t output); @@ -502,37 +509,63 @@ protected: float mVolume[2]; float mSendLevel; - uint32_t mFrameCount; + size_t mFrameCount; // corresponds to current IAudioTrack + size_t mReqFrameCount; // frame count to request the next time a new + // IAudioTrack is needed + + audio_track_cblk_t* mCblk; // re-load after mLock.unlock() - audio_track_cblk_t* mCblk; - audio_format_t mFormat; + // Starting address of buffers in shared memory. If there is a shared buffer, mBuffers + // is the value of pointer() for the shared buffer, otherwise mBuffers points + // immediately after the control block. This address is for the mapping within client + // address space. AudioFlinger::TrackBase::mBuffer is for the server address space. + void* mBuffers; + + audio_format_t mFormat; // as requested by client, not forced to 16-bit audio_stream_type_t mStreamType; uint8_t mChannelCount; uint8_t mMuted; uint8_t mReserved; audio_channel_mask_t mChannelMask; + + // mFrameSize is equal to mFrameSizeAF for non-PCM or 16-bit PCM data. + // For 8-bit PCM data, mFrameSizeAF is + // twice as large because data is expanded to 16-bit before being stored in buffer. + size_t mFrameSize; // app-level frame size + size_t mFrameSizeAF; // AudioFlinger frame size + status_t mStatus; uint32_t mLatency; 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; int mAuxEffectId; + + // When locking both mLock and mCblk->lock, must lock in this order to avoid deadlock: + // 1. mLock + // 2. mCblk->lock + // It is OK to lock only mCblk->lock. mutable Mutex mLock; - status_t mRestoreStatus; + bool mIsTimed; int mPreviousPriority; // before start() SchedPolicy mPreviousSchedulingGroup; |