diff --git a/include/eepp/audio/caudiodevice.hpp b/include/eepp/audio/caudiodevice.hpp index 71f30d6d5..8ff3ac165 100755 --- a/include/eepp/audio/caudiodevice.hpp +++ b/include/eepp/audio/caudiodevice.hpp @@ -5,16 +5,24 @@ namespace EE { namespace Audio { +/** + @brief High-level wrapper around the audio API, it manages + the creation and destruction of the audio device and + context and stores the device capabilities +*/ class EE_API cAudioDevice { public : cAudioDevice(); ~cAudioDevice(); + /** Get the OpenAL format that matches the given number of channels */ static ALenum GetFormatFromChannelsCount( unsigned int ChannelsCount ); + /** Checks if a AL or ALC extension is supported */ static bool IsExtensionSupported( const std::string& extension ); + /** @return True if the audio device was initialized */ static bool IsAvailable(); private : void PrintInfo(); diff --git a/include/eepp/audio/cmusic.hpp b/include/eepp/audio/cmusic.hpp index 4ffc608cd..e8ccf4eaf 100755 --- a/include/eepp/audio/cmusic.hpp +++ b/include/eepp/audio/cmusic.hpp @@ -2,11 +2,13 @@ #define EE_AUDIOCMUSIC_H #include -#include #include namespace EE { namespace Audio { +class cSoundFile; + +/** @brief Streamed music played from an audio file */ class EE_API cMusic : public cSoundStream { public : /** Construct the music with a buffer size */ diff --git a/include/eepp/audio/csound.hpp b/include/eepp/audio/csound.hpp index 33328453d..03d8ee1bb 100755 --- a/include/eepp/audio/csound.hpp +++ b/include/eepp/audio/csound.hpp @@ -2,11 +2,12 @@ #define EE_AUDIOCSOUND_H #include -#include +#include #include namespace EE { namespace Audio { +/** @brief Regular sound that can be played in the audio environment */ class EE_API cSound { public : /** @enum cSound::Status The state of the sound */ @@ -20,7 +21,7 @@ class EE_API cSound { ~cSound(); - /** Construct the sound from its parameters */ + /** Construct the sound with a buffer. */ cSound( const cSoundBuffer& Buffer, const bool& Loop = false, const eeFloat& Pitch = 1.f, const eeFloat& Volume = 100.f, const Vector3AL& Position = Vector3AL(0, 0, 0) ); /** Copy constructor */ diff --git a/include/eepp/audio/csoundbuffer.hpp b/include/eepp/audio/csoundbuffer.hpp index 489ba93c6..6208e68df 100755 --- a/include/eepp/audio/csoundbuffer.hpp +++ b/include/eepp/audio/csoundbuffer.hpp @@ -2,13 +2,13 @@ #define EE_AUDIOCSOUNDBUFFER_H #include -#include #include namespace EE { namespace Audio { class cSound; +/** @brief Storage for audio samples defining a sound */ class EE_API cSoundBuffer { public : cSoundBuffer(); diff --git a/include/eepp/audio/csoundfile.hpp b/include/eepp/audio/csoundfile.hpp index 3ced8ec99..d5ffdee48 100755 --- a/include/eepp/audio/csoundfile.hpp +++ b/include/eepp/audio/csoundfile.hpp @@ -5,28 +5,49 @@ namespace EE { namespace Audio { +/** @brief Provide read and write access to sound files */ class EE_API cSoundFile { public: + /** @brief Open a sound file for reading */ static cSoundFile * CreateRead(const std::string& Filename); + /** @brief Open a sound file from memory for reading */ static cSoundFile * CreateRead(const char* Data, std::size_t SizeInBytes); + /** @brief Open a sound file for writing */ static cSoundFile * CreateWrite(const std::string& Filename, unsigned int ChannelsCount, unsigned int SampleRate); virtual ~cSoundFile(); + /** @brief Get the total number of audio samples in the file */ std::size_t GetSamplesCount() const; + /** @brief Get the number of channels used by the sound + * @return Number of channels (1 = mono, 2 = stereo) + */ unsigned int GetChannelsCount() const; + /** @brief Get the sample rate of the sound + * @return Sample rate, in samples per second + */ unsigned int GetSampleRate() const; + /** @brief Restarts the audio from the beginning. */ bool Restart(); + /** @brief Read audio samples from the loaded sound + ** @param data Pointer to the sample array to fill + ** @param sampleCount Number of samples to read + ** @return Number of samples actually read (may be less than \a sampleCount) */ virtual std::size_t Read(Int16* Data, std::size_t NbSamples); + /** @brief Write audio samples to the file + ** @param data Pointer to the sample array to write + ** @param sampleCount Number of samples to write */ virtual void Write(const Int16* Data, std::size_t NbSamples); + /** @brief Change the current read position in the file + ** @param timeOffset New playing position, from the beginning of the file */ virtual void Seek( Uint32 timeOffset ); protected : cSoundFile(); diff --git a/include/eepp/audio/csoundstream.hpp b/include/eepp/audio/csoundstream.hpp index 2cb4a4735..8a43fbf20 100755 --- a/include/eepp/audio/csoundstream.hpp +++ b/include/eepp/audio/csoundstream.hpp @@ -6,6 +6,7 @@ namespace EE { namespace Audio { +/** @brief Abstract base class for streamed audio sources */ class EE_API cSoundStream : private cThread, private cSound { public: using cSound::Pause; @@ -17,6 +18,7 @@ class EE_API cSoundStream : private cThread, private cSound { using cSound::SetRelativeToListener; using cSound::IsRelativeToListener; + /** @brief Structure defining a chunk of audio data to stream */ struct Chunk { const Int16* Samples; ///< Pointer to the audio samples std::size_t NbSamples; ///< Number of samples pointed by Samples @@ -24,22 +26,55 @@ class EE_API cSoundStream : private cThread, private cSound { virtual ~cSoundStream(); + /** \brief Start or resume playing the audio stream + ** This function starts the stream if it was stopped, resumes + ** it if it was paused, and restarts it from beginning if it + ** was it already playing. + ** This function uses its own thread so that it doesn't block + ** the rest of the program while the stream is played. + ** @see Pause, Stop */ void Play(); + /** @brief Pause the audio stream + ** This function pauses the stream if it was playing, + ** otherwise (stream already paused or stopped) it has no effect. + ** @see Play, Stop */ void Pause(); + /** @brief Stop playing the audio stream + ** This function stops the stream if it was playing or paused, + ** and does nothing if it was already stopped. + ** It also resets the playing position (unlike pause()). + ** @see Play, Pause */ void Stop(); + /** @brief Return the number of channels of the stream + ** 1 channel means a mono sound, 2 means stereo, etc. + ** @return Number of channels */ unsigned int GetChannelsCount() const; + /** @brief Get the stream sample rate of the stream + ** The sample rate is the number of audio samples played per + ** second. The higher, the better the quality. + ** @return Sample rate, in number of samples per second */ unsigned int GetSampleRate() const; + /** @brief Get the current status of the stream (stopped, paused, playing) + ** @return Current status */ Status GetState() const; + /** @brief Get the current status of the stream (stopped, paused, playing) + ** @return Current status */ Status State() const ; + /** @brief Get the current playing position of the stream + ** @return Current playing position, from the beginning of the stream. */ Uint32 PlayingOffset() const; + /** @brief Change the current playing position of the stream + ** The playing position can be changed when the stream is + ** either paused or playing. + ** @param timeOffset New playing position, from the beginning of the stream */ void PlayingOffset( const Uint32& timeOffset ); /** Set the stream loop state. This parameter is disabled by default diff --git a/include/eepp/audio/openal.hpp b/include/eepp/audio/openal.hpp index 1fce4e728..dc719242a 100755 --- a/include/eepp/audio/openal.hpp +++ b/include/eepp/audio/openal.hpp @@ -20,8 +20,12 @@ namespace EE { namespace Audio { #define ALCheck(Func) (Func) #endif +/** Check the last OpenAL error +** @param file Source file where the call is located +** @param line Line number of the source file where the call is located */ void ALCheckError(const std::string& File, unsigned int Line); +/** Make sure that OpenAL is initialized */ void EnsureALInit(); }} diff --git a/include/eepp/audio/tsoundloader.hpp b/include/eepp/audio/tsoundloader.hpp index e0b81a018..a92340909 100644 --- a/include/eepp/audio/tsoundloader.hpp +++ b/include/eepp/audio/tsoundloader.hpp @@ -12,23 +12,29 @@ namespace EE { namespace Audio { #define SND_LT_PACK (3) #define SND_LT_SAMPLES (4) +/** @brief A helper template to load sounds in synchronous or asynchronous mode. +** @see cObjectLoader */ template class tSoundLoader : public cObjectLoader { public: + /** @brief Load the sound from file */ tSoundLoader( tSoundManager * SndMngr, const T& id, const std::string& filepath ); + /** @brief Load the sound from memory */ tSoundLoader( tSoundManager * SndMngr, const T& id, const char* Data, std::size_t SizeInBytes ); + /** @brief Load the sound from an array of samples */ tSoundLoader( tSoundManager * SndMngr, const T& id, const Int16* Samples, std::size_t SamplesCount, unsigned int ChannelsCount, unsigned int SampleRate ); + /** @brief Load the sound from the Pack file */ tSoundLoader( tSoundManager * SndMngr, const T& id, cPack* Pack, const std::string& FilePackPath ); ~tSoundLoader(); - void Update(); - + /** Unload the sound if was already loaded. */ void Unload(); + /** @return The sound id */ const T& Id() const; protected: Uint32 mLoadType; @@ -110,12 +116,6 @@ tSoundLoader::tSoundLoader( tSoundManager * SndMngr, template tSoundLoader::~tSoundLoader() { - -} - -template -void tSoundLoader::Update() { - } template diff --git a/include/eepp/audio/tsoundmanager.hpp b/include/eepp/audio/tsoundmanager.hpp index cc9509d40..9c39984e0 100755 --- a/include/eepp/audio/tsoundmanager.hpp +++ b/include/eepp/audio/tsoundmanager.hpp @@ -11,23 +11,47 @@ namespace EE { namespace Audio { template class tSoundManager { public: + /** @brief Load the sound from file + ** @param id The sound Id + ** @param filepath The sound path + */ bool LoadFromFile( const T& id, const std::string& filepath ); + /** @brief Load the sound from memory + ** @param id The sound id + ** @param Data The pointer to the data + ** @param SizeInBytes The size of the file to load */ bool LoadFromMemory( const T& id, const char* Data, std::size_t SizeInBytes ); + /** @brief Load the sound from an array of samples. + ** @param id The sound id + ** @param Samples Pointer to the array of samples in memory + ** @param SamplesCount Number of samples in the array + ** @param ChannelsCount Number of channels (1 = mono, 2 = stereo, ...) + ** @param SampleRate Sample rate (number of samples to play per second) */ bool LoadFromSamples( const T& id, const Int16* Samples, std::size_t SamplesCount, unsigned int ChannelsCount, unsigned int SampleRate ); + /** @brief Load the sound from a Pack file + ** @param Pack The Pack file + ** @param FilePackPath The pack file path */ bool LoadFromPack( const T& id, cPack* Pack, const std::string& FilePackPath ); + /** @return The sound buffer of the sound id */ cSoundBuffer& GetBuffer( const T& id ); - /** This method will open a new channel if the channel seted for the sound is playing. */ + /** Play the sound. This method will open a new channel if the channel seted for the sound is already playing. + ** @param id The sound id to play */ void Play( const T& id ); + /** Remove a sound from the sound manager. + ** @param id The sound id to remove */ bool Remove( const T& id ); + /** @return The sound id if exists */ cSound& operator[] ( const T& id ); + /** @brief Search for the sound id, and return a sound that is not playing, if all the sounds are playing, creates a new sound. + ** @return The sound */ cSound& GetFreeSound( const T& id ); ~tSoundManager(); diff --git a/include/eepp/ee.hpp b/include/eepp/ee.hpp index 406eb33a3..402070d36 100755 --- a/include/eepp/ee.hpp +++ b/include/eepp/ee.hpp @@ -19,28 +19,22 @@ * Jean-loup Gailly and Mark Adler for zlib \n * Milan Ikits and Marcelo Magallon for GLEW \n * And a lot more people! -**/ -/** PLANS: + + ROADMAP: Short-term plans: - @TODO Stabilize the API - STATE: It's looking good. But i'm changing things. - @TODO Improve documentation. STATE: EE ( Base ) documented what is needed. EE::Window documented. EE::System documented. EE::Graphics documented. - EE::Audio 50 % commented. - EE::Math 30 to 40 % commented. - EE::UI Not commented at all. - EE::Physics Not commented at all, chipmunk documentation should help. - EE::Gaming Not commented at all. - - @TODO Improve Premake4 support. It should be really easy to compile eepp in Windows and OS X ( Linux is always easy thanks to package managers ). - STATE: Seems to be done, needs more testing. + EE::Audio documented. + EE::Math 30 to 40 % documented. + EE::UI Not documented at all. + EE::Physics Not documented at all, chipmunk documentation should help. + EE::Gaming Not documented at all. @TODO Add more commented examples, showing at least the basic usage of the engine ( 10 or more examples at least ). STATE: 2 examples available. ( 20 % ) @@ -50,6 +44,12 @@ Tile selection i'm not decided yet. Copy-Paste will be moved for a middle to long term plan. + @TODO Stabilize the API + STATE: DONE. + + @TODO Improve Premake4 support. It should be really easy to compile eepp in Windows and OS X ( Linux is always easy thanks to package managers ). + STATE: DONE. + @TODO Add PVRTC and ETC support. STATE: DONE. @@ -70,6 +70,8 @@ @TODO Add some kind of support for TMX map files ( Tiles Map Editor ). + @TODO Pathfinding and AI helpers ( A*, FSM ). + */ // General includes and declarations diff --git a/include/eepp/graphics/ctextureloader.hpp b/include/eepp/graphics/ctextureloader.hpp index a00a30450..96a8f0c98 100644 --- a/include/eepp/graphics/ctextureloader.hpp +++ b/include/eepp/graphics/ctextureloader.hpp @@ -33,7 +33,7 @@ class EE_API cTextureLoader : public cObjectLoader { cTextureLoader( const std::string& Filepath, const bool& Mipmap = false, const EE_CLAMP_MODE& ClampMode = EE_CLAMP_TO_EDGE, const bool& CompressTexture = false, const bool& KeepLocalCopy = false ); /** Load a texture from memory - * @param ImagePtr The image data in RAM just as if it were still in a file + * @param ImagePtr The image data in memory just as if it were still in a file * @param Size The size of the texture ( Width * Height * BytesPerPixel ) * @param Mipmap Use mipmaps? * @param ClampMode Defines the CLAMP MODE diff --git a/projects/linux/ee.creator.user b/projects/linux/ee.creator.user index f070aacc6..8316988d5 100644 --- a/projects/linux/ee.creator.user +++ b/projects/linux/ee.creator.user @@ -1,6 +1,6 @@ - + ProjectExplorer.Project.ActiveTarget diff --git a/src/eepp/audio/cmusic.cpp b/src/eepp/audio/cmusic.cpp index e0ba58cbd..d1b110e04 100755 --- a/src/eepp/audio/cmusic.cpp +++ b/src/eepp/audio/cmusic.cpp @@ -1,4 +1,5 @@ #include +#include #include namespace EE { namespace Audio { diff --git a/src/eepp/audio/csound.cpp b/src/eepp/audio/csound.cpp index 22c9d8983..4e68b72e0 100755 --- a/src/eepp/audio/csound.cpp +++ b/src/eepp/audio/csound.cpp @@ -1,4 +1,5 @@ #include +#include namespace EE { namespace Audio { diff --git a/src/eepp/audio/csoundbuffer.cpp b/src/eepp/audio/csoundbuffer.cpp index 554288a70..4668fb536 100755 --- a/src/eepp/audio/csoundbuffer.cpp +++ b/src/eepp/audio/csoundbuffer.cpp @@ -1,5 +1,6 @@ #include #include +#include #include #include #include