Documentation for module: Audio

Former-commit-id: 4546f9db5579c219d708f87b7062104d24ec6da2

src/Nazara/Audio/Audio.cpp

@@ -16,6 +16,21 @@
 
 namespace Nz
 {
+	/*!
+	* \ingroup audio
+	* \class Nz::Audio
+	* \brief Audio class that represents the module initializer of Audio
+	*/
+
+	/*!
+	* \brief Gets the format of the audio
+	* \return AudioFormat Enumeration type for the format
+	*
+	* \param channelCount Number of channels
+	*
+	* \remark Produces a NazaraError if the number of channels is erroneous (3 or 5) and AudioFormat_Unknown is returned
+	*/
+
 	AudioFormat Audio::GetAudioFormat(unsigned int channelCount)
 	{
 		switch (channelCount)
@@ -34,19 +49,36 @@ namespace Nz
 		}
 	}
 
+	/*!
+	* \brief Gets the factor of the doppler effect
+	* \return Global factor of the doppler effect
+	*/
+
 	float Audio::GetDopplerFactor()
 	{
 		return alGetFloat(AL_DOPPLER_FACTOR);
 	}
 
+	/*!
+	* \brief Gets the global volume
+	* \return Float between [0, inf) with 100.f being the default
+	*/
+
 	float Audio::GetGlobalVolume()
 	{
 		ALfloat gain = 0.f;
 		alGetListenerf(AL_GAIN, &gain);
 
-		return gain*100.f;
+		return gain * 100.f;
 	}
 
+	/*!
+	* \brief Gets the direction of the listener
+	* \return Direction of the listener, in front of the listener
+	*
+	* \see GetListenerRotation
+	*/
+
 	Vector3f Audio::GetListenerDirection()
 	{
 		ALfloat orientation[6];
@@ -55,6 +87,13 @@ namespace Nz
 		return Vector3f(orientation[0], orientation[1], orientation[2]);
 	}
 
+	/*!
+	* \brief Gets the position of the listener
+	* \return Position of the listener
+	*
+	* \see GetListenerVelocity
+	*/
+
 	Vector3f Audio::GetListenerPosition()
 	{
 		Vector3f position;
@@ -63,6 +102,11 @@ namespace Nz
 		return position;
 	}
 
+	/*!
+	* \brief Gets the rotation of the listener
+	* \return Rotation of the listener
+	*/
+
 	Quaternionf Audio::GetListenerRotation()
 	{
 		ALfloat orientation[6];
@@ -73,6 +117,13 @@ namespace Nz
 		return Quaternionf::RotationBetween(Vector3f::Forward(), forward);
 	}
 
+	/*!
+	* \brief Gets the velocity of the listener
+	* \return Velocity of the listener
+	*
+	* \see GetListenerPosition
+	*/
+
 	Vector3f Audio::GetListenerVelocity()
 	{
 		Vector3f velocity;
@@ -81,20 +132,33 @@ namespace Nz
 		return velocity;
 	}
 
+	/*!
+	* \brief Gets the speed of sound
+	* \return Speed of sound
+	*/
+
 	float Audio::GetSpeedOfSound()
 	{
 		return alGetFloat(AL_SPEED_OF_SOUND);
 	}
 
