sid
/
NazaraEngine
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Audio/Music: Improve documentation

This commit is contained in:
Lynix 2016-11-22 14:25:35 +01:00
parent 82c51bd16a
commit 3193aef29a
1 changed files with 41 additions and 94 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
src/Nazara/Audio/Music.cpp
View File

@ -61,8 +61,6 @@ namespace Nz
* \return true if creation was succesful * \return true if creation was succesful
* *
* \param soundStream Sound stream which is the source for the music * \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) bool Music::Create(SoundStream* soundStream)
@ -86,8 +84,9 @@ namespace Nz
/*! /*!
* \brief Destroys the current music and frees resources * \brief Destroys the current music and frees resources
*
* \remark If the Music is playing, it is stopped first.
*/ */
void Music::Destroy() void Music::Destroy()
{ {
if (m_impl) if (m_impl)
@ -104,18 +103,11 @@ namespace Nz
* *
* \param loop Should music loop * \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) void Music::EnableLooping(bool loop)
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return;
}
#endif
m_impl->loop = loop; m_impl->loop = loop;
} }
@ -124,18 +116,11 @@ namespace Nz
* \brief Gets the duration of the music * \brief Gets the duration of the music
* \return Duration of the music in milliseconds * \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 UInt32 Music::GetDuration() const
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return 0;
}
#endif
return m_impl->stream->GetDuration(); return m_impl->stream->GetDuration();
} }
@ -144,18 +129,11 @@ namespace Nz
* \brief Gets the format of the music * \brief Gets the format of the music
* \return Enumeration of type AudioFormat (mono, stereo, ...) * \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 AudioFormat Music::GetFormat() const
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return AudioFormat_Unknown;
}
#endif
return m_impl->stream->GetFormat(); return m_impl->stream->GetFormat();
} }
@ -164,7 +142,7 @@ namespace Nz
* \brief Gets the current offset in the music * \brief Gets the current offset in the music
* \return Offset in milliseconds (works with entire seconds) * \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 UInt32 Music::GetPlayingOffset() const
{ {
@ -183,7 +161,7 @@ namespace Nz
* \brief Gets the number of samples in the music * \brief Gets the number of samples in the music
* \return Count of samples (number of seconds * sample rate * channel count) * \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 UInt64 Music::GetSampleCount() const
{ {
@ -196,7 +174,7 @@ namespace Nz
* \brief Gets the rates of sample in the music * \brief Gets the rates of sample in the music
* \return Rate of sample in Hertz (Hz) * \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 UInt32 Music::GetSampleRate() const
{ {
@ -209,8 +187,7 @@ namespace Nz
* \brief Gets the status of the music * \brief Gets the status of the music
* \return Enumeration of type SoundStatus (Playing, Stopped, ...) * \return Enumeration of type SoundStatus (Playing, Stopped, ...)
* *
* \remark If the music is not playing, Stopped is returned * \remark Music must be valid when calling this function
* \remark Produces a NazaraError if there is no music with NAZARA_AUDIO_SAFE defined
*/ */
SoundStatus Music::GetStatus() const SoundStatus Music::GetStatus() const
{ {
@ -229,44 +206,37 @@ namespace Nz
* \brief Checks whether the music is looping * \brief Checks whether the music is looping
* \return true if it is the case * \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 bool Music::IsLooping() const
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return false;
}
#endif
return m_impl->loop; return m_impl->loop;
} }
/*! /*!
* \brief Loads the music from file * \brief Opens the music from a file
* \return true if loading is successful * \return true if the file was successfully opened
* *
* \param filePath Path to the file * \param filePath Path to the file
* \param params Parameters for the music * \param params Parameters for the music
*/ */
bool Music::OpenFromFile(const String& filePath, const MusicParams& params) bool Music::OpenFromFile(const String& filePath, const MusicParams& params)
{ {
return MusicLoader::LoadFromFile(this, filePath, 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 * \return true if loading is successful
* *
* \param data Raw memory * \param data Raw memory
* \param size Size of the memory * \param size Size of the memory
* \param params Parameters for the music * \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) bool Music::OpenFromMemory(const void* data, std::size_t size, const MusicParams& params)
{ {
return MusicLoader::LoadFromMemory(this, data, size, params); return MusicLoader::LoadFromMemory(this, data, size, params);
@ -278,8 +248,9 @@ namespace Nz
* *
* \param stream Stream to the music * \param stream Stream to the music
* \param params Parameters for 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) bool Music::OpenFromStream(Stream& stream, const MusicParams& params)
{ {
return MusicLoader::LoadFromStream(this, stream, params); return MusicLoader::LoadFromStream(this, stream, params);
@ -287,8 +258,9 @@ namespace Nz
/*! /*!
* \brief Pauses the music * \brief Pauses the music
*
* \remark Music must be valid when calling this function
*/ */
void Music::Pause() void Music::Pause()
{ {
alSourcePause(m_source); alSourcePause(m_source);
@ -297,18 +269,16 @@ namespace Nz
/*! /*!
* \brief Plays the music * \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() void Music::Play()
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return;
}
#endif
// Maybe we are already playing // Maybe we are already playing
if (m_impl->streaming) 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) void Music::SetPlayingOffset(UInt32 offset)
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return;
}
#endif
bool isPlaying = m_impl->streaming; bool isPlaying = m_impl->streaming;
if (isPlaying) if (isPlaying)
Stop(); Stop();
@ -368,18 +333,11 @@ namespace Nz
/*! /*!
* \brief Stops the music * \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() void Music::Stop()
{ {
#if NAZARA_AUDIO_SAFE NazaraAssert(m_impl, "Music not created");
if (!m_impl)
{
NazaraError("Music not created");
return;
}
#endif
if (m_impl->streaming) 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) bool Music::FillAndQueueBuffer(unsigned int buffer)
{ {
std::size_t sampleCount = m_impl->chunkSamples.size(); 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) return sampleRead != sampleCount; // End of stream (Does not happen when looping)
} }
/*!
* \brief Thread function for the music
*/
void Music::MusicThread() void Music::MusicThread()
{ {
// Allocation of streaming buffers // Allocation of streaming buffers
@ -463,11 +410,11 @@ namespace Nz
{ {
ALuint buffer; ALuint buffer;
alSourceUnqueueBuffers(m_source, 1, &buffer); alSourceUnqueueBuffers(m_source, 1, &buffer);
ALint bits, size; ALint bits, size;
alGetBufferi(buffer, AL_BITS, &bits); alGetBufferi(buffer, AL_BITS, &bits);
alGetBufferi(buffer, AL_SIZE, &size); alGetBufferi(buffer, AL_SIZE, &size);
if (bits != 0) if (bits != 0)
m_impl->processedSamples += (8 * size) / bits; m_impl->processedSamples += (8 * size) / bits;