vlc | branch: master | Rémi Denis-Courmont <[email protected]> | Sat May 5 12:27:25 2018 +0300| [e7abf4a4a95a431b752ab5fc52d49c4620fa5bd5] | committer: Rémi Denis-Courmont
aout: update Doxygen > http://git.videolan.org/gitweb.cgi/vlc.git/?a=commit;h=e7abf4a4a95a431b752ab5fc52d49c4620fa5bd5 --- include/vlc_aout.h | 69 +++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 60 insertions(+), 9 deletions(-) diff --git a/include/vlc_aout.h b/include/vlc_aout.h index a5c1c26a7d..25063bdfab 100644 --- a/include/vlc_aout.h +++ b/include/vlc_aout.h @@ -121,7 +121,19 @@ struct vlc_audio_output_events { int (*gain_request)(audio_output_t *, float); }; -/** Audio output object */ +/** Audio output object + * + * The audio output object is the abstraction for rendering decoded + * (or pass-through) audio samples. In addition to playing samples, + * the abstraction exposes controls for pause/resume, flush/drain, + * changing the volume or mut flag, and listing and changing output device. + * + * An audio output can be in one of three different states: + * stopped, playing or paused. + * The audio output is always created in stopped state and is always destroyed + * in that state also. It is moved from stopped to playing state by start(), + * and from playing or paused states back to stopped state by stop(). + **/ struct audio_output { struct vlc_common_members obj; @@ -130,56 +142,95 @@ struct audio_output int (*start)(audio_output_t *, audio_sample_format_t *fmt); /**< Starts a new stream (mandatory, cannot be NULL). + * + * This callback changes the audio output from stopped to playing state + * (if succesful). After the callback returns, time_get(), play(), + * pause(), flush() and eventually stop() callbacks may be called. + * * \param fmt input stream sample format upon entry, * output stream sample format upon return [IN/OUT] * \return VLC_SUCCESS on success, non-zero on failure - * \note No other stream may be already started when called. + * + * \note This callback can only be called while the audio output is in + * stopped state. There can be only one stream per audio output at a time. + * + * \note This callbacks needs not be reentrant. */ + void (*stop)(audio_output_t *); /**< Stops the existing stream (optional, may be NULL). - * \note A stream must have been started when called. + * + * This callback terminates the current audio stream, + * and returns the audio output to stopped state. + * + * \note This callback needs not be reentrant. */ + int (*time_get)(audio_output_t *, mtime_t *delay); /**< Estimates playback buffer latency (optional, may be NULL). + * * \param delay pointer to the delay until the next sample to be written * to the playback buffer is rendered [OUT] * \return 0 on success, non-zero on failure or lack of data - * \note A stream must have been started when called. + * + * \note This callback cannot be called in stopped state. */ + void (*play)(audio_output_t *, block_t *block, mtime_t date); /**< Queues a block of samples for playback (mandatory, cannot be NULL). + * * \param block block of audio samples * \param date intended system time to render the first sample - * \note A stream must have been started when called. + * + * \note This callback cannot be called in stopped state. */ + void (*pause)( audio_output_t *, bool pause, mtime_t date); /**< Pauses or resumes playback (optional, may be NULL). + * * \param pause pause if true, resume from pause if false * \param date timestamp when the pause or resume was requested - * \note A stream must have been started when called. + * + * \note This callback cannot be called in stopped state. */ + void (*flush)( audio_output_t *, bool wait); /**< Flushes or drains the playback buffers (mandatory, cannot be NULL). + * * \param wait true to wait for playback of pending buffers (drain), * false to discard pending buffers (flush) - * \note A stream must have been started when called. + * + * \note This callback cannot be called in stopped state. */ + int (*volume_set)(audio_output_t *, float volume); /**< Changes playback volume (optional, may be NULL). + * * \param volume requested volume (0. = mute, 1. = nominal) + * * \note The volume is always a positive number. + * * \warning A stream may or may not have been started when called. + * \warning This callback may be called concurrently with + * time_get(), play(), pause() or flush(). + * It will however be protected against concurrent calls to + * start(), stop(), volume_set(), mute_set() or device_select(). */ + int (*mute_set)(audio_output_t *, bool mute); /**< Changes muting (optinal, may be NULL). + * * \param mute true to mute, false to unmute - * \warning A stream may or may not have been started when called. + * \warning The same constraints apply as with volume_set(). */ + int (*device_select)(audio_output_t *, const char *id); /**< Selects an audio output device (optional, may be NULL). + * * \param id nul-terminated device unique identifier. * \return 0 on success, non-zero on failure. - * \warning A stream may or may not have been started when called. + * + * \warning The same constraints apply as with volume_set(). */ struct { _______________________________________________ vlc-commits mailing list [email protected] https://mailman.videolan.org/listinfo/vlc-commits