+	/*!
+	* \brief Initializes the Audio module
+	* \return true if initialization is successful
+	*
+	* \remark Produces a NazaraError if initialization of modules Core, OpenAL or SoundBuffer failed
+	* \remark Produces a NazaraNotice
+	*/
+
 	bool Audio::Initialize()
 	{
-		if (s_moduleReferenceCounter > 0)
+		if (IsInitialized())
 		{
 			s_moduleReferenceCounter++;
-			return true; // Déjà initialisé
+			return true; // Already initialized
 		}
 
-		// Initialisation des dépendances
+		// Initialisation of dependencies
 		if (!Core::Initialize())
 		{
 			NazaraError("Failed to initialize core module");
@@ -103,10 +167,10 @@ namespace Nz
 
 		s_moduleReferenceCounter++;
 
-		// Initialisation du module
+		// Initialisation of the module
 		CallOnExit onExit(Audio::Uninitialize);
 
-		// Initialisation d'OpenAL
+		// Initialisation of OpenAL
 		if (!OpenAL::Initialize())
 		{
 			NazaraError("Failed to initialize OpenAL");
@@ -119,7 +183,7 @@ namespace Nz
 			return false;
 		}
 
-		// Définition de l'orientation par défaut
+		// Definition of the orientation by default
 		SetListenerDirection(Vector3f::Forward());
 
 		// Loaders
@@ -131,6 +195,13 @@ namespace Nz
 		return true;
 	}
 
+	/*!
+	* \brief Checks whether the format is supported by the engine
+	* \return true if it is the case
+	*
+	* \param format Format to check
+	*/
+
 	bool Audio::IsFormatSupported(AudioFormat format)
 	{
 		if (format == AudioFormat_Unknown)
@@ -139,21 +210,46 @@ namespace Nz
 		return OpenAL::AudioFormat[format] != 0;
 	}
 
+	/*!
+	* \brief Checks whether the module is initialized
+	* \return true if module is initialized
+	*/
+
 	bool Audio::IsInitialized()
 	{
 		return s_moduleReferenceCounter != 0;
 	}
 
+	/*!
+	* \brief Sets the factor of the doppler effect
+	*
+	* \param dopplerFactor Global factor of the doppler effect
+	*/
+
 	void Audio::SetDopplerFactor(float dopplerFactor)
 	{
 		alDopplerFactor(dopplerFactor);
 	}
 
+	/*!
+	* \brief Sets the global volume
+	*
+	* \param volume Float between [0, inf) with 100.f being the default
+	*/
+
 	void Audio::SetGlobalVolume(float volume)
 	{
-		alListenerf(AL_GAIN, volume*0.01f);
+		alListenerf(AL_GAIN, volume * 0.01f);
 	}
 
+	/*!
+	* \brief Sets the direction of the listener
+	*
+	* \param direction Direction of the listener, in front of the listener
+	*
+	* \see SetListenerDirection, SetListenerRotation
+	*/
+
 	void Audio::SetListenerDirection(const Vector3f& direction)
 	{
 		Vector3f up = Vector3f::Up();
@@ -167,6 +263,14 @@ namespace Nz
 		alListenerfv(AL_ORIENTATION, orientation);
 	}
 
+	/*!
+	* \brief Sets the direction of the listener
+	*
+	* \param (dirX, dirY, dirZ) Direction of the listener, in front of the listener
+	*
+	* \see SetListenerDirection, SetListenerRotation
+	*/
+
 	void Audio::SetListenerDirection(float dirX, float dirY, float dirZ)
 	{
 		Vector3f up = Vector3f::Up();
@@ -180,16 +284,38 @@ namespace Nz
 		alListenerfv(AL_ORIENTATION, orientation);
 	}
 
+	/*!
+	* \brief Sets the position of the listener
+	*
+	* \param position Position of the listener
+	*
+	* \see SetListenerVelocity
+	*/
+
 	void Audio::SetListenerPosition(const Vector3f& position)
 	{
 		alListenerfv(AL_POSITION, position);
 	}
 
+	/*!
+	* \brief Sets the position of the listener
+	*
+	* \param (x, y, z) Position of the listener
+	*
+	* \see SetListenerVelocity
+	*/
+
 	void Audio::SetListenerPosition(float x, float y, float z)
 	{
 		alListener3f(AL_POSITION, x, y, z);
 	}
 
+	/*!
+	* \brief Sets the rotation of the listener
+	*
+	* \param rotation Rotation of the listener
+	*/
+
 	void Audio::SetListenerRotation(const Quaternionf& rotation)
 	{
 		Vector3f forward = rotation * Vector3f::Forward();
@@ -204,33 +330,61 @@ namespace Nz
 		alListenerfv(AL_ORIENTATION, orientation);
 	}
 
+	/*!
+	* \brief Sets the velocity of the listener
+	*
+	* \param velocity Velocity of the listener
+	*
+	* \see SetListenerPosition
+	*/
+
 	void Audio::SetListenerVelocity(const Vector3f& velocity)
 	{
 		alListenerfv(AL_VELOCITY, velocity);
 	}
 
+	/*!
+	* \brief Sets the velocity of the listener
+	*
+	* \param (velX, velY, velZ) Velocity of the listener
+	*
+	* \see SetListenerPosition
+	*/
+
 	void Audio::SetListenerVelocity(float velX, float velY, float velZ)
 	{
 		alListener3f(AL_VELOCITY, velX, velY, velZ);
 	}
 
+	/*!
+	* \brief Sets the speed of sound
+	*
+	* \param speed Speed of sound
+	*/
+
 	void Audio::SetSpeedOfSound(float speed)
 	{
 		alSpeedOfSound(speed);
 	}
 
+	/*!
+	* \brief Uninitializes the Audio module
+	*
+	* \remark Produces a NazaraNotice
+	*/
+
 	void Audio::Uninitialize()
 	{
 		if (s_moduleReferenceCounter != 1)
 		{
-			// Le module est soit encore utilisé, soit pas initialisé
+			// The module is still in use, or can not be uninitialized
 			if (s_moduleReferenceCounter > 1)
 				s_moduleReferenceCounter--;
 
 			return;
 		}
 
-		// Libération du module
+		// Free of module
 		s_moduleReferenceCounter = 0;
 
 		// Loaders
@@ -241,7 +395,7 @@ namespace Nz
 
 		NazaraNotice("Uninitialized: Audio module");
 
-		// Libération des dépendances
+		// Free of dependencies
 		Core::Uninitialize();
 	}