From 3193aef29a39b8764b6e9a94278f222e4d327b7b Mon Sep 17 00:00:00 2001 From: Lynix Date: Tue, 22 Nov 2016 14:25:35 +0100 Subject: [PATCH] Audio/Music: Improve documentation --- src/Nazara/Audio/Music.cpp | 135 +++++++++++-------------------------- 1 file changed, 41 insertions(+), 94 deletions(-) diff --git a/src/Nazara/Audio/Music.cpp b/src/Nazara/Audio/Music.cpp index 1f0df6ba5..dfbb516e4 100644 --- a/src/Nazara/Audio/Music.cpp +++ b/src/Nazara/Audio/Music.cpp @@ -61,8 +61,6 @@ namespace Nz * \return true if creation was succesful * * \param soundStream Sound stream which is the source for the music - * - * \remark Produces a NazaraError if soundStream is invalid with NAZARA_AUDIO_SAFE defined */ bool Music::Create(SoundStream* soundStream) @@ -86,8 +84,9 @@ namespace Nz /*! * \brief Destroys the current music and frees resources + * + * \remark If the Music is playing, it is stopped first. */ - void Music::Destroy() { if (m_impl) @@ -104,18 +103,11 @@ namespace Nz * * \param loop Should music loop * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ - void Music::EnableLooping(bool loop) { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return; - } - #endif + NazaraAssert(m_impl, "Music not created"); m_impl->loop = loop; } @@ -124,18 +116,11 @@ namespace Nz * \brief Gets the duration of the music * \return Duration of the music in milliseconds * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ - UInt32 Music::GetDuration() const { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return 0; - } - #endif + NazaraAssert(m_impl, "Music not created"); return m_impl->stream->GetDuration(); } @@ -144,18 +129,11 @@ namespace Nz * \brief Gets the format of the music * \return Enumeration of type AudioFormat (mono, stereo, ...) * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ - AudioFormat Music::GetFormat() const { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return AudioFormat_Unknown; - } - #endif + NazaraAssert(m_impl, "Music not created"); return m_impl->stream->GetFormat(); } @@ -164,7 +142,7 @@ namespace Nz * \brief Gets the current offset in the music * \return Offset in milliseconds (works with entire seconds) * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ UInt32 Music::GetPlayingOffset() const { @@ -183,7 +161,7 @@ namespace Nz * \brief Gets the number of samples in the music * \return Count of samples (number of seconds * sample rate * channel count) * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ UInt64 Music::GetSampleCount() const { @@ -196,7 +174,7 @@ namespace Nz * \brief Gets the rates of sample in the music * \return Rate of sample in Hertz (Hz) * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ UInt32 Music::GetSampleRate() const { @@ -209,8 +187,7 @@ namespace Nz * \brief Gets the status of the music * \return Enumeration of type SoundStatus (Playing, Stopped, ...) * - * \remark If the music is not playing, Stopped is returned - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ SoundStatus Music::GetStatus() const { @@ -229,44 +206,37 @@ namespace Nz * \brief Checks whether the music is looping * \return true if it is the case * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ - bool Music::IsLooping() const { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return false; - } - #endif + NazaraAssert(m_impl, "Music not created"); return m_impl->loop; } /*! - * \brief Loads the music from file - * \return true if loading is successful + * \brief Opens the music from a file + * \return true if the file was successfully opened * * \param filePath Path to the file * \param params Parameters for the music */ - bool Music::OpenFromFile(const String& filePath, const MusicParams& params) { return MusicLoader::LoadFromFile(this, filePath, params); } /*! - * \brief Loads the music from memory + * \brief Opens the music from memory * \return true if loading is successful * * \param data Raw memory * \param size Size of the memory * \param params Parameters for the music + * + * \remark The memory pointer must stay valid (accessible) as long as the music is playing */ - bool Music::OpenFromMemory(const void* data, std::size_t size, const MusicParams& params) { return MusicLoader::LoadFromMemory(this, data, size, params); @@ -278,8 +248,9 @@ namespace Nz * * \param stream Stream to the music * \param params Parameters for the music + * + * \remark The stream must stay valid as long as the music is playing */ - bool Music::OpenFromStream(Stream& stream, const MusicParams& params) { return MusicLoader::LoadFromStream(this, stream, params); @@ -287,8 +258,9 @@ namespace Nz /*! * \brief Pauses the music + * + * \remark Music must be valid when calling this function */ - void Music::Pause() { alSourcePause(m_source); @@ -297,18 +269,16 @@ namespace Nz /*! * \brief Plays the music * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * Plays/Resume the music. + * If the music is currently playing, resets the playing offset to the beginning offset. + * If the music is currently paused, resumes the playing. + * If the music is currently stopped, starts the playing at the previously set playing offset. + * + * \remark Music must be valid when calling this function */ - void Music::Play() { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return; - } - #endif + NazaraAssert(m_impl, "Music not created"); // Maybe we are already playing if (m_impl->streaming) @@ -336,25 +306,20 @@ namespace Nz } /*! - * \brief Sets the playing offset for the music + * \brief Changes the playing offset of the music * - * \param offset Offset in the music in milliseconds + * If the music is not playing, this sets the playing offset for the next Play call * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \param offset The offset in milliseconds + * + * \remark Music must be valid when calling this function */ - void Music::SetPlayingOffset(UInt32 offset) { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return; - } - #endif + NazaraAssert(m_impl, "Music not created"); bool isPlaying = m_impl->streaming; - + if (isPlaying) Stop(); @@ -368,18 +333,11 @@ namespace Nz /*! * \brief Stops the music * - * \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined + * \remark Music must be valid when calling this function */ - void Music::Stop() { - #if NAZARA_AUDIO_SAFE - if (!m_impl) - { - NazaraError("Music not created"); - return; - } - #endif + NazaraAssert(m_impl, "Music not created"); if (m_impl->streaming) { @@ -388,13 +346,6 @@ namespace Nz } } - /*! - * \brief Fills the buffer and queues it up - * \return true if operation was successful - * - * \param buffer Index of the buffer - */ - bool Music::FillAndQueueBuffer(unsigned int buffer) { std::size_t sampleCount = m_impl->chunkSamples.size(); @@ -425,10 +376,6 @@ namespace Nz return sampleRead != sampleCount; // End of stream (Does not happen when looping) } - /*! - * \brief Thread function for the music - */ - void Music::MusicThread() { // Allocation of streaming buffers @@ -463,11 +410,11 @@ namespace Nz { ALuint buffer; alSourceUnqueueBuffers(m_source, 1, &buffer); - + ALint bits, size; alGetBufferi(buffer, AL_BITS, &bits); alGetBufferi(buffer, AL_SIZE, &size); - + if (bits != 0) m_impl->processedSamples += (8 * size) / bits;