From 99e53b86eebb605b70dd7591b89bf61a9414ed0e Mon Sep 17 00:00:00 2001 From: Glenn Kasten Date: Thu, 19 Jan 2012 08:59:58 -0800 Subject: Update comments We no longer put the filename at start of file. Change-Id: Ic435b159a23105681e3d4a6cb1ac097bc853302e --- include/media/AudioSystem.h | 2 +- include/media/AudioTrack.h | 46 ++++++++++++++++++++++++++----------- include/media/EffectsFactoryApi.h | 8 +++---- include/media/IAudioTrack.h | 8 +++---- include/media/MemoryLeakTrackUtil.h | 2 +- 5 files changed, 42 insertions(+), 24 deletions(-) (limited to 'include/media') 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& 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); -- cgit v1.1