diff options
author | Glenn Kasten <gkasten@google.com> | 2012-01-19 08:59:58 -0800 |
---|---|---|
committer | Glenn Kasten <gkasten@google.com> | 2012-02-14 09:17:59 -0800 |
commit | 99e53b86eebb605b70dd7591b89bf61a9414ed0e (patch) | |
tree | 8939550ada02fe21121550a83952ebf7638c0dac /include | |
parent | 6dbc1359f778575d09d6da722b060a6d72c2e7c5 (diff) | |
download | frameworks_av-99e53b86eebb605b70dd7591b89bf61a9414ed0e.zip frameworks_av-99e53b86eebb605b70dd7591b89bf61a9414ed0e.tar.gz frameworks_av-99e53b86eebb605b70dd7591b89bf61a9414ed0e.tar.bz2 |
Update comments
We no longer put the filename at start of file.
Change-Id: Ic435b159a23105681e3d4a6cb1ac097bc853302e
Diffstat (limited to 'include')
-rw-r--r-- | include/media/AudioSystem.h | 2 | ||||
-rw-r--r-- | include/media/AudioTrack.h | 46 | ||||
-rw-r--r-- | include/media/EffectsFactoryApi.h | 8 | ||||
-rw-r--r-- | include/media/IAudioTrack.h | 8 | ||||
-rw-r--r-- | include/media/MemoryLeakTrackUtil.h | 2 | ||||
-rw-r--r-- | include/private/media/AudioTrackShared.h | 29 |
6 files changed, 65 insertions, 30 deletions
diff --git a/include/media/AudioSystem.h b/include/media/AudioSystem.h index da99620..1916ac5 100644 --- a/include/media/AudioSystem.h +++ b/include/media/AudioSystem.h @@ -131,7 +131,7 @@ public: NUM_CONFIG_EVENTS }; - // audio output descritor used to cache output configurations in client process to avoid frequent calls + // audio output descriptor used to cache output configurations in client process to avoid frequent calls // through IAudioFlinger class OutputDescriptor { public: diff --git a/include/media/AudioTrack.h b/include/media/AudioTrack.h index 11db81b..0f2c323 100644 --- a/include/media/AudioTrack.h +++ b/include/media/AudioTrack.h @@ -58,8 +58,8 @@ public: EVENT_BUFFER_END = 5 // Playback head is at the end of the buffer. }; - /* 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 @@ -68,12 +68,16 @@ public: enum { MUTE = 0x00000001 }; - uint32_t flags; + 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; - size_t size; + + 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 + + size_t size; // input/output in byte units union { void* raw; short* i16; // signed 16-bit @@ -84,15 +88,15 @@ public: /* 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 available or an underrun condition occurs. + * invokes the callback when a new buffer becomes available or various conditions occur. * Parameters: * * event: type of event notified (see enum AudioTrack::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 AudioTrack::Buffer struct. The callback must not write - * more bytes than indicated by 'size' field and update 'size' if less bytes are - * written. + * more bytes than indicated by 'size' field and update 'size' if fewer bytes are + * written. * - EVENT_UNDERRUN: unused. * - EVENT_LOOP_END: pointer to an int indicating the number of loops remaining. * - EVENT_MARKER: pointer to an uint32_t containing the marker position in frames. @@ -225,7 +229,7 @@ public: */ uint32_t latency() const; - /* getters, see constructor */ + /* getters, see constructors and set() */ audio_stream_type_t streamType() const; audio_format_t format() const; @@ -401,13 +405,19 @@ public: status_t attachAuxEffect(int effectId); /* Obtains a buffer of "frameCount" frames. The buffer must be - * filled entirely. If the track is stopped, obtainBuffer() returns + * filled 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()) * 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 { @@ -416,12 +426,19 @@ public: }; status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount); + + /* Release a filled buffer of "frameCount" frames for AudioFlinger to process. */ void releaseBuffer(Buffer* audioBuffer); /* As a convenience we provide a write() interface to the audio buffer. - * This is implemented on top of lockBuffer/unlockBuffer. For best - * performance use callbacks. Return actual number of bytes written. - * + * This is implemented on top of obtainBuffer/releaseBuffer. For best + * performance use callbacks. Returns actual number of bytes written >= 0, + * or one of the following negative status codes: + * INVALID_OPERATION AudioTrack is configured for shared buffer mode + * BAD_VALUE size is invalid + * STOPPED AudioTrack was stopped during the write + * NO_MORE_BUFFERS when obtainBuffer() returns same + * or any other error code returned by IAudioTrack::start() or restoreTrack_l(). */ ssize_t write(const void* buffer, size_t size); @@ -448,6 +465,7 @@ private: AudioTrack& mReceiver; }; + // body of AudioTrackThread::threadLoop() bool processAudioBuffer(const sp<AudioTrackThread>& thread); status_t createTrack_l(audio_stream_type_t streamType, uint32_t sampleRate, @@ -484,7 +502,7 @@ private: bool mActive; // protected by mLock - callback_t mCbf; + 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 diff --git a/include/media/EffectsFactoryApi.h b/include/media/EffectsFactoryApi.h index df83995..65c26f4 100644 --- a/include/media/EffectsFactoryApi.h +++ b/include/media/EffectsFactoryApi.h @@ -87,7 +87,7 @@ int EffectQueryEffect(uint32_t index, effect_descriptor_t *pDescriptor); // Description: Creates an effect engine of the specified type and returns an // effect control interface on this engine. The function will allocate the // resources for an instance of the requested effect engine and return -// a handler on the effect control interface. +// a handle on the effect control interface. // // Input: // pEffectUuid: pointer to the effect uuid. @@ -115,17 +115,17 @@ int EffectCreate(const effect_uuid_t *pEffectUuid, int32_t sessionId, int32_t io // // Function: EffectRelease // -// Description: Releases the effect engine whose handler is given as argument. +// Description: Releases the effect engine whose handle is given as argument. // All resources allocated to this particular instance of the effect are // released. // // Input: -// handle: handler on the effect interface to be released. +// handle: handle on the effect interface to be released. // // Output: // returned value: 0 successful operation. // -ENODEV factory failed to initialize -// -EINVAL invalid interface handler +// -EINVAL invalid interface handle // //////////////////////////////////////////////////////////////////////////////// int EffectRelease(effect_handle_t handle); diff --git a/include/media/IAudioTrack.h b/include/media/IAudioTrack.h index b346722..e4772a1 100644 --- a/include/media/IAudioTrack.h +++ b/include/media/IAudioTrack.h @@ -46,12 +46,12 @@ public: /* Stop a track. If set, the callback will cease being called and * obtainBuffer will return an error. Buffers that are already released - * will be processed, unless flush() is called. + * will continue to be processed, unless/until flush() is called. */ virtual void stop() = 0; - /* Flush a stopped track. All pending buffers are discarded. - * This function has no effect if the track is not stopped. + /* Flush a stopped or paused track. All pending/released buffers are discarded. + * This function has no effect if the track is not stopped or paused. */ virtual void flush() = 0; @@ -62,7 +62,7 @@ public: /* Pause a track. If set, the callback will cease being called and * obtainBuffer will return an error. Buffers that are already released - * will be processed, unless flush() is called. + * will continue to be processed, unless/until flush() is called. */ virtual void pause() = 0; diff --git a/include/media/MemoryLeakTrackUtil.h b/include/media/MemoryLeakTrackUtil.h index 290b748..ac0f6b2 100644 --- a/include/media/MemoryLeakTrackUtil.h +++ b/include/media/MemoryLeakTrackUtil.h @@ -19,7 +19,7 @@ namespace android { /* - * Dump the memory adddress of the calling process to the given fd. + * Dump the memory address of the calling process to the given fd. */ extern void dumpMemoryAddresses(int fd); diff --git a/include/private/media/AudioTrackShared.h b/include/private/media/AudioTrackShared.h index 23226c0..af2db93 100644 --- a/include/private/media/AudioTrackShared.h +++ b/include/private/media/AudioTrackShared.h @@ -62,16 +62,23 @@ struct audio_track_cblk_t // are in the same line of data cache. Mutex lock; // sizeof(int) Condition cv; // sizeof(int) + + // next 4 are offsets within "buffers" volatile uint32_t user; volatile uint32_t server; uint32_t userBase; uint32_t serverBase; + + // if there is a shared buffer, "buffers" is the value of pointer() for the shared + // buffer, otherwise "buffers" points immediately after the control block void* buffers; uint32_t frameCount; + // Cache line boundary + uint32_t loopStart; - uint32_t loopEnd; - int loopCount; + uint32_t loopEnd; // read-only for server, read/write for client + int loopCount; // read/write for client // Channel volumes are fixed point U4.12, so 0x1000 means 1.0. // Left channel is in [0:15], right channel is in [16:31]. @@ -82,29 +89,39 @@ private: public: uint32_t sampleRate; + // NOTE: audio_track_cblk_t::frameSize is not equal to AudioTrack::frameSize() for // 8 bit PCM data: in this case, mCblk->frameSize is based on a sample size of // 16 bit because data is converted to 16 bit before being stored in buffer + // read-only for client, server writes once at initialization and is then read-only uint8_t frameSize; // would normally be size_t, but 8 bits is plenty + + // never used uint8_t pad1; + + // used by client only uint16_t bufferTimeoutMs; // Maximum cumulated timeout before restarting audioflinger - uint16_t waitTimeMs; // Cumulated wait time + uint16_t waitTimeMs; // Cumulated wait time, used by client only private: + // client write-only, server read-only uint16_t mSendLevel; // Fixed point U4.12 so 0x1000 means 1.0 public: volatile int32_t flags; // Cache line boundary (32 bytes) + // Since the control block is always located in shared memory, this constructor + // is only used for placement new(). It is never used for regular new() or stack. audio_track_cblk_t(); - uint32_t stepUser(uint32_t frameCount); - bool stepServer(uint32_t frameCount); + uint32_t stepUser(uint32_t frameCount); // called by client only, where + // client includes regular AudioTrack and AudioFlinger::PlaybackThread::OutputTrack + bool stepServer(uint32_t frameCount); // called by server only void* buffer(uint32_t offset) const; uint32_t framesAvailable(); uint32_t framesAvailable_l(); - uint32_t framesReady(); + uint32_t framesReady(); // called by server only bool tryLock(); // No barriers on the following operations, so the ordering of loads/stores |