From d745172cda0210fb288afa90b055d4ab5a6efbf9 Mon Sep 17 00:00:00 2001 From: Axel Nana Date: Sat, 5 Oct 2024 17:27:07 +0100 Subject: [PATCH] chore(docs): Full API reference. Signed-off-by: Axel Nana --- .gitignore | 5 - CMakeLists.txt | 13 +- README.md | 40 +- .../SparkyStudios/Audio/Amplitude/Amplitude.h | 5 +- .../Audio/Amplitude/Core/Asset.h | 6 +- .../Audio/Amplitude/Core/AudioBuffer.h | 166 ++- .../Audio/Amplitude/Core/Codec.h | 130 +- .../Audio/Amplitude/Core/Common.h | 226 ++-- .../Audio/Amplitude/Core/Common/Config.h | 10 +- .../Core/Common/Platforms/Android/Config.h | 2 +- .../Core/Common/Platforms/Apple/Config.h | 11 +- .../Core/Common/Platforms/Linux/Config.h | 4 +- .../Core/Common/Platforms/UNIX/Config.h | 8 +- .../Audio/Amplitude/Core/Device.h | 47 +- .../Audio/Amplitude/Core/Driver.h | 40 +- .../Audio/Amplitude/Core/Engine.h | 1133 +++++++++++------ .../Audio/Amplitude/Core/Entity.h | 120 +- .../Audio/Amplitude/Core/Environment.h | 96 +- .../Audio/Amplitude/Core/Event.h | 71 +- .../Audio/Amplitude/Core/Listener.h | 105 +- .../SparkyStudios/Audio/Amplitude/Core/Log.h | 97 +- .../Audio/Amplitude/Core/Memory.h | 294 ++++- .../Audio/Amplitude/Core/Playback/Bus.h | 76 +- .../Audio/Amplitude/Core/Playback/Channel.h | 163 ++- .../Core/Playback/ChannelEventListener.h | 61 +- .../Audio/Amplitude/Core/RefCounter.h | 4 +- .../SparkyStudios/Audio/Amplitude/Core/Room.h | 158 ++- .../Audio/Amplitude/Core/Thread.h | 89 +- .../Audio/Amplitude/Core/Version.h | 12 +- .../Audio/Amplitude/DSP/AudioConverter.h | 54 +- .../{Convolution => DSP}/Convolver.h | 46 +- .../Audio/Amplitude/{Math => DSP}/FFT.h | 35 +- .../Audio/Amplitude/DSP/Filter.h | 145 ++- .../Audio/Amplitude/DSP/Resampler.h | 115 +- .../Amplitude/{Math => DSP}/SplitComplex.h | 24 +- .../Audio/Amplitude/HRTF/HRIRSphere.h | 16 +- .../Audio/Amplitude/IO/DiskFile.h | 48 +- .../Audio/Amplitude/IO/DiskFileSystem.h | 31 +- .../SparkyStudios/Audio/Amplitude/IO/File.h | 95 +- .../Audio/Amplitude/IO/FileSystem.h | 84 +- .../Audio/Amplitude/IO/MemoryFile.h | 50 +- .../Audio/Amplitude/IO/PackageFileSystem.h | 73 +- .../Audio/Amplitude/IO/PackageItemFile.h | 28 +- .../Audio/Amplitude/IO/Resource.h | 9 +- .../Amplitude/Math/BarycentricCoordinates.h | 20 +- .../Math/CartesianCoordinateSystem.h | 20 +- .../Audio/Amplitude/Math/Curve.h | 69 +- .../Audio/Amplitude/Math/Geometry.h | 29 +- .../Audio/Amplitude/Math/Orientation.h | 16 +- .../Audio/Amplitude/Math/Shape.h | 343 +++-- .../Audio/Amplitude/Math/SphericalPosition.h | 43 +- .../Audio/Amplitude/Math/Utils.h | 118 +- .../Audio/Amplitude/Mixer/Amplimix.h | 240 +++- .../Audio/Amplitude/Mixer/Node.h | 182 +-- .../Audio/Amplitude/Mixer/Pipeline.h | 34 +- .../Audio/Amplitude/Sound/Attenuation.h | 44 +- .../Audio/Amplitude/Sound/Collection.h | 18 +- .../Audio/Amplitude/Sound/Effect.h | 25 +- .../Audio/Amplitude/Sound/Fader.h | 125 +- .../Audio/Amplitude/Sound/Rtpc.h | 57 +- .../Audio/Amplitude/Sound/Sound.h | 18 +- .../Audio/Amplitude/Sound/SoundBank.h | 43 +- .../Audio/Amplitude/Sound/SoundObject.h | 13 +- .../Audio/Amplitude/Sound/Switch.h | 66 +- .../Audio/Amplitude/Sound/SwitchContainer.h | 24 +- schemas/common.fbs | 6 +- src/Ambisonics/AmbisonicBinauralizer.h | 2 +- src/Core/Codecs/AMS/Codec.cpp | 6 +- src/Core/Codecs/MP3/Codec.cpp | 8 +- src/Core/Codecs/WAV/Codec.cpp | 8 +- src/Core/Common.cpp | 14 +- src/Core/Engine.cpp | 10 +- src/Core/Log.cpp | 22 +- src/Core/Playback/Bus.cpp | 8 + src/Core/Playback/BusInternalState.cpp | 9 +- src/Core/Playback/BusInternalState.h | 2 +- src/Core/Playback/Channel.cpp | 2 - src/Core/Playback/ChannelInternalState.cpp | 16 +- src/Core/Version.cpp | 2 +- src/{Convolution => DSP}/Convolver.cpp | 2 +- src/{Math => DSP}/FFT.cpp | 2 +- src/DSP/Filter.cpp | 4 +- src/DSP/Filters/BassBoostFilter.cpp | 6 +- src/DSP/Filters/BiquadResonantFilter.cpp | 8 +- src/DSP/Filters/DCRemovalFilter.cpp | 26 +- src/DSP/Filters/DCRemovalFilter.h | 5 +- src/DSP/Filters/DelayFilter.cpp | 8 +- src/DSP/Filters/EqualizerFilter.cpp | 30 +- src/DSP/Filters/FFTFilter.cpp | 59 +- src/DSP/Filters/FFTFilter.h | 5 +- src/DSP/Filters/FlangerFilter.cpp | 6 +- src/DSP/Filters/LofiFilter.cpp | 6 +- src/DSP/Filters/MonoPoleFilter.cpp | 6 +- src/DSP/Filters/RobotizeFilter.cpp | 6 +- src/DSP/Filters/WaveShaperFilter.cpp | 6 +- src/{Math => DSP}/SplitComplex.cpp | 2 +- src/IO/DiskFile.cpp | 34 +- src/IO/DiskFileSystem.cpp | 2 +- src/IO/File.cpp | 2 +- src/IO/MemoryFile.cpp | 34 +- src/IO/PackageFileSystem.cpp | 4 +- src/IO/PackageItemFile.cpp | 18 +- src/Sound/Fader.cpp | 20 +- src/Utils/Utils.h | 2 +- tools/amac/main.cpp | 9 +- tools/amir/main.cpp | 2 +- tools/ampk/main.cpp | 11 +- 107 files changed, 3921 insertions(+), 2111 deletions(-) rename include/SparkyStudios/Audio/Amplitude/{Convolution => DSP}/Convolver.h (73%) rename include/SparkyStudios/Audio/Amplitude/{Math => DSP}/FFT.h (64%) rename include/SparkyStudios/Audio/Amplitude/{Math => DSP}/SplitComplex.h (84%) rename src/{Convolution => DSP}/Convolver.cpp (98%) rename src/{Math => DSP}/FFT.cpp (97%) rename src/{Math => DSP}/SplitComplex.cpp (97%) diff --git a/.gitignore b/.gitignore index 758ce48e..54098d09 100644 --- a/.gitignore +++ b/.gitignore @@ -49,11 +49,6 @@ cmake-*/ # Misc generated files tags/ -docs/html/ -docs/linklint_results/ -docs/resources/_gen/ -docs/.hugo_build.lock -docs/node_modules/ gen/ .DS_Store diff --git a/CMakeLists.txt b/CMakeLists.txt index 300f69b1..e82f7f3f 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -119,7 +119,6 @@ build_flatbuffers("${FLATBUFFERS_SCHEMAS}" # Setup project source files. set(SA_SOURCE - include/SparkyStudios/Audio/Amplitude/Convolution/Convolver.h include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Config.h include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Types.h include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Apple/Config.h @@ -155,8 +154,11 @@ set(SA_SOURCE include/SparkyStudios/Audio/Amplitude/Core/Thread.h include/SparkyStudios/Audio/Amplitude/Core/Version.h include/SparkyStudios/Audio/Amplitude/DSP/AudioConverter.h + include/SparkyStudios/Audio/Amplitude/DSP/Convolver.h + include/SparkyStudios/Audio/Amplitude/DSP/FFT.h include/SparkyStudios/Audio/Amplitude/DSP/Filter.h include/SparkyStudios/Audio/Amplitude/DSP/Resampler.h + include/SparkyStudios/Audio/Amplitude/DSP/SplitComplex.h include/SparkyStudios/Audio/Amplitude/HRTF/HRIRSphere.h include/SparkyStudios/Audio/Amplitude/IO/DiskFile.h include/SparkyStudios/Audio/Amplitude/IO/DiskFileSystem.h @@ -169,13 +171,11 @@ set(SA_SOURCE include/SparkyStudios/Audio/Amplitude/Math/BarycentricCoordinates.h include/SparkyStudios/Audio/Amplitude/Math/CartesianCoordinateSystem.h include/SparkyStudios/Audio/Amplitude/Math/Curve.h - include/SparkyStudios/Audio/Amplitude/Math/FFT.h include/SparkyStudios/Audio/Amplitude/Math/Geometry.h include/SparkyStudios/Audio/Amplitude/Math/HandmadeMath.h include/SparkyStudios/Audio/Amplitude/Math/Orientation.h include/SparkyStudios/Audio/Amplitude/Math/Shape.h include/SparkyStudios/Audio/Amplitude/Math/SphericalPosition.h - include/SparkyStudios/Audio/Amplitude/Math/SplitComplex.h include/SparkyStudios/Audio/Amplitude/Math/Utils.h include/SparkyStudios/Audio/Amplitude/Mixer/Amplimix.h include/SparkyStudios/Audio/Amplitude/Mixer/Node.h @@ -209,8 +209,6 @@ set(SA_SOURCE src/Ambisonics/BFormat.cpp src/Ambisonics/BFormat.h - src/Convolution/Convolver.cpp - src/Core/Codecs/AMS/Codec.cpp src/Core/Codecs/AMS/Codec.h @@ -296,8 +294,10 @@ set(SA_SOURCE src/DSP/Resamplers/LibsamplerateResampler.h src/DSP/Resamplers/R8BrainResampler.h src/DSP/AudioConverter.cpp + src/DSP/Convolver.cpp src/DSP/Delay.cpp src/DSP/Delay.h + src/DSP/FFT.cpp src/DSP/Filter.cpp src/DSP/Gain.cpp src/DSP/Gain.h @@ -306,6 +306,7 @@ set(SA_SOURCE src/DSP/ReflectionsProcessor.cpp src/DSP/ReflectionsProcessor.h src/DSP/Resampler.cpp + src/DSP/SplitComplex.cpp src/HRTF/HRIRSphere.cpp src/HRTF/HRIRSphere.h @@ -323,11 +324,9 @@ set(SA_SOURCE src/Math/Orientation.cpp src/Math/FaceBSPTree.cpp src/Math/FaceBSPTree.h - src/Math/FFT.cpp src/Math/Geometry.cpp src/Math/Shape.cpp src/Math/SphericalPosition.cpp - src/Math/SplitComplex.cpp src/Mixer/Nodes/AmbisonicBinauralDecoderNode.cpp src/Mixer/Nodes/AmbisonicBinauralDecoderNode.h diff --git a/README.md b/README.md index 1f40806b..3cc1eedf 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@

- +

@@ -21,12 +21,12 @@ thanks to its data-driven way. All you need is to write configuration files and
-[Project Setup](https://amplitudeaudiosdk.com/docs/project-setup/) | [Integration](https://amplitudeaudiosdk.com/docs/integration/) | API Documentation +[Project Setup](https://docs.amplitudeaudiosdk.com/nightly/project/) | [Integration](https://docs.amplitudeaudiosdk.com/nightly/integration/) | API Documentation
-> Amplitude is still in active development, and no official release is made yet. However, the API is stable and no breaking changes will be introduced until the first release. To get a copy of the SDK, you should [build it from sources](https://amplitudeaudiosdk.com/docs/get-started/installation/#build-the-sdk-from-sources). Feel free to raise an [issue](https://github.com/AmplitudeAudio/sdk/issues/new/choose "Open a Github Issue") or open a [PR](https://github.com/AmplitudeAudio/sdk/pulls), by following our [Contributor Guidelines](https://github.com/AmplitudeAudio/sdk/blob/main/CODE_OF_CONDUCT.md). +> Amplitude is still in active development, and no official release is made yet. However, the API is stable and no breaking changes will be introduced until the first release. To get a copy of the SDK, you should [build it from sources](https://docs.amplitudeaudiosdk.com/nightly/getting-started/installation/#build-from-sources). Feel free to raise an [issue](https://github.com/AmplitudeAudio/sdk/issues/new/choose "Open a Github Issue") or open a [PR](https://github.com/AmplitudeAudio/sdk/pulls), by following our [Contributor Guidelines](https://github.com/AmplitudeAudio/sdk/blob/main/CODE_OF_CONDUCT.md). ## Sample Projects @@ -35,21 +35,23 @@ The quickest way to get started with the SDK is to have a look on the [sample pr ## Features This is a list of some of the most important features of Amplitude: -- [Data-driven Development](https://amplitudeaudiosdk.com/docs/get-started/introduction/#data-driven-development) -- [Plugin Architecture](https://amplitudeaudiosdk.com/docs/get-started/introduction/#plugin-architecture) -- [Drivers and Codecs](https://amplitudeaudiosdk.com/docs/get-started/introduction/#drivers-and-codecs) -- [Customizable Pipeline](https://amplitudeaudiosdk.com/docs/get-started/introduction/#customizable-pipeline) -- [Soundbanks Management](https://amplitudeaudiosdk.com/docs/get-started/introduction/#soundbanks-management) -- [Sound Objects](https://amplitudeaudiosdk.com/docs/get-started/introduction/#sound-objects) -- [Game and Engine Synchronization](https://amplitudeaudiosdk.com/docs/get-started/introduction/#game-and-engine-synchronization) -- [Game Entities](https://amplitudeaudiosdk.com/docs/get-started/introduction/#game-entities) -- [Listeners](https://amplitudeaudiosdk.com/docs/get-started/introduction/#listeners) -- [Customizable Attenuation Models](https://amplitudeaudiosdk.com/docs/get-started/introduction/#customizable-attenuation-models) -- [Sound Effects](https://amplitudeaudiosdk.com/docs/get-started/introduction/#sound-effects) -- [Sound Events](https://amplitudeaudiosdk.com/docs/get-started/introduction/#sound-events) -- [Buses Management and Auto-ducking](https://amplitudeaudiosdk.com/docs/get-started/introduction/#buses-management-and-auto-ducking) -- [Channel Priority](https://amplitudeaudiosdk.com/docs/get-started/introduction/#channel-priority) -- [ADPCM Compression and sample rate conversion](https://amplitudeaudiosdk.com/docs/get-started/introduction/#adpcm-compression-and-sample-rate-conversion) + +- [Spatial Audio, HRTF, and Ambisonic Rendering](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#spatial-audio-hrtf-and-ambisonic-rendering) +- [Data-driven Development](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#data-driven-development) +- [Plugin Architecture](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#plugin-architecture) +- [Drivers and Codecs](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#drivers-and-codecs) +- [Customizable Pipeline](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#customizable-pipeline) +- [Sound banks Management](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#sound-banks-management) +- [Sound Objects](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#sound-objects) +- [Game and Engine Synchronization](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#game-and-engine-synchronization) +- [Game Entities](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#game-entities) +- [Listeners](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#listeners) +- [Customizable Attenuation Models](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#customizable-attenuation-models) +- [Sound Effects](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#sound-effects) +- [Sound Events](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#sound-events) +- [Buses Management and Auto-ducking](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#buses-management-and-auto-ducking) +- [Channel Priority](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#channel-priority) +- [CLI Tools](https://docs.amplitudeaudiosdk.com/nightly/getting-started/introduction/#cli-tools) ## Supported Platforms @@ -60,7 +62,7 @@ Amplitude can support the following platforms: - ✔️ [OS X](https://www.apple.com/osx/) - ✔️ [Windows](https://www.microsoft.com/windows/) -Amplitude uses [MiniAudio](http://miniaud.io/) as the default audio device implementation for cross-platform support. You still can change that by implementing a [custom driver](https://amplitudeaudiosdk.com/docs/guide/custom-driver/). +Amplitude uses [MiniAudio](http://miniaud.io/) as the default audio device implementation for cross-platform support. You still can change that by implementing a [custom driver](https://docs.amplitudeaudiosdk.com/nightly/tutorials/custom-driver/). ## Download diff --git a/include/SparkyStudios/Audio/Amplitude/Amplitude.h b/include/SparkyStudios/Audio/Amplitude/Amplitude.h index 794154ab..16cdad3f 100644 --- a/include/SparkyStudios/Audio/Amplitude/Amplitude.h +++ b/include/SparkyStudios/Audio/Amplitude/Amplitude.h @@ -38,8 +38,11 @@ #include #include +#include +#include #include #include +#include #include @@ -55,13 +58,11 @@ #include #include #include -#include #include #include #include #include #include -#include #include #include diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Asset.h b/include/SparkyStudios/Audio/Amplitude/Core/Asset.h index a79a0b34..5ad2f638 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Asset.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Asset.h @@ -25,10 +25,12 @@ namespace SparkyStudios::Audio::Amplitude * @brief Amplitude Asset. * * This is the base class for all Amplitude assets. An Amplitude asset is a - * .json file with a specific format (definition), which is specified by the - * corresponding asset flatbuffer schema. + * `.json` file with a specific format (definition) specified by the corresponding + * asset's flatbuffer schema. * * @tparam Id The type of the asset id. + * + * @ingroup assets */ template class AM_API_PUBLIC Asset diff --git a/include/SparkyStudios/Audio/Amplitude/Core/AudioBuffer.h b/include/SparkyStudios/Audio/Amplitude/Core/AudioBuffer.h index 17c60cf5..5483b844 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/AudioBuffer.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/AudioBuffer.h @@ -22,7 +22,11 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Represents a view to a single channel in an @c AudioBuffer. + * @brief Represents a view to a single channel in an `AudioBuffer`. + * + * @see AudioBuffer + * + * @ingroup core */ class AM_API_PUBLIC AudioBufferChannel { @@ -63,75 +67,75 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] const AmReal32* end() const; /** - * @brief Clears the channel data to zero. + * @brief Clears the channel data with zero. */ void clear(); /** * @brief Checks if the channel is enabled. * - * @return @c true if the channel is enabled, @c false otherwise. + * @return `true` if the channel is enabled, `false` otherwise. */ [[nodiscard]] bool enabled() const; /** - * @brief Gets the frame at the specified index. + * @brief Gets the audio sample at the specified index. * - * @param index The frame index. + * @param[in] index The audio sample index. * - * @return The frame at the specified index. + * @return The audio sample at the specified index. */ AmReal32& operator[](AmSize index); /** - * @brief Gets the frame at the specified index. + * @brief Gets the audio sample at the specified index. * - * @param index The frame index. + * @param[in] index The audio sample index. * - * @return The frame at the specified index. + * @return The audio sample at the specified index. */ [[nodiscard]] const AmReal32& operator[](AmSize index) const; /** * @brief Sets the entire channel data from the provided vector. * - * @param data The vector containing the new channel data. + * @param[in] data The vector containing the new channel data. * * @return A reference to the modified channel. */ AudioBufferChannel& operator=(const std::vector& data); /** - * @brief Sets the entire channel data from the provided @c AudioBufferChannel. + * @brief Sets the entire channel data from the provided `AudioBufferChannel`. * - * @param channel The @c AudioBufferChannel to copy the data from. + * @param[in] channel The `AudioBufferChannel` to copy the data from. * * @return A reference to the modified channel. */ AudioBufferChannel& operator=(const AudioBufferChannel& channel); /** - * @brief Adds the provided @c AudioBufferChannel to this channel. + * @brief Performs point-wise addition of this channel with the provided `AudioBufferChannel`. * - * @param channel The @c AudioBufferChannel to add. + * @param[in] channel The `AudioBufferChannel` to add. * * @return A reference to the modified channel. */ AudioBufferChannel& operator+=(const AudioBufferChannel& channel); /** - * @brief Subtracts the provided @c AudioBufferChannel from this channel. + * @brief Performs point-wise subtraction of this channel with the provided `AudioBufferChannel`. * - * @param channel The @c AudioBufferChannel to subtract. + * @param[in] channel The `AudioBufferChannel` to subtract. * * @return A reference to the modified channel. */ AudioBufferChannel& operator-=(const AudioBufferChannel& channel); /** - * @brief Point-wise multiplies this channel with the provided @c AudioBufferChannel. + * @brief Point-wise multiplies this channel with the provided `AudioBufferChannel`. * - * @param channel The @c AudioBufferChannel to multiply with. + * @param[in] channel The `AudioBufferChannel` to multiply with. * * @return A reference to the modified channel. */ @@ -140,7 +144,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Point-wise multiplies this channel with the provided scalar. * - * @param scalar The scalar to multiply with. + * @param[in] scalar The scalar to multiply with. * * @return A reference to the modified channel. */ @@ -149,24 +153,60 @@ namespace SparkyStudios::Audio::Amplitude private: friend class AudioBuffer; + /** + * @brief Creates a new audio buffer channel from the provided memory range. + * + * @param[in] begin The beginning of the memory range storing the channel data. + * @param[in] numFrames The number of audio samples in the memory range. + * + * @internal + */ AudioBufferChannel(AmReal32* begin, AmSize numFrames); + /** + * @brief The beginning of the memory range storing the channel data. + * + * @internal + */ AmReal32* _begin; + + /** + * @brief The number of audio samples in the memory range. + * + * @internal + */ AmSize _frameCount; + + /** + * @brief Indicates whether the channel is enabled. + * + * @internal + */ bool _isEnabled; }; + /** + * @brief Represents an audio buffer containing multiple channels. + * + * An `AudioBuffer` is a de-interleaved memory storage used to store and manipulate audio data, + * such as audio samples or Ambisonics sound fields, in a flexible and efficient manner. Accessing + * a channel data will return an `AudioBufferChannel` object, which is a view to the memory range storing that channel. + * + * @see AudioBufferChannel + * + * @ingroup core + */ class AM_API_PUBLIC AudioBuffer { public: /** * @brief Copies the given number of frames from the source buffer to the destination buffer. * - * @param source The source buffer to copy. - * @param sourceOffset The offset in the source buffer. - * @param destination The destination buffer to copy to. - * @param destinationOffset The offset in the destination buffer. - * @param numFrames The number of frames to copy. + * @param[in] source The source buffer to copy. + * @param[in] sourceOffset The offset in the source buffer. + * @param[out] destination The destination buffer to copy to. + * @param[in] destinationOffset The offset in the destination buffer. + * @param[in] numFrames The number of frames to copy. */ static void Copy( const AudioBuffer& source, AmSize sourceOffset, AudioBuffer& destination, AmSize destinationOffset, AmSize numFrames); @@ -179,15 +219,15 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates an audio buffer with the specified number of frames and channels. * - * @param numFrames The number of frames in the buffer. - * @param numChannels The number of channels in the buffer. + * @param[in] numFrames The number of frames in the buffer. + * @param[in] numChannels The number of channels in the buffer. */ AudioBuffer(AmSize numFrames, AmSize numChannels); /** * @brief Explicitly deletes the audio buffer copy to avoid unintended usage. * - * @param buffer The other audio buffer to copy. + * @param[in] buffer The other audio buffer to copy. * * @note Use the assignment operator to copy the audio buffer. */ @@ -196,16 +236,19 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Moves the given audio buffer data in this one. * - * @param buffer The other audio buffer to move. + * @param[in] buffer The other audio buffer to move. */ AudioBuffer(AudioBuffer&& buffer) noexcept; + /** + * @brief Destroys the audio buffer data and release allocated memory. + */ ~AudioBuffer(); /** * @brief Check if the audio buffer is empty. * - * @return @c true if the audio buffer is empty, @c false otherwise. + * @return `true` if the audio buffer is empty, `false` otherwise. */ [[nodiscard]] bool IsEmpty() const; @@ -236,20 +279,20 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] const AmAlignedReal32Buffer& GetData() const; /** - * @brief Gets the @c AudioBufferChannel at the specified index. + * @brief Gets the `AudioBufferChannel` at the specified index. * - * @param index The channel index. + * @param[in] index The channel index. * - * @return The @c AudioBufferChannel at the specified index. + * @return The `AudioBufferChannel` at the specified index. */ AudioBufferChannel& GetChannel(AmSize index); /** - * @brief Gets the @c AudioBufferChannel at the specified index. + * @brief Gets the `AudioBufferChannel` at the specified index. * - * @param index The channel index. + * @param[in] index The channel index. * - * @return The @c AudioBufferChannel at the specified index. + * @return The `AudioBufferChannel` at the specified index. */ [[nodiscard]] const AudioBufferChannel& GetChannel(AmSize index) const; @@ -261,54 +304,54 @@ namespace SparkyStudios::Audio::Amplitude AudioBuffer Clone() const; /** - * @brief Gets the @c AudioBufferChannel at the specified index. + * @brief Gets the `AudioBufferChannel` at the specified index. * - * @param index The channel index. + * @param[in] index The channel index. * - * @return The @c AudioBufferChannel at the specified index. + * @return The `AudioBufferChannel` at the specified index. */ AudioBufferChannel& operator[](AmSize index); /** - * @brief Gets the @c AudioBufferChannel at the specified index. + * @brief Gets the `AudioBufferChannel` at the specified index. * - * @param index The channel index. + * @param[in] index The channel index. * - * @return The @c AudioBufferChannel at the specified index. + * @return The `AudioBufferChannel` at the specified index. */ [[nodiscard]] const AudioBufferChannel& operator[](AmSize index) const; /** - * @brief Copies the audio buffer data from the provided @c AudioBuffer. + * @brief Copies the audio buffer data from the provided `AudioBuffer`. * - * @param buffer The other audio buffer to copy. + * @param[in] buffer The other audio buffer to copy. * * @return This instance with the copied audio buffer data. */ AudioBuffer& operator=(const AudioBuffer& buffer); /** - * @brief Accumulates the audio buffer data from the provided @c AudioBuffer. + * @brief Accumulates the audio buffer data from the provided `AudioBuffer`. * - * @param buffer The buffer to add in this one. + * @param[in] buffer The buffer to add in this one. * * @return This instance with the added audio buffer data. */ AudioBuffer& operator+=(const AudioBuffer& buffer); /** - * @brief Subtracts the audio buffer data from the provided @c AudioBuffer. + * @brief Subtracts the audio buffer data from the provided `AudioBuffer`. * - * @param buffer The buffer to subtract from this one. + * @param[in] buffer The buffer to subtract from this one. * * @return This instance with the subtracted audio buffer data. */ AudioBuffer& operator-=(const AudioBuffer& buffer); /** - * @brief Point-wise multiplies the audio buffer data with the provided @c AudioBuffer. + * @brief Point-wise multiplies the audio buffer data with the provided `AudioBuffer`. * - * @param buffer The buffer to multiply with this one. + * @param[in] buffer The buffer to multiply with this one. * * @return This instance with the multiplied audio buffer data. */ @@ -317,18 +360,41 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Point-wise multiplies this channel with the provided scalar. * - * @param scalar The scalar to multiply with. + * @param[in] scalar The scalar to multiply with. * * @return A reference to the modified channel. */ AudioBuffer& operator*=(AmReal32 scalar); private: + /** + * @brief Initializes the audio buffer with the specified number of channels. + * + * @param[in] channelCount The number of channels in the buffer. + * + * @internal + */ void Initialize(AmSize channelCount); + /** + * @brief The number of audio samples in each channel. + * + * @internal + */ AmSize _frameCount; + + /** + * @brief The vector of available channels. + * + * @internal + */ std::vector _channels; + /** + * @brief The wrapped audio buffer data. + * + * @internal + */ AmAlignedReal32Buffer _data; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Codec.h b/include/SparkyStudios/Audio/Amplitude/Core/Codec.h index 288e1f73..473ccb37 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Codec.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Codec.h @@ -26,9 +26,11 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Audio file reader and writer. * - * The Codec class is used to implement an audio file reader and writer. + * The `Codec` class is used to implement an audio file reader and writer. * This is the base class for all audio codecs, each implementation should * allow to build decoders and encoders. + * + * @ingroup engine */ class AM_API_PUBLIC Codec { @@ -36,11 +38,12 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Audio file reader. * - * The Decoder is built by a Codec instance. It's used to read + * The `Decoder` is built by a `Codec` instance. It's used to read * an audio file and process its data. Each implementation should - * allow to load the entire file into memory or stream it from the file system. + * allow to @ref Load load the entire file into memory or @ref Stream stream + * it from the file system. * - * The Stream() method of a decoder implementation should be thread-safe. + * The @ref Stream `Stream()` method of a decoder implementation must be thread-safe. */ class AM_API_PUBLIC Decoder { @@ -48,25 +51,28 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new instance of the decoder for the given codec. * - * @param codec The codec wrapper for the decoder. + * @param[in] codec The codec wrapper for the decoder. */ explicit Decoder(const Codec* codec); + /** + * @brief Default destructor. + */ virtual ~Decoder() = default; /** * @brief Opens the given file to start decoding. * - * @param file The file to read. + * @param[in] file The file to read. * - * @return Whether the operation is successful. + * @return `true` if the file was opened successfully, `false` otherwise. */ virtual bool Open(std::shared_ptr file) = 0; /** - * @brief Closes the file previously opened. + * @brief Closes the previously opened file. * - * @return Whether is operation is successful. + * @return `true` if the file was closed successfully, `false` otherwise. */ virtual bool Close() = 0; @@ -74,6 +80,8 @@ namespace SparkyStudios::Audio::Amplitude * @brief Gets the audio sample format. * * @return The audio sample format. + * + * @see SoundFormat */ [[nodiscard]] const SoundFormat& GetFormat() const; @@ -83,7 +91,7 @@ namespace SparkyStudios::Audio::Amplitude * The output buffer must allocate enough size for this operation * to be successful. * - * @param out The buffer to load audio data data into. + * @param[out] out The buffer to load audio data data into. * * @return The number of audio frames loaded into the buffer. */ @@ -92,10 +100,10 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Streams a part of the file from disk into the output buffer. * - * @param out The buffer to stream the file data into. - * @param bufferOffset - * @param seekOffset The offset in frames from which start to read the file. - * @param length The length in frames to read from the file. + * @param[out] out The buffer to stream the file data into. + * @param[in] bufferOffset The offset in frames from which start to write in the `out` buffer. + * @param[in] seekOffset The offset in frames from which start to read the file. + * @param[in] length The length in frames to read from the file. * * @return The number of frames read. */ @@ -103,16 +111,16 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Moves the cursor to the given frame. - * @param offset The offset in frames to move the cursor to. * - * @return Whether the operation is successful. + * @param[in] offset The offset in frames to move the cursor to. + * + * @return `true` if the cursor was moved successfully, `false` otherwise. */ virtual bool Seek(AmUInt64 offset) = 0; protected: /** - * @brief The audio sample format of the file - * currently loaded by this decoder. + * @brief The audio sample format of the file currently loaded by this decoder. * * The sound format must be filled during the initialization * of this decoder. @@ -128,10 +136,10 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Audio file writer. * - * The Encoder is built by a Codec instance. It's used to write + * The `Encoder` is built by a `Codec` instance. It's used to write * data to an audio file. * - * The Write() methods of an encoder implementation should be thread safe. + * The @ref Write `Write()` methods of an encoder implementation must be thread safe. */ class AM_API_PUBLIC Encoder { @@ -139,41 +147,44 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new instance of the encoder for the given codec. * - * @param codec The codec wrapper for the encoder. + * @param[in] codec The codec wrapper for the encoder. */ explicit Encoder(const Codec* codec); + /** + * @brief Default destructor. + */ virtual ~Encoder() = default; /** * @brief Opens or create a file at the given path to start encoding. * - * @param file The file to write. + * @param[in] file The file to write. * - * @return Whether the operation is successful. + * @return `true` if the file was opened successfully, `false` otherwise. */ virtual bool Open(std::shared_ptr file) = 0; /** - * @brief Closes the opened file. + * @brief Closes a previously opened file. * - * @return Whether the operation is successful. + * @return `true` if the file was closed successfully, `false` otherwise. */ virtual bool Close() = 0; /** * @brief Sets the audio sample format. * - * @param format The audio sample format. + * @param[in] format The audio sample format. */ virtual void SetFormat(const SoundFormat& format); /** - * @brief Writes a the given buffer into the file. + * @brief Writes the given buffer into the file. * - * @param in The buffer to write into the the file. - * @param offset The offset in frames from which write the input buffer. - * @param length The length in frames to write from the input buffer. + * @param[in] in The buffer to write into the the file. + * @param[in] offset The offset in frames from which write the input buffer. + * @param[in] length The length in frames to write from the input buffer. * * @return The number of frames written. */ @@ -181,12 +192,12 @@ namespace SparkyStudios::Audio::Amplitude protected: /** - * @brief The audio sample format of the file - * to write using this encoder. + * @brief The audio sample format of the file to write using this encoder. + * + * The sound format must be set before the initialization of this encoder. Otherwise, + * the encoder initialization should fail. * - * The sound format must be set before the initialization - * of this encoder. Otherwise the encoder initialization will - * mostly fail. + * @note The final behavior depend on the specific codec implementation. */ SoundFormat m_format; @@ -204,45 +215,45 @@ namespace SparkyStudios::Audio::Amplitude */ explicit Codec(AmString name); + /** + * @brief Default destructor. + */ virtual ~Codec(); /** - * @brief Creates a new instance of the decoder associated - * to this codec. + * @brief Creates a new instance of the decoder associated to this codec. * - * @return A Decoder instance. + * @return A `Decoder` instance. */ [[nodiscard]] virtual Decoder* CreateDecoder() = 0; /** * @brief Destroys the decoder associated to this codec. * - * @param decoder The decoder instance to destroy. + * @param[in] decoder The decoder instance to destroy. */ virtual void DestroyDecoder(Decoder* decoder) = 0; /** - * @brief Creates a new instance of the encoder associated - * to this codec. + * @brief Creates a new instance of the encoder associated to this codec. * - * @return An Encoder instance. + * @return An `Encoder` instance. */ [[nodiscard]] virtual Encoder* CreateEncoder() = 0; /** * @brief Destroys the encoder associated to this codec. * - * @param encoder The encoder instance to destroy. + * @param[in] encoder The encoder instance to destroy. */ virtual void DestroyEncoder(Encoder* encoder) = 0; /** - * @brief Checks whether this Codec can handle the file at - * the given path. + * @brief Checks whether this `Codec` can handle the file at the given path. * - * @param file The file to check. + * @param[in] file The file to check. * - * @return Whether this Codec can handle the given file. + * @return `true` if the `Codec` can handle the file, `false` otherwise. */ [[nodiscard]] virtual bool CanHandleFile(std::shared_ptr file) const = 0; @@ -256,47 +267,50 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new audio codec. * - * @param codec The audio codec to add in the registry. + * @param[in] codec The audio codec to add in the registry. */ static void Register(Codec* codec); /** * @brief Unregisters a audio codec. * - * @param codec The audio codec to remove from the registry. + * @param[in] codec The audio codec to remove from the registry. */ static void Unregister(const Codec* codec); /** * @brief Look up a codec by name. * - * @return The codec with the given name, or NULL if none. + * @param[in] name The name of the codec to find. + * + * @return The codec with the given name, or `nullptr` if none. */ static Codec* Find(const AmString& name); /** * @brief Finds the codec which can handle the given file. * - * @param file The file to find the codec for. - * @return The codec which can handle the given file. + * @param[in] file The file to find the codec for. + * + * @return The codec which can handle the given file, or `nullptr` if none. */ static Codec* FindCodecForFile(std::shared_ptr file); /** * @brief Locks the codecs registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new codecs after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new codecs after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the codecs registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new codecs after the engine is fully unloaded. */ static void UnlockRegistry(); diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common.h b/include/SparkyStudios/Audio/Amplitude/Core/Common.h index 7b2f9043..69615357 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common.h @@ -17,9 +17,8 @@ #ifndef _AM_CORE_COMMON_H #define _AM_CORE_COMMON_H -///////////////////////////////////////////////////////////////////// -///////////////////////////////////////////////////////////////////// // Standard Library +// -------------------------------------------------------------- #include #include @@ -36,9 +35,8 @@ #include #include -///////////////////////////////////////////////////////////////////// -///////////////////////////////////////////////////////////////////// // Amplitude +// -------------------------------------------------------------- #include #include @@ -47,20 +45,51 @@ #include -///////////////////////////////////////////////////////////////////// -///////////////////////////////////////////////////////////////////// // Common defines +// -------------------------------------------------------------- -// Define an invalid object handle +/** + * @brief Define an invalid object handle. + * + * @ingroup engine + */ #define AM_INVALID_HANDLE nullptr -// Check for handle validity +/** + * @brief Checks if a handle is valid + * + * @param handle The handle to check + * + * @return @c true if the handle is valid, @c false otherwise. + * + * @ingroup engine + */ #define AM_IS_VALID_HANDLE(handle) ((handle) != AM_INVALID_HANDLE) -// Clamps a value between a and b +/** + * @brief Clamps a value between a and b. + * + * @param v The value to clamp + * @param a The minimum value + * @param b The maximum value + * + * @return The clamped value + * + * @ingroup math + */ #define AM_CLAMP(v, a, b) (((v) < (a)) ? (a) : ((v) > (b)) ? (b) : (v)) -// Checks if a value is between a and b +/** + * @brief Checks if a value is between a and b. + * + * @param v The value to check + * @param a The minimum value + * @param b The maximum value + * + * @return @c true if the value is between a and b, @c false otherwise. + * + * @ingroup math + */ #define AM_BETWEEN(v, a, b) ((v) >= AM_MIN(a, b) && (v) <= AM_MAX(a, b)) /** @@ -69,17 +98,23 @@ * @param _type_ Return type of the function * @param _name_ Name of the function * - * @remarks This must be followed by the parentheses containing the function arguments declaration + * @note This must be followed by the parentheses containing the function arguments declaration + * + * @ingroup core */ #define AM_CALLBACK(_type_, _name_) typedef _type_(AM_CALL_POLICY* _name_) /** * @brief The minimum value for an audio sample. + * + * @ingroup engine */ #define AM_AUDIO_SAMPLE_MIN (-1.0f) /** * @brief The maximum value for an audio sample. + * + * @ingroup engine */ #define AM_AUDIO_SAMPLE_MAX (+1.0f) @@ -87,6 +122,8 @@ * @brief Helps to avoid compiler warnings about unused values. * * @param x The statement where the return value is not used. + * + * @ingroup core */ #define AM_UNUSED(x) ((void)(x)) @@ -94,20 +131,29 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief Class that handles aligned allocations to support vectorized operations. + * + * @ingroup core */ class AM_API_PUBLIC AmAlignedReal32Buffer { public: + /** + * @brief Constructs an empty buffer. + */ AmAlignedReal32Buffer(); + + /** + * @brief Destructs the buffer and deallocates the memory. + */ ~AmAlignedReal32Buffer(); /** * @brief Allocates and align buffer. * - * @param size The buffer size. - * @param clear Whether to clear the buffer. + * @param[in] size The buffer size. + * @param[in] clear Whether to clear the buffer. * - * @return the result of the allocation. + * @returns An `AM_ERROR` value indicating if the allocation was successful or not. */ AmResult Init(AmUInt32 size, bool clear = true); @@ -124,7 +170,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the size of the buffer. * - * @return AmUInt32 + * @return The number of float values stored in the buffer. */ [[nodiscard]] AM_INLINE AmUInt32 GetSize() const { @@ -134,9 +180,9 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the current aligned pointer. * - * @return AmFloat32Buffer + * @return The pointer the float buffer */ - [[nodiscard]] AM_INLINE AmReal32Buffer GetBuffer() const + [[nodiscard]] AM_INLINE AmReal32* GetBuffer() const { return m_data; } @@ -144,7 +190,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the raw allocated pointer. * - * @return AmUInt8Buffer + * @return The pointer to the raw allocated memory. */ [[nodiscard]] AM_INLINE AmUInt8Buffer GetPointer() const { @@ -153,15 +199,16 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Copies data from another buffer. - * @param other The other buffer to copy data from. + * + * @param[in] other The other buffer to copy data from. */ void CopyFrom(const AmAlignedReal32Buffer& other) const; /** * @brief Resizes the buffer to the specified size. * - * @param size The new size of the buffer. - * @param clear Whether to clear the buffer after resize. If @c true, the buffer will be cleared + * @param[in] size The new size of the buffer. + * @param[in] clear Whether to clear the buffer after resize. If `true`, the buffer will be cleared * even if the new size equals the old size. */ void Resize(AmUInt32 size, bool clear = true); @@ -169,17 +216,31 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Swaps two buffers. * - * @param a The first buffer. - * @param b The second buffer. + * @param[in,out] a The first buffer. + * @param[in,out] b The second buffer. */ static void Swap(AmAlignedReal32Buffer& a, AmAlignedReal32Buffer& b); + /** + * @brief Returns a reference to the float at the specified index. + * + * @param[in] index The index of the float to retrieve. + * + * @return The reference to the float at the specified index. + */ AmReal32& operator[](AmSize index) { AMPLITUDE_ASSERT(m_data != nullptr && index < m_floats); return m_data[index]; } + /** + * @brief Returns a const reference to the float at the specified index. + * + * @param[in] index The index of the float to retrieve. + * + * @return The const reference to the float at the specified index. + */ const AmReal32& operator[](AmSize index) const { AMPLITUDE_ASSERT(m_data != nullptr && index < m_floats); @@ -187,78 +248,44 @@ namespace SparkyStudios::Audio::Amplitude } private: - AmReal32Buffer m_data; // aligned pointer + AmReal32* m_data; // aligned pointer AmUInt8Buffer m_basePtr; // raw allocated pointer (for delete) AmUInt32 m_floats; // size of buffer (w/out padding) }; - /** - * @brief Lightweight class that handles small aligned buffer to support vectorized operations. - */ - class AM_API_PUBLIC AmTinyAlignedReal32Buffer - { - public: - /** - * @brief Construct a new TinyAlignedReal32Buffer object by allocating an aligned - * buffer with AM_SIMD_ALIGNMENT float values. - */ - AmTinyAlignedReal32Buffer(); - - /** - * @brief Gets the raw allocated pointer. - * - * @return AmReal32Buffer - */ - [[nodiscard]] AM_INLINE AmReal32Buffer GetBuffer() const - { - return m_data; - } - - private: - AmReal32Buffer m_data; // aligned pointer - AmUInt8 m_actualData[sizeof(AmReal32) * AM_SIMD_ALIGNMENT + AM_SIMD_ALIGNMENT]{}; - }; - /** * @brief Enumerates the list of possible errors encountered by the library. + * + * @ingroup core */ - enum AM_ERROR : AmUInt8 + enum eErrorCode : AmUInt8 { - AM_ERROR_NO_ERROR = 0, // No error - AM_ERROR_INVALID_PARAMETER = 1, // Some parameter is invalid - AM_ERROR_FILE_NOT_FOUND = 2, // File not found - AM_ERROR_FILE_LOAD_FAILED = 3, // File found, but could not be loaded - AM_ERROR_DLL_NOT_FOUND = 4, // DLL not found, or wrong DLL - AM_ERROR_OUT_OF_MEMORY = 5, // Out of memory - AM_ERROR_NOT_IMPLEMENTED = 6, // Feature not implemented - AM_ERROR_UNKNOWN = 7 // Other error + eErrorCode_Success = 0, ///< No error + eErrorCode_InvalidParameter = 1, ///< Some parameter is invalid + eErrorCode_FileNotFound = 2, ///< File not found + eErrorCode_FileLoadFailed = 3, ///< File found, but could not be loaded + eErrorCode_DllNotFound = 4, ///< DLL not found, or wrong DLL + eErrorCode_OutOfMemory = 5, ///< Out of memory + eErrorCode_NotImplemented = 6, ///< Feature not implemented + eErrorCode_Unknown = 7 ///< Unknown error }; /** * @brief Enumerates the list of possible sample formats handled by Amplitude. + * + * @ingroup core */ - enum AM_SAMPLE_FORMAT : AmUInt8 - { - // floating point (float32) - AM_SAMPLE_FORMAT_FLOAT, - // integer (int16) - AM_SAMPLE_FORMAT_INT, - // An unknown format - AM_SAMPLE_FORMAT_UNKNOWN, - }; - - /** - * @brief Enumerates the list of states in a fader. - */ - enum AM_FADER_STATE : AmInt8 + enum eAudioSampleFormat : AmUInt8 { - AM_FADER_STATE_STOPPED = -1, - AM_FADER_STATE_DISABLED = 0, - AM_FADER_STATE_ACTIVE = 1, + eAudioSampleFormat_Float32, ///< 32-bit floating-point sample + eAudioSampleFormat_Int16, //< 16-bit signed integer sample + eAudioSampleFormat_Unknown, ///< An unknown or unsupported format }; /** * @brief Enumerates the list of available spatialization modes. + * + * @ingroup core */ enum eSpatialization : AmUInt8 { @@ -275,10 +302,10 @@ namespace SparkyStudios::Audio::Amplitude eSpatialization_Position, /** - * @brief Enables 2D (left-right) spatialization based on sound position - * and orientation. + * @brief Enables 2D (left-right) spatialization based on sound position and orientation. + * + * @note The sound instance using this spatialization mode needs to be attached to an `Entity`. * - * @note The sound instance using this spatialization mode needs to be attached to an @c Entity. * @note This mode is available for every panning mode. */ eSpatialization_PositionOrientation, @@ -293,6 +320,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Enumerates the list of available panning modes. + * + * @ingroup core */ enum ePanningMode : AmUInt8 { @@ -300,7 +329,7 @@ namespace SparkyStudios::Audio::Amplitude * @brief 2D stereo panning. This panning mode won't provide HRTF-related features. * * @note The Ambisonic decoder will use a virtual array of 2 loudspeakers - * evenly arranged in front of the listener's head. + * evenly arranged in front of the listener. */ ePanningMode_Stereo = 0, @@ -308,7 +337,7 @@ namespace SparkyStudios::Audio::Amplitude * @brief 3D binaural panning using first-order HRTF. * * @note The Ambisonic decoder will use a virtual array of 8 loudspeakers - * arranged in a cube configuration around the listener's head. + * arranged in a cube configuration around the listener. */ ePanningMode_BinauralLowQuality = 1, @@ -352,24 +381,35 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Describe the format of an audio sample. * - * This data structure is mainly filled by a Codec - * during the initialization time. + * This data structure is mainly filled by a `Codec` during the initialization time. + * + * @ingroup core */ struct AM_API_PUBLIC SoundFormat { public: + /** + * @brief Sets all the properties of the sound format. + * + * @param[in] sampleRate The sample rate of the audio. + * @param[in] numChannels The number of audio channels. + * @param[in] bitsPerSample The number of bits per sample. + * @param[in] framesCount The total number of audio frames. + * @param[in] frameSize The size of each audio frame in bytes. + * @param[in] sampleType The type of audio sample. + */ void SetAll( AmUInt32 sampleRate, AmUInt16 numChannels, AmUInt32 bitsPerSample, AmUInt64 framesCount, AmUInt32 frameSize, - AM_SAMPLE_FORMAT sampleType); + eAudioSampleFormat sampleType); /** * @brief Get the sample rate. * - * @return AmUInt32 + * @return The sample rate of the audio. */ [[nodiscard]] AM_INLINE AmUInt32 GetSampleRate() const { @@ -379,7 +419,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the number of channels. * - * @return AmUInt16 + * @return The number of audio channels. */ [[nodiscard]] AM_INLINE AmUInt16 GetNumChannels() const { @@ -389,7 +429,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the bits per sample. * - * @return AmUInt32 + * @return The number of bits per sample. */ [[nodiscard]] AM_INLINE AmUInt32 GetBitsPerSample() const { @@ -399,7 +439,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the number of frames. * - * @return AmUInt64 + * @return The total number of audio frames. */ [[nodiscard]] AM_INLINE AmUInt64 GetFramesCount() const { @@ -409,7 +449,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the frame size. * - * @return AmUInt32 + * @return The size of each audio frame in bytes. */ [[nodiscard]] AM_INLINE AmUInt32 GetFrameSize() const { @@ -419,9 +459,9 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the sample type. * - * @return AM_SAMPLE_FORMAT + * @return The type of audio sample. */ - [[nodiscard]] AM_INLINE AM_SAMPLE_FORMAT GetSampleType() const + [[nodiscard]] AM_INLINE eAudioSampleFormat GetSampleType() const { return _sampleType; } @@ -432,7 +472,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 _bitsPerSample = 0; AmUInt64 _framesCount = 0; AmUInt32 _frameSize = 0; - AM_SAMPLE_FORMAT _sampleType = AM_SAMPLE_FORMAT_FLOAT; + eAudioSampleFormat _sampleType = eAudioSampleFormat_Float32; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common/Config.h b/include/SparkyStudios/Audio/Amplitude/Core/Common/Config.h index fffb0ed5..af8289a7 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common/Config.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common/Config.h @@ -83,19 +83,15 @@ #define MA_NO_SSE2 #endif // AMPLITUDE_DISABLE_SIMD -// Define the value of Pi if the platform doesn't do that #ifndef M_PI +/// Define the value of Pi if the platform doesn't do that #define M_PI 3.14159265358979323846264f // from CRC #endif -///////////////////////////////////////////////////////////////////// -///////////////////////////////////////////////////////////////////// // Configuration defines +// -------------------------------------------------------------- -// Maximum number of filters per stream -#define AM_FILTERS_PER_STREAM 8 - -// Maximum number of tasks in a single pool +/// Maximum number of tasks in a single pool #define AM_MAX_THREAD_POOL_TASKS 1024 #endif // _AM_CORE_COMMON_CONFIG_H diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Config.h b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Config.h index 7de54767..d34c3676 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Config.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Android/Config.h @@ -17,7 +17,7 @@ #ifndef _AM_CORE_COMMON_PLATFORMS_ANDROID_CONFIG_H #define _AM_CORE_COMMON_PLATFORMS_ANDROID_CONFIG_H -// Enable Android Compilation +/// Compiling for an Android platform #define AM_ANDROID_VERSION // Detect the platform CPU type diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Apple/Config.h b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Apple/Config.h index de6da5a2..9efd0d46 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Apple/Config.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Apple/Config.h @@ -19,12 +19,15 @@ #include -#define AM_APPLE_VERSION ///< Compiling for an Apple platform +/// Compiling for an Apple platform +#define AM_APPLE_VERSION #if TARGET_OS_IPHONE || TARGET_OS_TV -#define AM_IOS_VERSION ///< Compiling for iOS or tvOS (iPhone, iPad, iPod, Apple TV...) +/// Compiling for iOS or tvOS (iPhone, iPad, iPod, Apple TV...) +#define AM_IOS_VERSION #elif !TARGET_OS_EMBEDDED -#define AM_OSX_VERSION ///< Compiling for Mac OS X +/// Compiling for Mac OS X +#define AM_OSX_VERSION #endif // Detect the platform CPU type @@ -50,7 +53,7 @@ #include #ifndef AM_ID_CHAR_FMT -// Defines the format used to print AmObjectId value +/// Defines the format used to print AmObjectId value #define AM_ID_CHAR_FMT "%llu" #endif diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Linux/Config.h b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Linux/Config.h index b56557f6..f43fa3be 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Linux/Config.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/Linux/Config.h @@ -17,7 +17,7 @@ #ifndef _AM_CORE_COMMON_PLATFORMS_LINUX_CONFIG_H #define _AM_CORE_COMMON_PLATFORMS_LINUX_CONFIG_H -// Enable Android Compilation +/// Compiling for a Linux platform #define AM_LINUX_VERSION // Detect the platform CPU type @@ -40,7 +40,7 @@ #include #ifndef AM_ID_CHAR_FMT -// Defines the format used to print AmObjectId value +/// Defines the format used to print AmObjectId value #define AM_ID_CHAR_FMT "%lu" #endif diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/UNIX/Config.h b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/UNIX/Config.h index bd516945..f607de63 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/UNIX/Config.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Common/Platforms/UNIX/Config.h @@ -17,7 +17,7 @@ #ifndef _AM_CORE_COMMON_PLATFORMS_UNIX_CONFIG_H #define _AM_CORE_COMMON_PLATFORMS_UNIX_CONFIG_H -// Call policy +/// Call policy #define AM_CALL_POLICY // Library export policy @@ -79,13 +79,13 @@ static AM_INLINE std::string am_wstring_narrow(const std::wstring& str) #define AM_OS_STRING_TO_STRING(s) am_wstring_narrow(s).c_str() #define AM_STRING_TO_OS_STRING(s) am_string_widen(s).c_str() #else -// Defines the format used to print AmOsString text +/// Defines the format used to print AmOsString text #define AM_OS_CHAR_FMT "%s" -// Macro used to convert a string literal to an AmOsString string at compile-time +/// Macro used to convert a string literal to an AmOsString string at compile-time #define AM_OS_STRING(s) s -// Conversion between OS strings and default strings +/// Conversion between OS strings and default strings #define AM_OS_STRING_TO_STRING(s) std::string(s).c_str() #define AM_STRING_TO_OS_STRING(s) std::string(s).c_str() #endif diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Device.h b/include/SparkyStudios/Audio/Amplitude/Core/Device.h index 865037de..ec2cfc64 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Device.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Device.h @@ -25,6 +25,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The playback output format of the device. + * + * @ingroup engine */ enum class PlaybackOutputFormat : AmUInt16 { @@ -36,38 +38,35 @@ namespace SparkyStudios::Audio::Amplitude Default = 0, /** - * @brief Send audio samples as unsigned 8-bit integers - * to the device. + * @brief Send audio samples as unsigned 8-bit integers to the device. */ UInt8 = 1, /** - * @brief Send audio samples as signed 16-bit integers - * to the device. + * @brief Send audio samples as signed 16-bit integers to the device. */ Int16 = 2, /** - * @brief Send audio samples as signed 24-bit integers - * to the device. + * @brief Send audio samples as signed 24-bit integers to the device. */ Int24 = 3, /** - * @brief Send audio samples as signed 32-bit integers - * to the device. + * @brief Send audio samples as signed 32-bit integers to the device. */ Int32 = 4, /** - * @brief Send audio samples as 32-bit floating point values - * to the device. + * @brief Send audio samples as 32-bit floating point values to the device. */ Float32 = 5 }; /** * @brief The playback output channel layout of the device. + * + * @ingroup engine */ enum class PlaybackOutputChannels : AmUInt16 { @@ -106,6 +105,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The device state. + * + * @ingroup engine */ enum class DeviceState : AmUInt8 { @@ -137,6 +138,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The possible device notification types. + * + * @ingroup engine */ enum class DeviceNotification : AmUInt8 { @@ -151,7 +154,7 @@ namespace SparkyStudios::Audio::Amplitude Started, /** - * @brief The device is paused. + * @brief The device has changed. */ Rerouted, @@ -174,6 +177,8 @@ namespace SparkyStudios::Audio::Amplitude * * The device settings are filled after the Amplimix initialization, * and are provided by the selected Driver. + * + * @ingroup engine */ struct DeviceDescription { @@ -231,25 +236,31 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The device notification callback. * - * @param notification The notification type. - * @param device The device description. - * @param driver The driver which triggered the device notification. + * @param[in] notification The notification type. + * @param[in] device The device description. + * @param[in] driver The driver which triggered the device notification. + * + * @ingroup engine */ AM_CALLBACK(void, DeviceNotificationCallback)(DeviceNotification notification, const DeviceDescription& device, Driver* driver); /** * @brief Registers a callback to listen to device state changes. * - * @param callback The callback to register. + * @param[in] callback The callback to register. + * + * @ingroup engine */ AM_API_PUBLIC void RegisterDeviceNotificationCallback(DeviceNotificationCallback callback); /** * @brief Calls the registered device notification callback. * - * @param notification The notification type. - * @param device The device description. - * @param driver The driver which triggered the device notification. + * @param[in] notification The notification type. + * @param[in] device The device description. + * @param[in] driver The driver which triggered the device notification. + * + * @ingroup engine */ AM_API_PUBLIC void CallDeviceNotificationCallback(DeviceNotification notification, const DeviceDescription& device, Driver* driver); } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Driver.h b/include/SparkyStudios/Audio/Amplitude/Core/Driver.h index a10c0c3b..5047c801 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Driver.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Driver.h @@ -27,6 +27,8 @@ namespace SparkyStudios::Audio::Amplitude * * A driver allows to use an audio device to output sounds and * receive data from the microphone. + * + * @ingroup engine */ class AM_API_PUBLIC Driver { @@ -34,32 +36,38 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new AudioDriver with an unique name. * - * @param name The driver name. Recommended names are "APIName". + * @param[in] name The driver name. Recommended names are "APIName". * eg. "MiniAudio" or "PortAudio" or "SDL", etc... */ explicit Driver(AmString name); + /** + * @brief Default destructor. + */ virtual ~Driver(); /** * @brief Open and start using the audio device. * - * @param device The audio device to use description to use for - * initializing the physical device. + * @param[in] device The audio device to use description to use for initializing the physical device. + * + * @return `true` if successful, `false` otherwise. */ virtual bool Open(const DeviceDescription& device) = 0; /** * @brief Closes the audio device. + * + * @return `true` if successful, `false` otherwise. */ virtual bool Close() = 0; /** * @brief Enumerates all the available audio devices. * - * @param devices The vector in which to store the device descriptions. + * @param[out] devices The vector in which to store the device descriptions. * - * @return @c true if successful, @c false otherwise. + * @return `true` if successful, `false` otherwise. */ virtual bool EnumerateDevices(std::vector& devices) = 0; @@ -80,14 +88,14 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new audio driver. * - * @param driver The audio driver to add in the registry. + * @param[in] driver The audio driver to add in the registry. */ static void Register(Driver* driver); /** * @brief Unregisters an audio driver. * - * @param driver The audio driver to remove from the registry. + * @param[in] driver The audio driver to remove from the registry. */ static void Unregister(const Driver* driver); @@ -101,32 +109,34 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Look up a driver by name. * - * @return The audio driver with the given name, or NULL if none. + * @param[in] name The name of the audio driver. Must be registered before. + * + * @return The audio driver with the given name, or `nullptr` if none. */ static Driver* Find(const AmString& name); /** * @brief Set the default diver to use in the engine. * - * @param name The name of the audio driver. Must be registered before. + * @param[in] name The name of the audio driver. Must be registered before. */ static void SetDefault(const AmString& name); /** * @brief Locks the drivers registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new divers after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new divers after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the drivers registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new divers after the engine is fully unloaded. */ static void UnlockRegistry(); diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Engine.h b/include/SparkyStudios/Audio/Amplitude/Core/Engine.h index bbbb9c78..ef15e674 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Engine.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Engine.h @@ -50,6 +50,8 @@ /** * @brief Macro to get the current Amplitude engine instance. + * + * @ingroup engine */ #define amEngine SparkyStudios::Audio::Amplitude::Engine::GetInstance() @@ -69,8 +71,22 @@ namespace SparkyStudios::Audio::Amplitude typedef Effect* EffectHandle; /** - * @brief The central class of the library that manages the Listeners, Entities, - * Sounds, Collections, Channels, and tracks all of the internal state. + * @brief The Amplitude Engine. + * + * This is the main class of the library that manages all the entities + * and provides methods to create, destroy, and manipulate them. You can also + * access to the internal state of the engine through the public API. + * + * The `Engine` is a singleton class and you can access it using the `amEngine` macro. Before + * using most of the methods of the engine, you need to [initialize the + * engine](../../../integration/initializing-the-engine.md) first, for example: + * ```cpp + * amEngine->Initialize("config.amconfig"); + * //... + * amEngine->Deinitialize(); + * ``` + * + * @ingroup engine */ class AM_API_PUBLIC Engine { @@ -84,7 +100,7 @@ namespace SparkyStudios::Audio::Amplitude * * @return The version string structure */ - [[nodiscard]] virtual const struct Version* Version() const = 0; + [[nodiscard]] virtual const Version* Version() const = 0; #pragma endregion @@ -93,23 +109,23 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Initializes the Amplitude engine. * - * @param configFile The path to the configuration file. + * @param[in] configFile The path to the configuration file. * - * @return Whether the engine has been successfully initialized. + * @return `true` when the engine has been successfully initialized, `false` otherwise. */ virtual bool Initialize(const AmOsString& configFile) = 0; /** * @brief Deinitializes the Amplitude engine. * - * @return @c true when the engine has been successfully deinitialized, @c false otherwise. + * @return `true` when the engine has been successfully deinitialized, `false` otherwise. */ virtual bool Deinitialize() = 0; /** * @brief Checks if the Amplitude engine has been successfully initialized. * - * @return @c true if the engine has been successfully initialized, @c false otherwise. + * @return `true` if the engine has been successfully initialized, `false` otherwise. */ [[nodiscard]] virtual bool IsInitialized() const = 0; @@ -118,16 +134,17 @@ namespace SparkyStudios::Audio::Amplitude #pragma region FileSystem Management /** - * @brief Set a file system implementation to be used by the engine. + * @brief Sets a file system implementation to be used by the engine. * - * @param fs The file system implementation. + * @param[in] fs The file system implementation. */ virtual void SetFileSystem(FileSystem* fs) = 0; /** * @brief Gets the file system implementation used by the engine. * - * @return The file system implementation used by the engine. + * @return The current file system implementation used by the engine, + * or `nullptr` if no file system has been set. */ [[nodiscard]] virtual const FileSystem* GetFileSystem() const = 0; @@ -137,8 +154,24 @@ namespace SparkyStudios::Audio::Amplitude virtual void StartOpenFileSystem() = 0; /** - * @brief Returns @c true if the file system has been fully loaded. Must call - * @c Engine::StartOpenFileSystem() first. + * @brief Checks if the file system has been fully loaded. + * + * This method is helpful when the file system implementation is loaded asynchronously. You + * can use this method to wait until the file system is fully loaded before using it. + * + * @example + * ```cpp + * // Open the file system + * amEngine->StartOpenFileSystem(); + * while (!amEngine->TryFinalizeOpenFileSystem()) { + * // Wait until the file system is fully loaded + * Thread::Sleep(100); + * } + * // Use the file system now + * //... + * ``` + * + * @return `true` if the file system has been fully loaded, `false` otherwise. */ virtual bool TryFinalizeOpenFileSystem() = 0; @@ -148,8 +181,24 @@ namespace SparkyStudios::Audio::Amplitude virtual void StartCloseFileSystem() = 0; /** - * @brief Return @c true if the file system has been fully closed. Must call - * @c Engine::StartCloseFileSystem() first. + * @brief Checks if the file system has been fully closed. + * + * This method is helpful when the file system implementation is closed asynchronously. You + * can use this method to wait until the file system is fully closed. + * + * @example + * ```cpp + * // Close the file system + * amEngine->StartCloseFileSystem(); + * while (!amEngine->TryFinalizeCloseFileSystem()) { + * // Wait until the file system is fully closed + * Thread::Sleep(100); + * } + * // The file system is now closed + * //... + * ``` + * + * @return `true` if the file system has been fully closed, `false` otherwise. */ virtual bool TryFinalizeCloseFileSystem() = 0; @@ -160,14 +209,17 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Updates the engine state for the given number of milliseconds. * - * @param delta The number of milliseconds since the last frame. + * @param[in] delta The number of milliseconds since the last frame. */ virtual void AdvanceFrame(AmTime delta) const = 0; /** * @brief Executes the given callback on the next frame. * - * @param callback The callback to be called when the next frame is ready. + * @note The given callback will be executed at the *beginning* of the next frame, + * before doing the actual frame update. + * + * @param[in] callback The callback to be called when the next frame is ready. */ virtual void OnNextFrame(std::function callback) const = 0; @@ -180,90 +232,118 @@ namespace SparkyStudios::Audio::Amplitude #pragma endregion -#pragma region SoundBank Management +#pragma region Sound Bank Management /** - * @brief Loads a sound bank from a file. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from a binary asset file (`.ambank`). * - * @param filename The path to the sound bank file. + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @param[in] filename The path to the sound bank asset file. + * + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ virtual bool LoadSoundBank(const AmOsString& filename) = 0; /** - * @brief Loads a sound bank from a file. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from a binary asset file (`.ambank`). + * + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. * - * @param filename The path to the sound bank file. - * @param outID The ID of the loaded sound bank. + * @param[in] filename The path to the sound bank asset file. + * @param[out] outID The ID of the loaded sound bank. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ virtual bool LoadSoundBank(const AmOsString& filename, AmBankID& outID) = 0; /** - * @brief Loads a sound bank from memory. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from memory. + * + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. + * + * @param[in] fileData The sound bank data to be loaded. * - * @param fileData The sound bank data to be loaded. + * @note The `fileData` pointer should be null terminated. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @warning The `fileData` pointer should remain valid until the sound bank is unloaded. + * + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ virtual bool LoadSoundBankFromMemory(const char* fileData) = 0; /** - * @brief Loads a sound bank from memory. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from memory. + * + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. + * + * @param[in] fileData The sound bank data to be loaded. + * @param[out] outID The ID of the loaded sound bank. * - * @param fileData The sound bank data to be loaded. - * @param outID The ID of the loaded sound bank. + * @note The `fileData` pointer should be null terminated. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @warning The `fileData` pointer should remain valid until the sound bank is unloaded. + * + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ virtual bool LoadSoundBankFromMemory(const char* fileData, AmBankID& outID) = 0; /** - * @brief Loads a sound bank from memory. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from memory. + * + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. + * + * @param[in] ptr The pointer to the sound bank data to be loaded. + * @param[in] size The size of the memory to read. + * + * @note The `fileData` pointer should be null terminated. * - * @param ptr The pointer to the sound bank data to be loaded. - * @param size The size of the memory to read. + * @warning The `fileData` pointer should remain valid until the sound bank is unloaded. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ - virtual bool LoadSoundBankFromMemoryView(void* ptr, AmSize size) = 0; + virtual bool LoadSoundBankFromMemoryView(AmVoidPtr ptr, AmSize size) = 0; /** - * @brief Loads a sound bank from memory. Queue the sound files in that sound - * bank for loading. Call @c Engine::StartLoadSoundFiles() to trigger loading - * of the sound files on a separate thread. + * @brief Loads a sound bank from memory. + * + * This method queues the sound files in that sound bank for loading. Call + * @ref StartLoadSoundFiles `StartLoadSoundFiles()` to trigger the loading + * of sound files on a separate thread. + * + * @param[in] ptr The pointer to the sound bank data to be loaded. + * @param[in] size The size of the memory to read. + * @param[out] outID The ID of the loaded sound bank. + * + * @note The `ptr` pointer should be null terminated. * - * @param ptr The pointer to the sound bank data to be loaded. - * @param size The size of the memory to read. - * @param outID The ID of the loaded sound bank. + * @warning The `ptr` pointer should remain valid until the sound bank is unloaded. * - * @return @c true when the sound bank is successfully loaded, @c false otherwise. + * @return `true` when the sound bank is successfully loaded, `false` otherwise. */ - virtual bool LoadSoundBankFromMemoryView(void* ptr, AmSize size, AmBankID& outID) = 0; + virtual bool LoadSoundBankFromMemoryView(AmVoidPtr ptr, AmSize size, AmBankID& outID) = 0; /** - * @brief Unloads a sound bank. + * @brief Unloads a sound bank given its filename. * - * @param filename The file to unload. + * @param[in] filename The file to unload. */ virtual void UnloadSoundBank(const AmOsString& filename) = 0; /** - * @brief Unloads a sound bank. + * @brief Unloads a sound bank given its ID. * - * @param id The sound bank id to unload. + * @param[in] id The sound bank id to unload. */ virtual void UnloadSoundBank(AmBankID id) = 0; @@ -275,15 +355,28 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Starts the loading of sound files referenced in loaded sound banks. * - * This process will run in another thread. You must call @c Engine::TryFinalizeLoadSoundFiles() to - * know when the loading has completed, and to release used resources. + * This process will run in another thread. You must call @ref TryFinalizeLoadSoundFiles `TryFinalizeLoadSoundFiles()` to + * know when the loading has completed, and to automaticaly release used resources. */ virtual void StartLoadSoundFiles() = 0; /** * @brief Checks if the loading of sound files has been completed, and releases used resources. * - * @return @c true when the sound files have been successfully loaded, @c false otherwise. + * @note This method should be called after calling @ref StartLoadSoundFiles `StartLoadSoundFiles()`. + * + * @example + * ```cpp + * // Start loading sound files + * amEngine->StartLoadSoundFiles(); + * while (!amEngine->TryFinalizeLoadSoundFiles()) { + * // Wait for loading to complete + * Thread::Sleep(100); + * } + * // Sound files have been loaded, and used resources has been released + * ``` + * + * @return `true` when the sound files have been successfully loaded, `false` otherwise. */ virtual bool TryFinalizeLoadSoundFiles() = 0; @@ -292,213 +385,382 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Handles /** - * @brief Gets a @c SwitchContainerHandle given its name as defined in its JSON data. + * @brief Gets a `SwitchContainerHandle` given its name as defined in its asset file (`.amswitchcontainer`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `SwitchContainerHandle` for the given name, or an invalid handle if no switch container + * with that name was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandle(const AmString& name) const = 0; /** - * @brief Gets a @C SwitchContainerHandle given its ID as defined in its JSON data. + * @brief Gets a `SwitchContainerHandle` given its ID as defined in its asset file (`.amswitchcontainer`). * - * @param id The unique ID as defined in the JSON data. + * @param[in] id The unique ID as defined in the asset file. + * + * @return The `SwitchContainerHandle` for the given ID, or an invalid handle if no switch container + * with that ID was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandle(AmSwitchContainerID id) const = 0; /** - * @brief Gets a @c SwitchContainerHandle given its definition file's name. + * @brief Gets a `SwitchContainerHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `switch_containers` directory of your Amplitude + * project, not an absolute path from the filesystem base path. * - * @param filename The filename containing the flatbuffer binary data. + * @example + * ```cpp + * // Assuming the asset file is located in "switch_containers/footsteps.amswitchcontainer" + * SwitchContainerHandle handle = amEngine->GetSwitchContainerHandleFromFile("footsteps.amswitchcontainer"); + * ``` + * + * @return The `SwitchContainerHandle` for the given asset's filename, or an invalid handle if no switch container + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchContainerHandle GetSwitchContainerHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets a @c CollectionHandle given its name as defined in its JSON data. + * @brief Gets a `CollectionHandle` given its name as defined in its asset file (`.amcollection`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `CollectionHandle` for the given name, or an invalid handle if no collection + * with that name was found in any loaded sound bank. */ [[nodiscard]] virtual CollectionHandle GetCollectionHandle(const AmString& name) const = 0; /** - * @brief Gets a @c CollectionHandle given its ID as defined in its JSON data. + * @brief Gets a `CollectionHandle` given its ID as defined in its asset file (`.amcollection`). * - * @param id The unique ID as defined in the JSON data. + * @param[in] id The unique ID as defined in the asset file. + * + * @return The `CollectionHandle` for the given ID, or an invalid handle if no collection + * with that ID was found in any loaded sound bank. */ [[nodiscard]] virtual CollectionHandle GetCollectionHandle(AmCollectionID id) const = 0; /** - * @brief Gets a @c CollectionHandle given its definition file's name. + * @brief Gets a `CollectionHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. * - * @param filename The filename containing the flatbuffer binary data. + * @note The asset's filename should be relative path from the `collections` directory of your Amplitude + * project, not an absolute path from the filesystem base path. + * + * @example + * ```cpp + * // Assuming the asset file is located in "collections/weapons/ak47_gunfires.amcollection" + * CollectionHandle handle = amEngine->GetCollectionHandleFromFile("weapons/ak47_gunfires.amcollection"); + * ``` + * + * @return The `CollectionHandle` for the given asset's filename, or an invalid handle if no collection + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual CollectionHandle GetCollectionHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets a @c SoundHandle given its name as defined in its JSON data. + * @brief Gets a `SoundHandle` given its name as defined in its asset file (`.amsound`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `SoundHandle` for the given name, or an invalid handle if no sound with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual SoundHandle GetSoundHandle(const AmString& name) const = 0; /** - * @brief Gets a @c SoundHandle given its ID as defined in its JSON data. + * @brief Gets a `SoundHandle` given its ID as defined in its asset file (`.amsound`). * - * @param id The unique ID as defined in the JSON data. + * @param[in] id The unique ID as defined in the asset file. + * + * @return The `SoundHandle` for the given ID, or an invalid handle if no sound with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual SoundHandle GetSoundHandle(AmSoundID id) const = 0; /** - * @brief Gets a @c SoundHandle given its defintion file's name. + * @brief Gets a `SoundHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `sounds` directory of your Amplitude + * project, not an absolute path from the filesystem base path. * - * @param filename The filename containing the flatbuffer binary data. + * @example + * ```cpp + * // Assuming the asset file is located in "sounds/env/forest/calm_lake_bg.amsound" + * SoundHandle handle = amEngine->GetSoundHandleFromFile("env/forest/calm_lake_bg.amsound"); + * ``` + * + * @return The `SoundHandle` for the given asset's filename, or an invalid handle if no sound + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual SoundHandle GetSoundHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets a @c SoundObjectHandle given its name as defined in its JSON data. + * @brief Gets a `SoundObjectHandle` given its name as defined in its asset file. + * + * @param[in] name The unique name as defined in the asset file. * - * Can be a @c SwitchContainerHandle, a @c CollectionHandle, or a @c SoundHandle. + * @return The `SoundObjectHandle` for the given name, or an invalid handle if no sound object + * with that name was found in any loaded sound bank. * - * @param name The unique name as defined in the JSON data. + * @note The return value can be a `SwitchContainerHandle`, a `CollectionHandle`, or a `SoundHandle`. */ [[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandle(const AmString& name) const = 0; /** - * @brief Gets a @c SoundObjectHandle given its ID as defined in its JSON data. + * @brief Gets a `SoundObjectHandle` given its ID as defined in its asset file. + * + * @param[in] id The unique ID as defined in the asset file. * - * Can be a @c SwitchContainerHandle, a @c CollectionHandle, or a @c SoundHandle. + * @return The `SoundObjectHandle` for the given ID, or an invalid handle if no sound object + * with that ID was found in any loaded sound bank. * - * @param id The unique ID as defined in the JSON data. + * @note The return value can be a `SwitchContainerHandle`, a `CollectionHandle`, or a `SoundHandle`. */ [[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandle(AmSoundID id) const = 0; /** - * @brief Gets a @c SoundObjectHandle given its definition file's name. + * @brief Gets a `SoundObjectHandle` given its asset's filename. * - * Can be a @c SwitchContainerHandle, a @c CollectionHandle, or a @c SoundHandle. + * @param[in] filename The asset's filename. * - * @param filename The filename containing the flatbuffer binary data. + * @note The asset's filename should be relative path from the `sounds`, `collections`, + * or `switch_containers` directories of your Amplitude project, not an absolute path + * from the filesystem base path. + * + * @example + * ```cpp + * // Assuming the asset file is located in "sounds/env/forest/calm_lake_bg.amsound" + * // Note that the return value in this case is a indeed a `SoundHandle` + * SoundObjectHandle handle = amEngine->GetSoundObjectHandleFromFile("env/forest/calm_lake_bg.amsound"); + * ``` + * + * @return The `SoundObjectHandle` for the given asset's filename, or an invalid handle if no sound object + * with that filename was found in any loaded sound bank. + * + * @note The return value can be a `SwitchContainerHandle`, a `CollectionHandle`, or a `SoundHandle`. */ [[nodiscard]] virtual SoundObjectHandle GetSoundObjectHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets an @c EventHandle given its name as defined in its JSON data. + * @brief Gets an `EventHandle` given its name as defined in its asset file (`.amevent`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `EventHandle` for the given name, or an invalid handle if no event with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual EventHandle GetEventHandle(const AmString& name) const = 0; /** - * @brief Gets an @c EventHandle given its ID as defined in its JSON data. + * @brief Gets an `EventHandle` given its ID as defined in its asset file (`.amevent`). * - * @param id The unique ID as defined in the JSON data. + * @param[in] id The unique ID as defined in the asset file. + * + * @return The `EventHandle` for the given ID, or an invalid handle if no event with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual EventHandle GetEventHandle(AmEventID id) const = 0; /** - * @brief Gets an @c EventHandle given its defintion file's name. + * @brief Gets an `EventHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `events` directory of your Amplitude + * project, not an absolute path from the filesystem base path. * - * @param filename The filename containing the flatbuffer binary data. + * @example + * ```cpp + * // Assuming the asset file is located in "events/gameplay/start_menu.amevent" + * EventHandle handle = amEngine->GetEventHandleFromFile("gameplay/start_menu.amevent"); + * ``` + * + * @return The `EventHandle` for the given asset's filename, or an invalid handle if no event + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual EventHandle GetEventHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets an @c AttenuationHandle given its name as defined in its JSON data. + * @brief Gets an `AttenuationHandle` given its name as defined in its asset file (`.amattenuation`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `AttenuationHandle` for the given name, or an invalid handle if no attenuation with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual AttenuationHandle GetAttenuationHandle(const AmString& name) const = 0; /** - * @brief Gets an @c AttenuationHandle given its ID as defined in its JSON data. + * @brief Gets an `AttenuationHandle` given its ID as defined in its asset file (`.amattenuation`). + * + * @param[in] id The unique ID as defined in the asset file. * - * @param id The unique ID as defined in the JSON data. + * @return The `AttenuationHandle` for the given ID, or an invalid handle if no attenuation with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual AttenuationHandle GetAttenuationHandle(AmAttenuationID id) const = 0; /** - * @brief Gets an @c AttenuationHandle given its definition file's name. + * @brief Gets an `AttenuationHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `attenuators` directory of your Amplitude + * project, not an absolute path from the filesystem base path. + * + * @example + * ```cpp + * // Assuming the asset file is located in "attenuators/impact.amattenuation" + * AttenuationHandle handle = amEngine->GetAttenuationHandleFromFile("impact.amattenuation"); + *``` * - * @param filename The filename containing the flatbuffer binary data. + * @return The `AttenuationHandle` for the given asset's filename, or an invalid handle if no attenuation + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual AttenuationHandle GetAttenuationHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets a @c SwitchHandle given its name as defined in its JSON data. + * @brief Gets a `SwitchHandle` given its name as defined in its asset file (`.amswitch`). * - * @param name The unique name as defined in the JSON data. + * @param[in] name The unique name as defined in the asset file. + * + * @return The `SwitchHandle` for the given name, or an invalid handle if no switch with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchHandle GetSwitchHandle(const AmString& name) const = 0; /** - * @brief Gets a @c SwitchHandle given its ID as defined in its JSON data. + * @brief Gets a `SwitchHandle` given its ID as defined in its asset file (`.amswitch`). + * + * @param[in] id The unique ID as defined in the asset file. * - * @param id The unique ID as defined in the JSON data. + * @return The `SwitchHandle` for the given ID, or an invalid handle if no switch with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchHandle GetSwitchHandle(AmSwitchID id) const = 0; /** - * @brief Gets a @c SwitchHandle given its defintion file's name. + * @brief Gets a `SwitchHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `switches` directory of your Amplitude + * project, not an absolute path from the filesystem base path. * - * @param filename The filename containing the flatbuffer binary data. + * @example + * ```cpp + * // Assuming the asset file is located in "switches/env/surfaces.amswitch" + * SwitchHandle handle = amEngine->GetSwitchHandleFromFile("env/surfaces.amswitch"); + * ``` + * + * @return The `SwitchHandle` for the given asset's filename, or an invalid handle if no switch + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual SwitchHandle GetSwitchHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets a @c RtpcHandle given its name as defined in its JSON data. + * @brief Gets a `RtpcHandle` given its name as defined in its asset file (`.amrtpc`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `RtpcHandle` for the given name, or an invalid handle if no RTPC with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual RtpcHandle GetRtpcHandle(const AmString& name) const = 0; /** - * @brief Gets an @c RtpcHandle given its ID as defined in its JSON data. + * @brief Gets an `RtpcHandle` given its ID as defined in its asset file (`.amrtpc`). + * + * @param[in] id The unique ID as defined in the asset file. * - * @param id The unique ID as defined in the JSON data. + * @return The `RtpcHandle` for the given ID, or an invalid handle if no RTPC with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual RtpcHandle GetRtpcHandle(AmRtpcID id) const = 0; /** - * @brief Gets an @c RtpcHandle given its definition file's name. + * @brief Gets an `RtpcHandle` given its asset's filename. * - * @param filename The filename containing the flatbuffer binary data. + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `rtpc` directory of your Amplitude + * project, not an absolute path from the filesystem base path. + * + * @example + * ```cpp + * // Assuming the asset file is located in "rtpc/music_volume.amrtpc" + * RtpcHandle handle = amEngine->GetRtpcHandleFromFile("music_volume.amrtpc"); + * ``` + * + * @return The `RtpcHandle` for the given asset's filename, or an invalid handle if no RTPC + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual RtpcHandle GetRtpcHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets an @c EffectHandle given its name as defined in its JSON data. + * @brief Gets an `EffectHandle` given its name as defined in its asset file (`.amfx`). + * + * @param[in] name The unique name as defined in the asset file. * - * @param name The unique name as defined in the JSON data. + * @return The `EffectHandle` for the given name, or an invalid handle if no effect with that name + * was found in any loaded sound bank. */ [[nodiscard]] virtual EffectHandle GetEffectHandle(const AmString& name) const = 0; /** - * @brief Gets an @c EffectHandle given its ID as defined in its JSON data. + * @brief Gets an `EffectHandle` given its ID as defined in its asset file (`.amfx`). * - * @param id The unique ID as defined in the JSON data. + * @param[in] id The unique ID as defined in the asset file. + * + * @return The `EffectHandle` for the given ID, or an invalid handle if no effect with that ID + * was found in any loaded sound bank. */ [[nodiscard]] virtual EffectHandle GetEffectHandle(AmEffectID id) const = 0; /** - * @brief Gets an @c EffectHandle given its definition file's name. + * @brief Gets an `EffectHandle` given its asset's filename. + * + * @param[in] filename The asset's filename. + * + * @note The asset's filename should be relative path from the `effects` directory of your Amplitude + * project, not an absolute path from the filesystem base path. * - * @param filename The filename containing the flatbuffer binary data. + * @example + * ```cpp + * // Assuming the asset file is located in "effects/echo.amfx" + * EffectHandle handle = amEngine->GetEffectHandleFromFile("echo.amfx"); + * ``` + * + * @return The `EffectHandle` for the given asset's filename, or an invalid handle if no effect + * with that filename was found in any loaded sound bank. */ [[nodiscard]] virtual EffectHandle GetEffectHandleFromFile(const AmOsString& filename) const = 0; /** - * @brief Gets this @c PipelineHandle loaded in the engine configuration. + * @brief Gets a `PipelineHandle` from the loaded pipeline asset file (`.ampipeline`). + * + * @note Only one pipeline can be loaded at a time. The loaded pipeline asset is defined in the + * [engine configuration file](../../../project/engine-config.md#pipeline). + * + * @return The `PipelineHandle` for the loaded pipeline. This method should always return a valid handle. */ [[nodiscard]] virtual PipelineHandle GetPipelineHandle() const = 0; #pragma endregion -#pragma region Master Gain& Mute State +#pragma region Master Gain and Mute State /** * @brief Adjusts the master gain of the mixer. * - * @param gain The master gain. + * @param[in] gain The master gain. */ virtual void SetMasterGain(AmReal32 gain) const = 0; @@ -512,28 +774,28 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Mutes the engine, but keep processing audio. * - * @param mute Whether to mute or unmute the engine. + * @param[in] mute Whether to mute or unmute the engine. */ virtual void SetMute(bool mute) const = 0; /** - * @brief Whether the engine is currently muted. + * @brief Checks whether the engine is currently muted. * - * @return @c true if the engine is muted, @c false otherwise. + * @return `true` if the engine is muted, `false` otherwise. */ [[nodiscard]] virtual bool IsMuted() const = 0; /** * @brief Pauses or resumes all playing sounds and streams. * - * @param pause Whether to pause or resume the engine. + * @param[in] pause Whether to pause or resume the engine. */ virtual void Pause(bool pause) const = 0; /** - * @brief Whether the engine is currently paused. + * @brief Checks whether the engine is currently paused. * - * @return @c true if the engine is currently paused, @c false otherwise. + * @return `true` if the engine is currently paused, `false` otherwise. */ [[nodiscard]] virtual bool IsPaused() const = 0; @@ -544,56 +806,67 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Sets the default sound listener. * - * @param listener A valid and initialized @c Listener instance. + * This method will set the default listener that will render every played sound sources. + * + * @note This method takes effect only if the + * [`listener_fetch_mode`](../../../project/engine-config.md#listener_fetch_mode) + * engine setting is set to `Default`. + * + * @param[in] listener A valid and initialized `Listener` instance. */ virtual void SetDefaultListener(const Listener* listener) = 0; /** * @brief Sets the default sound listener. * - * @param id A valid @c Listener ID. + * This method will set the default listener that will render every played sound sources. + * + * @note This method takes effect only if the + * [`listener_fetch_mode`](../../../project/engine-config.md#listener_fetch_mode) + * engine setting is set to `Default`. + * + * @param[in] id The ID of a valid and registered `Listener`. */ virtual void SetDefaultListener(AmListenerID id) = 0; /** - * @brief Returns a @c Listener object storing the state of the default - * audio listener. + * @brief Gets the default audio `Listener`. * - * @return An initialized @c Listener object if a default listener was set, - * otherwise an unitialized @c Listener object. + * @return An initialized `Listener` object if a default listener was set, + * otherwise an uninitialized `Listener` object. */ [[nodiscard]] virtual Listener GetDefaultListener() const = 0; /** - * @brief Initializes and returns a @c Listener. + * @brief Initializes and returns a new `Listener`. * - * @param id The sound listener ID. + * @param[in] id The new listener ID. * - * @return An initialized @c Listener. + * @return An initialized `Listener`. */ [[nodiscard]] virtual Listener AddListener(AmListenerID id) const = 0; /** - * @brief Returns the @c Listener with the given ID. + * @brief Returns the `Listener` with the given ID. * - * @param id The sound listener ID. + * @param[in] id The listener ID. * - * @return An initialized @c Listener if that one has been registered before, - * otherwise an unitialized @c Listener. + * @return An initialized `Listener` if a one with the given ID has been registered before, + * otherwise an uninitialized `Listener`. */ [[nodiscard]] virtual Listener GetListener(AmListenerID id) const = 0; /** - * @brief Removes a @c Listener given its ID. + * @brief Removes a `Listener` given its ID. * - * @param id The ID of the @c Listener to be removed. + * @param[in] id The ID of the `Listener` to be removed. */ virtual void RemoveListener(AmListenerID id) const = 0; /** - * @brief Removes a @c Listener given its handle. + * @brief Removes a `Listener` given its handle. * - * @param listener The @c Listener to be removed. + * @param[in] listener The `Listener` to be removed. */ virtual void RemoveListener(const Listener* listener) const = 0; @@ -602,35 +875,35 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Entities Management /** - * @brief Initializes and returns an @c Entity. + * @brief Initializes and returns a new `Entity`. * - * @param id The game entity ID. + * @param[in] id The game entity ID. * - * @return An initialized @c Entity. + * @return An initialized `Entity`. */ [[nodiscard]] virtual Entity AddEntity(AmEntityID id) const = 0; /** - * @brief Returns the @c Entity with the given ID. + * @brief Returns the `Entity` with the given ID. * - * @param id The game entity ID. + * @param[in] id The game entity ID. * - * @return An initialized @c Entity if that one has been registered before, - * otherwise an uninitialized @c Entity. + * @return An initialized `Entity` if that one has been registered before, + * otherwise an uninitialized `Entity`. */ [[nodiscard]] virtual Entity GetEntity(AmEntityID id) const = 0; /** - * @brief Removes an @c Entity. + * @brief Removes an `Entity`. * - * @param entity The game entity to be removed. + * @param[in] entity The game entity to be removed. */ virtual void RemoveEntity(const Entity* entity) const = 0; /** - * @brief Removes an @c Entity given its ID. + * @brief Removes an `Entity` given its ID. * - * @param id The ID of the game entity to be removed. + * @param[in] id The ID of the game entity to be removed. */ virtual void RemoveEntity(AmEntityID id) const = 0; @@ -639,35 +912,35 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Environments Management /** - * @brief Initializes and return an @c Environment. + * @brief Initializes and return a new `Environment`. * - * @param id The game environment ID. + * @param[in] id The game environment ID. * - * @return An initialized @c Environment. + * @return An initialized `Environment`. */ [[nodiscard]] virtual Environment AddEnvironment(AmEnvironmentID id) const = 0; /** - * @brief Returns the @c Environment with the given ID. + * @brief Returns the `Environment` with the given ID. * - * @param id The game environment ID. + * @param[in] id The game environment ID. * - * @return An initialized @c Environment if that one has been registered before, - * otherwise an uninitialized @c Environment. + * @return An initialized `Environment` if that one has been registered before, + * otherwise an uninitialized `Environment`. */ [[nodiscard]] virtual Environment GetEnvironment(AmEnvironmentID id) const = 0; /** - * @brief Removes an @c Environment. + * @brief Removes an `Environment`. * - * @param Environment The game environment to be removed. + * @param[in] environment The game environment to be removed. */ - virtual void RemoveEnvironment(const Environment* Environment) const = 0; + virtual void RemoveEnvironment(const Environment* environment) const = 0; /** - * @brief Removes an @c Environment given its ID. + * @brief Removes an `Environment` given its ID. * - * @param id The ID of the game environment to be removed. + * @param[in] id The ID of the game environment to be removed. */ virtual void RemoveEnvironment(AmEnvironmentID id) const = 0; @@ -676,35 +949,35 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Rooms Management /** - * @brief Initializes and return a @c Room. + * @brief Initializes and return a new `Room`. * - * @param id The room ID. + * @param[in] id The room ID. * - * @return An initialized @c Room. + * @return An initialized `Room`. */ [[nodiscard]] virtual Room AddRoom(AmRoomID id) const = 0; /** - * @brief Returns the @c Room with the given ID. + * @brief Returns the `Room` with the given ID. * - * @param id The room ID. + * @param[in] id The room ID. * - * @return An initialized @c Room if that one has been registered before, - * otherwise an uninitialized @c Room. + * @return An initialized `Room` if that one has been registered before, + * otherwise an uninitialized `Room`. */ [[nodiscard]] virtual Room GetRoom(AmRoomID id) const = 0; /** - * @brief Removes a @c Room. + * @brief Removes a `Room`. * - * @param room The room to be removed. + * @param[in] room The room to be removed. */ virtual void RemoveRoom(const Room* room) const = 0; /** - * @brief Removes a @c Room given its ID. + * @brief Removes a `Room` given its ID. * - * @param id The ID of the room to be removed. + * @param[in] id The ID of the room to be removed. */ virtual void RemoveRoom(AmRoomID id) const = 0; @@ -713,20 +986,24 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Buses Management /** - * @brief Returns the @c Bus with the specified name. + * @brief Returns the `Bus` with the specified name. * - * @param name The name of the bus. + * @param[in] name The name of the bus. * - * @return A valid bus if found, otherwise an invalid bus. + * @note The name should match one of the buses loaded from the asset file (`.ambus`). + * + * @return A valid `Bus` if found, otherwise an invalid `Bus`. */ [[nodiscard]] virtual Bus FindBus(const AmString& name) const = 0; /** - * @brief Returns the @c Bus with the given ID. + * @brief Returns the `Bus` with the given ID. + * + * @param[in] id The ID of the bus. * - * @param id The ID of the bus. + * @note The ID should match one of the buses loaded from the asset file (`.ambus`). * - * @return A valid bus if found, otherwise an invalid bus. + * @return A valid `Bus` if found, otherwise an invalid `Bus`. */ [[nodiscard]] virtual Bus FindBus(AmBusID id) const = 0; @@ -737,328 +1014,384 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Plays a switch container associated with the given handle in the World scope. * - * @param handle A handle to the switch container to play. + * This method is recommended for switch containers with spatialization disabled, since + * no positional information need to be provided. + * + * @param[in] handle A handle to the switch container to play. * - * @return The channel the switch container is played on. If the switch container could not be - * played, an invalid @c Channel is returned. + * @return The channel the switch container is being played on. If the switch container could not be + * played, or the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SwitchContainerHandle handle) const = 0; /** - * @brief Plays a switch container associated with the given handle in the World scope at the - * given location. + * @brief Plays a switch container associated with the given handle in the World scope. * - * @param handle A handle to the switch container to play. - * @param location The location on which play the switch container. + * @param[in] handle A handle to the switch container to play. + * @param[in] location The location at which switch container should be played. * - * @return The channel the switch container is played on. If the switch container could not be - * played, an invalid @c Channel is returned. + * @return The channel the switch container is being played on. If the switch container could not be + * played, or the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const AmVec3& location) const = 0; /** - * @brief Plays a switch container associated with the given handle in the World scope at the - * given location with the given gain. + * @brief Plays a switch container associated with the given handle in the World scope. + * + * @param[in] handle A handle to the switch container to play. + * @param[in] location The location at which the switch container should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param handle A handle to the switch container to play. - * @param location The location on which play the switch container. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the switch container is played on. If the switch container could not be - * played, an invalid @c Channel is returned. + * @return The channel the switch container is being played on. If the switch container could not be + * played, or the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const AmVec3& location, AmReal32 userGain) const = 0; /** * @brief Plays a switch container associated with the given handle in an Entity scope. * - * @param handle A handle to the switch container to play. - * @param entity The entity which is playing the switch container. + * @note Switch containers played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @return The channel the switch container is played on. If the switch container could not be - * played, an invalid @c Channel is returned. + * @param[in] handle A handle to the switch container to play. + * @param[in] entity The entity on which the switch container should be played. + * + * @return The channel the switch container is being played on. If the switch container could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const Entity& entity) const = 0; /** - * @brief Plays a switch container associated with the given handle in an Entity scope with the - * given gain. + * @brief Plays a switch container associated with the given handle in an Entity scope. + * + * @note Switch containers played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). + * + * @param[in] handle A handle to the switch container to play. + * @param[in] entity The entity on which the switch container should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param handle A handle to the switch container to play. - * @param entity The entity which is playing the switch container. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the switch container is played on. If the switch container could not be - * played, an invalid @c Channel is returned. + * @return The channel the switch container is being played on. If the switch container could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SwitchContainerHandle handle, const Entity& entity, AmReal32 userGain) const = 0; /** * @brief Plays a collection associated with the given handle in the World scope. * - * @param handle A handle to the collection to play. + * @param[in] handle A handle to the collection to play. * - * @return The channel the collection is played on. If the collection could not be - * played, an invalid @c Channel is returned. + * @return The channel the collection is being played on. If the collection could not be + * played, or the handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(CollectionHandle handle) const = 0; /** - * @brief Plays a collection associated with the given handle in the World scope at - * the given location. + * @brief Plays a collection associated with the given handle in the World scope. * - * @param handle A handle to the collection to play. - * @param location The location on which play the collection. + * @param[in] handle A handle to the collection to play. + * @param[in] location The location at which the collection should be played. * - * @return The channel the collection is played on. If the collection could not be - * played, an invalid @c Channel is returned. + * @return The channel the collection is being played on. If the collection could not be + * played, or the handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(CollectionHandle handle, const AmVec3& location) const = 0; /** - * @brief Plays a collection associated with the given handle in the location with - * the given gain. + * @brief Plays a collection associated with the given handle in the World scope. + * + * @param[in] handle A handle to the collection to play. + * @param[in] location The location at which the collection should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param handle A handle to the collection to play. - * @param location The location on which play the collection. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the collection is played on. If the collection could not be - * played, an invalid @c Channel is returned. + * @return The channel the collection is being played on. If the collection could not be + * played, or the handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(CollectionHandle handle, const AmVec3& location, AmReal32 userGain) const = 0; /** * @brief Plays a collection associated with the given handle in the Entity scope. * - * @param handle A handle to the collection to play. - * @param entity The entity which is playing the collection. + * @note Collections played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @return The channel the collection is played on. If the collection could not be - * played, an invalid @c Channel is returned. + * @param[in] handle A handle to the collection to play. + * @param[in] entity The entity on which the collection should be played. + * + * @return The channel the collection is being played on. If the collection could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(CollectionHandle handle, const Entity& entity) const = 0; /** - * @brief Plays a collection associated with the given handle in an Entity scope - * with the given gain. + * @brief Plays a collection associated with the given handle in an Entity scope. + * + * @note Collections played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). + * + * @param[in] handle A handle to the collection to play. + * @param[in] entity The entity on which the collection should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param handle A handle to the collection to play. - * @param entity The entity which is playing the collection. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the collection is played on. If the collection could not be - * played, an invalid @c Channel is returned. + * @return The channel the collection is being played on. If the collection could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(CollectionHandle handle, const Entity& entity, AmReal32 userGain) const = 0; /** * @brief Plays a sound associated with the given handle in the World scope. * - * @param handle A handle to the sound to play. + * @param[in] handle A handle to the sound to play. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound is being played on. If the sound could not be + * played, the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SoundHandle handle) const = 0; /** - * @brief Plays a sound associated with the given handle in the World scope - * at the given location. + * @brief Plays a sound associated with the given handle in the World scope. * - * @param handle A handle to the sound to play. - * @param location The location on which play the sound. + * @param[in] handle A handle to the sound to play. + * @param[in] location The location at which the sound should be played. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound is being played on. If the sound could not be + * played, the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SoundHandle handle, const AmVec3& location) const = 0; /** - * @brief Plays a sound associated with the given handle in the World scope - * at the given location with the given gain. + * @brief Plays a sound associated with the given handle in the World scope. + * + * @param[in] handle A handle to the sound to play. + * @param[in] location The location at which the sound should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param handle A handle to the sound to play. - * @param location The location on which play the sound. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound is being played on. If the sound could not be + * played, the given handle is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SoundHandle handle, const AmVec3& location, AmReal32 userGain) const = 0; /** * @brief Plays a sound associated with the given sound handle in an Entity scope. * - * @param handle A handle to the sound to play. - * @param entity The entity which is playing the sound. + * @note Sounds played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @param[in] handle A handle to the sound to play. + * @param[in] entity The entity on which the sound should be played. + * + * @return The channel the sound is being played on. If the sound could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SoundHandle handle, const Entity& entity) const = 0; /** - * @brief Plays a sound associated with the given sound handle in an Entity - * scope with the given gain. + * @brief Plays a sound associated with the given sound handle in an Entity. + * + * @note Sounds played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @param handle A handle to the sound to play. - * @param entity The entity which is playing the sound. - * @param userGain The gain of the sound. + * @param[in] handle A handle to the sound to play. + * @param[in] entity The entity on which the sound should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. + * + * @return The channel the sound is being played on. If the sound could not be + * played, the given handle is invalid, or the given entity is invalid, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(SoundHandle handle, const Entity& entity, AmReal32 userGain) const = 0; /** * @brief Plays a sound object associated with the given name in the World scope. * - * @note Playing a sound object with its handle is faster than using the - * name as using the name requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * name as using the name requires an internal lookup. * - * @param name The name of the sound object to play. + * @param[in] name The name of the sound object to play. * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given name was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(const AmString& name) const = 0; /** * @brief Plays a sound object associated with the given name in the World scope. * - * @note Playing a sound object with its handle is faster than using the - * name as using the name requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * name as using the name requires an internal lookup. * - * @param name The name of the sound object to play. - * @param location The location of the sound. + * @param[in] name The name of the sound object to play. + * @param[in] location The location at which the sound should be played. * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given name was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(const AmString& name, const AmVec3& location) const = 0; /** * @brief Plays a sound object associated with the given name in the World scope. * - * @note Playing a sound object with its handle is faster than using the - * name as using the name requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * name as using the name requires an internal lookup. + * + * @param[in] name The name of the sound object to play. + * @param[in] location The location at which the sound should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param name The name of the sound object to play. - * @param location The location of the sound. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given name was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(const AmString& name, const AmVec3& location, AmReal32 userGain) const = 0; /** * @brief Plays a sound object associated with the given name in an Entity scope. * - * @note Playing a sound object with its handle is faster than using the - * name as using the name requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * name as using the name requires an internal lookup. * - * @param name The name of the sound object to play. - * @param entity The entity which is playing the sound. + * @note Sound objects played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @param[in] name The name of the sound object to play. + * @param[in] entity The entity on which the sound object should be played. + * + * @return The channel the sound object is being played on. If the object could not be + * played, an object with the given name was not found, or the entity is invalid, + * an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(const AmString& name, const Entity& entity) const = 0; /** * @brief Plays a sound object associated with the given name in an Entity scope. * - * @note Playing a sound object with its handle is faster than using the - * name as using the name requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * name as using the name requires an internal lookup. + * + * @note Sound objects played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). + * + * @param[in] name The name of the sound object to play. + * @param[in] entity The entity on which the sound object should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @param name The name of the sound object to play. - * @param entity The entity which is playing the sound. - * @param userGain The gain of the sound. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, an object with the given name was not found, or the entity is invalid, + * an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(const AmString& name, const Entity& entity, AmReal32 userGain) const = 0; /** - * @brief Plays a sound object associated with the given ID in the - * World scope, at the origin of the world. + * @brief Plays a sound object associated with the given ID in the World scope. * - * @note Playing a sound object with its handle is faster than using the - * ID as using the ID requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * ID as using the ID requires an internal lookup. * - * @param id The ID of the sound object to play. + * @param[in] id The ID of the sound object to play. * - * @return The channel the sound is played on. If the object could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given ID was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(AmObjectID id) const = 0; /** - * @brief Plays a sound object associated with the given ID in the - * World scope, at the given location. + * @brief Plays a sound object associated with the given ID in the World scope. * - * @note Playing a sound object with its handle is faster than using the - * ID as using the ID requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * ID as using the ID requires an internal lookup. * - * @param id The ID of the sound object to play. - * @param location The location of the sound. + * @param[in] id The ID of the sound object to play. + * @param[in] location The location at which the sound object should be played. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given ID was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(AmObjectID id, const AmVec3& location) const = 0; /** - * @brief Plays a sound object associated with the given ID in the - * World scope, at the given location, and with the given gain. + * @brief Plays a sound object associated with the given ID in the World scope. * - * @note Playing an object with its handle is faster than using the - * ID as using the ID requires a map lookup internally. + * @tip Playing a sound object with its handle is faster than using the + * ID as using the ID requires an internal lookup. * - * @param id The ID of the sound object to play. - * @param location The location of the sound. - * @param userGain The gain of the sound. + * @param[in] id The ID of the sound object to play. + * @param[in] location The location at which the sound object should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. + * + * @return The channel the sound object is being played on. If the object could not be + * played, or an object with the given ID was not found, an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(AmObjectID id, const AmVec3& location, AmReal32 userGain) const = 0; /** - * @brief Plays a sound or a collection associated with the given ID in an Entity scope. + * @brief Plays a sound object associated with the given ID in an Entity scope. + * + * @tip Playing a sound object with its handle is faster than using the + * ID as using the ID requires an internal lookup. * - * @note Playing an object with its handle is faster than using the - * ID as using the ID requires a map lookup internally. + * @note Sound objects played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @param id The ID of the sound object to play. - * @param entity The entity which is playing the sound. + * @param[in] id The ID of the sound object to play. + * @param[in] entity The entity on which the sound object should be played. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @return The channel the sound object is being played on. If the object could not be + * played, an object with the given ID was not found, or the entity is invalid, + * an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(AmObjectID id, const Entity& entity) const = 0; /** - * @brief Plays a sound object associated with the given ID in an Entity - * scope with the given gain. + * @brief Plays a sound object associated with the given ID in an Entity scope. + * + * @tip Playing a sound object with its handle is faster than using the + * ID as using the ID requires an internal lookup. * - * @note Playing an object with its handle is faster than using the - * ID as using the ID requires a map lookup internally. + * @note Sound objects played using this method should have been set in the `Entity` scope + * from their asset file. See more [here](../../../project/sound-object.md#scope). * - * @param id The ID of the sound object to play. - * @param entity The entity which is playing the sound. - * @param userGain The gain of the sound. + * @param[in] id The ID of the sound object to play. + * @param[in] entity The entity on which the sound object should be played. + * @param[in] userGain The gain of the sound. Must be in the range [0, 1]. * - * @return The channel the sound is played on. If the sound could not be - * played, an invalid @c Channel is returned. + * @note The `userGain` parameter will not be used directly, but instead, it will be used in the final + * gain computation, which may include other factors like the attenuation and the master gain. + * + * @return The channel the sound object is being played on. If the object could not be + * played, an object with the given ID was not found, or the entity is invalid, + * an invalid `Channel` is returned. */ [[nodiscard]] virtual Channel Play(AmObjectID id, const Entity& entity, AmReal32 userGain) const = 0; /** * @brief Stops all playing sound objects. + * + * This is the equivalent of calling `Stop()` on all generated channels. */ virtual void StopAll() const = 0; @@ -1069,23 +1402,23 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Triggers the event associated to the given handle. * - * @param handle The handle of the event to trigger. - * @param entity The entity in which trigger the event. + * @param[in] handle The handle of the event to trigger. + * @param[in] entity The entity on which trigger the event. * - * @return An @c EventCanceler object which may be used to cancel the execution of the event.. + * @return An `EventCanceler` object which may be used to cancel the execution of the event. */ [[nodiscard]] virtual EventCanceler Trigger(EventHandle handle, const Entity& entity) const = 0; /** * @brief Triggers the event associated to the given handle. * - * @note Triggering an event with its EventHandle is faster than using the - * event name as using the name requires a map lookup internally. + * @tip Triggering an event with its `EventHandle` is faster than using the + * event name as using the name requires an internal lookup. * - * @param name The name of event to trigger. - * @param entity The entity in which trigger the event. + * @param[in] name The name of event to trigger. + * @param[in] entity The entity on which trigger the event. * - * @return An @c EventCanceler object which may be used to cancel the execution of the event.. + * @return An `EventCanceler` object which may be used to cancel the execution of the event. */ [[nodiscard]] virtual EventCanceler Trigger(const AmString& name, const Entity& entity) const = 0; @@ -1094,74 +1427,74 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Switches /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param handle The handle of the @c Switch. - * @param stateId The ID of the active state to set. + * @param[in] handle The handle of the `Switch`. + * @param[in] stateId The ID of the active state to set. */ virtual void SetSwitchState(SwitchHandle handle, AmObjectID stateId) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param handle The handle of the @c Switch. - * @param stateName The name of the active state to set. + * @param[in] handle The handle of the `Switch`. + * @param[in] stateName The name of the active state to set. */ virtual void SetSwitchState(SwitchHandle handle, const AmString& stateName) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param handle The handle of the @c Switch. - * @param state The active state to set. + * @param[in] handle The handle of the `Switch`. + * @param[in] state The active state to set. */ virtual void SetSwitchState(SwitchHandle handle, const SwitchState& state) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param id The ID of the @c Switch to update. - * @param stateId The ID of the active state to set. + * @param[in] id The ID of the `Switch` to update. + * @param[in] stateId The ID of the active state to set. */ virtual void SetSwitchState(AmSwitchID id, AmObjectID stateId) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param id The ID of the @c Switch to update. - * @param stateName The name of the active state to set. + * @param[in] id The ID of the `Switch` to update. + * @param[in] stateName The name of the active state to set. */ virtual void SetSwitchState(AmSwitchID id, const AmString& stateName) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param id The ID of the @c Switch to update. - * @param state The active state to set. + * @param[in] id The ID of the `Switch` to update. + * @param[in] state The active state to set. */ virtual void SetSwitchState(AmSwitchID id, const SwitchState& state) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param name The name of the @c Switch to update. - * @param stateId The ID of the active state to set. + * @param[in] name The name of the `Switch` to update. + * @param[in] stateId The ID of the active state to set. */ virtual void SetSwitchState(const AmString& name, AmObjectID stateId) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param name The name of the @c Switch to update. - * @param stateName The name of the active state to set. + * @param[in] name The name of the `Switch` to update. + * @param[in] stateName The name of the active state to set. */ virtual void SetSwitchState(const AmString& name, const AmString& stateName) const = 0; /** - * @brief Set the active state of the defined @c Switch. + * @brief Sets the active state of the defined `Switch`. * - * @param name The name of the @c Switch to update. - * @param state The active state to set. + * @param[in] name The name of the `Switch` to update. + * @param[in] state The active state to set. */ virtual void SetSwitchState(const AmString& name, const SwitchState& state) const = 0; @@ -1170,26 +1503,26 @@ namespace SparkyStudios::Audio::Amplitude #pragma region RTPC /** - * @brief Set the value of a @c RTPC. + * @brief Sets the value of a `RTPC`. * - * @param handle The @c RTPC handle to update. - * @param value The value to set to the @c RTPC. + * @param[in] handle The handle of the `RTPC` to update. + * @param[in] value The value to set to the `RTPC`. */ virtual void SetRtpcValue(RtpcHandle handle, double value) const = 0; /** - * @brief Set the value of a @c RTPC. + * @brief Sets the value of a `RTPC`. * - * @param id The ID of the @c RTPC to update. - * @param value The value to set to the @c RTPC. + * @param[in] id The ID of the `RTPC` to update. + * @param[in] value The value to set to the `RTPC`. */ virtual void SetRtpcValue(AmRtpcID id, double value) const = 0; /** - * @brief Set the value of a @c RTPC. + * @brief Sets the value of a `RTPC`. * - * @param name THe name of the @c RTPC to update. - * @param value The value to set to the @c RTPC. + * @param[in] name THe name of the `RTPC` to update. + * @param[in] value The value to set to the `RTPC`. */ virtual void SetRtpcValue(const AmString& name, double value) const = 0; @@ -1198,7 +1531,7 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Driver /** - * @brief Gets the audio driver used by this Engine. + * @brief Gets the audio driver used by the Engine. * * @return The audio driver. */ @@ -1211,7 +1544,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the mixer instance. * - * @return The Amplimix mixer instance. + * @return The `Amplimix` mixer instance. */ [[nodiscard]] virtual Amplimix* GetMixer() const = 0; @@ -1220,29 +1553,28 @@ namespace SparkyStudios::Audio::Amplitude #pragma region Engine State and Configuration /** - * @brief Get the current speed of sound. + * @brief Gets the speed of sound, as set in the loaded engine configuration file. * * @return The speed of sound. */ [[nodiscard]] virtual AmReal32 GetSoundSpeed() const = 0; /** - * @brief Get the engine Doppler factor. + * @brief Get the Doppler factor, as set in the loaded engine configuration file. * * @return The Doppler factor. */ [[nodiscard]] virtual AmReal32 GetDopplerFactor() const = 0; /** - * @brief Get the number of samples to process in one stream. + * @brief Get the number of samples to process in one stream, as set in the loaded engine configuration file. * * @return The number of samples per stream. */ [[nodiscard]] virtual AmUInt32 GetSamplesPerStream() const = 0; /** - * @brief Checks whether the game is tracking environment amounts - * himself. This is useful for engines like O3DE. + * @brief Checks whether the game is tracking environment amounts himself. * * @return Whether the game is tracking environment amounts. */ @@ -1256,36 +1588,37 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] virtual AmUInt32 GetMaxListenersCount() const = 0; /** - * @brief Gets the maximum number of game entities handled by the engine. This value - * does not reflect the maximum number of simultaneous sound handled by the engine. + * @brief Gets the maximum number of game entities handled by the engine. + * + * This value does not reflect the maximum number of simultaneous sound handled by the engine. * * @return The maximum number of game entities. */ [[nodiscard]] virtual AmUInt32 GetMaxEntitiesCount() const = 0; /** - * @brief Gets the occlusion coefficient curve defined in the loaded engine configuration. + * @brief Gets the occlusion coefficient curve, as set in the loaded engine configuration file. * * @return The occlusion coefficient curve. */ [[nodiscard]] virtual const Curve& GetOcclusionCoefficientCurve() const = 0; /** - * @brief Gets the occlusion gain curve defined in the loaded engine configuration. + * @brief Gets the occlusion gain curve, as set in the loaded engine configuration file. * * @return The occlusion gain curve. */ [[nodiscard]] virtual const Curve& GetOcclusionGainCurve() const = 0; /** - * @brief Gets the obstruction low pass curve defined in the loaded engine configuration. + * @brief Gets the obstruction coefficient curve, as set in the loaded engine configuration file. * - * @return The obstruction low pass curve. + * @return The obstruction coefficient curve. */ [[nodiscard]] virtual const Curve& GetObstructionCoefficientCurve() const = 0; /** - * @brief Gets the obstruction gain curve defined in the loaded engine configuration. + * @brief Gets the obstruction gain curve, as set in the loaded engine configuration file. * * @return The obstruction gain curve. */ @@ -1299,16 +1632,16 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] virtual ePanningMode GetPanningMode() const = 0; /** - * Gets the HRIR sphere sampling mode defined in the loaded engine configuration. + * @brief Gets the HRIR sphere sampling mode defined in the loaded engine configuration. * * @return The HRIR sphere sampling mode. */ [[nodiscard]] virtual eHRIRSphereSamplingMode GetHRIRSphereSamplingMode() const = 0; /** - * Gets the HRIR sphere defined in the loaded engine configuration. + * @brief Gets the HRIR sphere defined in the loaded engine configuration. * - * @return The HRIR sphere. If no HRIR sphere is defined, returns nullptr. + * @return The HRIR sphere. If no HRIR sphere is defined, returns `nullptr`. * * @note The HRIR sphere is optional and can be null in some cases. If the * engine does not have an HRIR sphere defined, this function will return `nullptr`. @@ -1324,7 +1657,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Loads a plugin library from the given path. * - * @param pluginLibraryName The name of the plugin library to load. + * @param[in] pluginLibraryName The name of the plugin library to load. * * @return A handle to the loaded plugin library. */ @@ -1333,14 +1666,14 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Adds a path in the plugins search paths list. * - * @param path The path to add in the plugins search paths list. + * @param[in] path The path to add in the plugins search paths list. */ static void AddPluginSearchPath(const AmOsString& path); /** * @brief Removes a path from the plugins search paths list. * - * @param path The path to remove from the plugins search path list. + * @param[in] path The path to remove from the plugins search path list. */ static void RemovePluginSearchPath(const AmOsString& path); diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Entity.h b/include/SparkyStudios/Audio/Amplitude/Core/Entity.h index 233a3959..73f53dec 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Entity.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Entity.h @@ -24,191 +24,219 @@ namespace SparkyStudios::Audio::Amplitude class EntityInternalState; /** - * @brief An Entity represent an object in the game. + * @brief An Entity represents a spatially positioned object in the game. * * Amplitude use entities to link sound to an object in the game. Each sounds * played from an entity get the location and orientation data fom that entity. * - * The Entity class is a lightweight reference to a EntityInternalState object - * which is managed by the Engine. + * The `Entity` class is a lightweight reference to an `EntityInternalState` object + * which is managed by the `Engine`. + * + * @ingroup engine */ class AM_API_PUBLIC Entity { public: /** - * @brief Creates an uninitialized Entity. + * @brief Creates an uninitialized `Entity`. * * An uninitialized Entity cannot provide location and orientation * information, and therefore cannot play sounds. + * + * To create an initialized `Entity`, use the `AddEntity()` method of the + * `Engine` instance. + * ```cpp + * amEngine->AddEntity(1234); // You should provide an unique ID + * ``` */ Entity(); + /** + * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. + */ explicit Entity(EntityInternalState* state); /** - * @brief Uninitializes this Entity. + * @brief Uninitializes this `Entity`. * * Note that this does not destroy the internal state it references, * it just removes this reference to it. + * + * To completely destroy the `Entity`, use `RemoveEntity()` method + * of the `Engine` instance. + * ```cpp + * amEngine->RemoveEntity(1234); // You should provide the entity ID + * ``` */ void Clear(); /** - * @brief Checks whether this Entity has been initialized. + * @brief Checks whether this `Entity` has been initialized. * - * @return boolean true if this Entity has been initialized. + * @return `true` if this `Entity` is initialized, `false` otherwise. */ [[nodiscard]] bool Valid() const; /** - * @brief Gets the ID of this Entity in game. + * @brief Gets the ID of this `Entity`. * - * @return The game Entity ID. + * @return The `Entity` ID. */ [[nodiscard]] AmEntityID GetId() const; /** - * @brief Gets the velocity of the Entity. + * @brief Gets the velocity of the `Entity`. * - * @return The Entity's velocity. + * @return The entity's velocity. */ [[nodiscard]] const AmVec3& GetVelocity() const; /** - * @brief Sets the location of this Entity. + * @brief Sets the location of this `Entity`. * - * @param location The new location. + * @param[in] location The new location. */ void SetLocation(const AmVec3& location) const; /** - * @brief Gets the current location of this Entity. + * @brief Gets the current location of this `Entity`. * - * @return The current location of this Entity. + * @return The current location of this `Entity`. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Sets the orientation of this Entity. + * @brief Sets the orientation of this `Entity`. * - * @param orientation The new orientation. + * @param[in] orientation The new orientation. */ void SetOrientation(const Orientation& orientation) const; /** - * @brief Get the direction vector of the Entity. + * @brief Gets the direction vector of the `Entity`. * * @return The direction vector. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Get the up vector of the Entity. + * @brief Gets the up vector of the `Entity`. * * @return The up vector. */ [[nodiscard]] AmVec3 GetUp() const; /** - * @brief Get the orientation of the Entity. + * @brief Gets the orientation of the `Entity`. * * @return The entity's orientation. */ [[nodiscard]] const Orientation& GetOrientation() const; /** - * @brief Update the state of this Entity. + * @brief Updates the state of this `Entity`. + * + * This method is called automatically by the `Engine` + * on each frames to update the internal state of the `Entity` * - * This method is called automatically by the Engine - * on each frames. + * @warning This method is for internal usage only. */ void Update() const; /** - * @brief Set the obstruction level of sounds played by this Entity. + * @brief Sets the obstruction level of sounds played by this `Entity`. * - * @param obstruction The obstruction amount. This is provided by the - * game engine. + * @param[in] obstruction The obstruction amount. */ void SetObstruction(AmReal32 obstruction) const; /** - * @brief Set the occlusion level of sounds played by this Entity. + * @brief Sets the occlusion level of sounds played by this `Entity`. * - * @param occlusion The occlusion amount. This is provided by the - * game engine. + * @param[in] occlusion The occlusion amount. */ void SetOcclusion(AmReal32 occlusion) const; /** - * @brief Sets the directivity and sharpness of sounds played by this Entity. + * @brief Sets the directivity and sharpness of sounds played by this `Entity`. * - * @param directivity The directivity of the sound source, in the range [0, 1]. - * @param sharpness The directivity sharpness of the sound source, in the range [1, +INF]. + * @param[in] directivity The directivity of the sound source, in the range [0, 1]. + * @param[in] sharpness The directivity sharpness of the sound source, in the range [1, +INF]. * Increasing this value increases the directivity towards the front of the source. */ void SetDirectivity(AmReal32 directivity, AmReal32 sharpness) const; /** - * @brief Get the obstruction level of sounds played by this Entity. + * @brief Gets the obstruction level of sounds played by this `Entity`. * * @return The obstruction amount. */ [[nodiscard]] AmReal32 GetObstruction() const; /** - * @brief Get the occlusion level of sounds played by this Entity. + * @brief Gets the occlusion level of sounds played by this `Entity`. * * @return The occlusion amount. */ [[nodiscard]] AmReal32 GetOcclusion() const; /** - * @brief Gets the directivity of sounds played by this Entity. + * @brief Gets the directivity of sounds played by this `Entity`. * * @return The directivity of sound sources. */ [[nodiscard]] AmReal32 GetDirectivity() const; /** - * @brief Gets the directivity sharpness of sounds played by this Entity. + * @brief Gets the directivity sharpness of sounds played by this `Entity`. * - * @return The directivity sharpness of sounds played by this Entity. + * @return The directivity sharpness of sounds played by this `Entity`. */ [[nodiscard]] AmReal32 GetDirectivitySharpness() const; /** - * @brief Sets the environment factor for this Entity in the given environment. + * @brief Sets the environment factor for this `Entity` in the given environment. * - * @param environment The environment ID. - * @param factor The environment factor. + * @param[in] environment The environment ID. + * @param[in] factor The environment factor. */ void SetEnvironmentFactor(AmEnvironmentID environment, AmReal32 factor) const; /** - * @brief Gets the environment factor of this Entity for the given environment. + * @brief Gets the environment factor of this `Entity` for the given environment. * - * @param environment The environment ID. + * @param[in] environment The environment ID. * * @return The environment factor. */ [[nodiscard]] AmReal32 GetEnvironmentFactor(AmEnvironmentID environment) const; /** - * @brief Get the list of environments where this Entity belongs or has visited. + * @brief Gets the list of environments where this `Entity` belongs or has visited. * - * @return The list of environments where this Entity belongs or has visited. + * @return The list of environments where this `Entity` belongs or has visited. */ [[nodiscard]] const std::map& GetEnvironments() const; /** - * @brief Returns the internal state of this Entity. + * @brief Returns the internal state of this `Entity`. + * + * @return The `Entity` internal state. * - * @return The Entity internal state. + * @warning This method is for internal usage only. */ [[nodiscard]] EntityInternalState* GetState() const; private: + /** + * @brief The internal state of the entity. + * + * @internal + */ EntityInternalState* _state; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Environment.h b/include/SparkyStudios/Audio/Amplitude/Core/Environment.h index 8932bb36..4812fbf2 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Environment.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Environment.h @@ -30,20 +30,29 @@ namespace SparkyStudios::Audio::Amplitude * @brief An Environment is a zone where every spatialized audio playing inside him got * applied a specific effect. * - * The Environment class is a lightweight reference to a EnvironmentInternalState object - * which is managed by the Engine. + * The `Environment` class is a lightweight reference to an `EnvironmentInternalState` object + * which is managed by the `Engine`. + * + * @ingroup engine */ class AM_API_PUBLIC Environment { public: /** - * @brief Creates an uninitialized Environment. + * @brief Creates an uninitialized `Environment`. * * An uninitialized Environment cannot provide location and orientation * information, and therefore cannot play sounds. */ Environment(); + /** + * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. + */ explicit Environment(EnvironmentInternalState* state); /** @@ -55,137 +64,146 @@ namespace SparkyStudios::Audio::Amplitude void Clear(); /** - * @brief Checks whether this Environment has been initialized. + * @brief Checks whether this `Environment` has been initialized. * - * @return boolean true if this Environment has been initialized. + * @return `true` if this `Environment` is initialized, `false` otherwise. */ [[nodiscard]] bool Valid() const; /** - * @brief Returns the unique ID of this Environment. + * @brief Returns the unique ID of this `Environment`. * - * @return The Environment unique ID. + * @return The `Environment` unique ID. */ [[nodiscard]] AmEnvironmentID GetId() const; /** - * @brief Sets the location of this Environment. + * @brief Sets the location of this `Environment`. * - * @param location The new location. + * @param[in] location The new location. */ void SetLocation(const AmVec3& location) const; /** - * @brief Gets the current location of this Environment. + * @brief Gets the current location of this `Environment`. * - * @return The current location of this Environment. + * @return The current location of this `Environment`. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Sets the orientation of this Environment. + * @brief Sets the orientation of this `Environment`. * - * @param orientation The new orientation. + * @param[in] orientation The new orientation. */ void SetOrientation(const Orientation& orientation) const; /** - * @brief Gets the current orientation of this Environment. + * @brief Gets the current orientation of this `Environment`. * - * @return The current orientation of this Environment. + * @return The current orientation of this `Environment`. */ [[nodiscard]] const Orientation& GetOrientation() const; /** - * @brief Get the direction vector of the Environment. + * @brief Gets the direction vector of the `Environment`. * * @return The direction vector. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Get the up vector of the Environment. + * @brief Gets the up vector of the `Environment`. * * @return The up vector. */ [[nodiscard]] AmVec3 GetUp() const; /** - * @brief Get the Environment factor for the given location. + * @brief Gets the `Environment` factor for the given location. * - * @param location The location for which compute the environment factor. + * @param[in] location The location for which compute the environment factor. * * @return The environment factor. */ [[nodiscard]] AmReal32 GetFactor(const AmVec3& location) const; /** - * @brief Get the Environment factor for the given entity. + * @brief Gets the `Environment` factor for the given entity. * - * @param entity The entity for which compute the environment factor. + * @param[in] entity The entity for which compute the environment factor. * * @return The environment factor. */ [[nodiscard]] AmReal32 GetFactor(const Entity& entity) const; /** - * @brief Set the Effect applied in the Environment. + * @brief Sets the `Effect` applied in the `Environment`. * - * @param effect The effect to apply in the Environment. + * @param[in] effect The ID of the effect to apply in the `Environment`. */ void SetEffect(AmEffectID effect) const; /** - * @brief Set the Effect applied in the Environment. + * @brief Sets the `Effect` applied in the `Environment`. * - * @param effect The effect to apply in the Environment. + * @param[in] effect The name of the effect to apply in the `Environment`. */ - void SetEffect(const std::string& effect) const; + void SetEffect(const AmString& effect) const; /** - * @brief Set the Effect applied in the Environment. + * @brief Sets the `Effect` applied in the `Environment`. * - * @param effect The effect to apply in the Environment. + * @param[in] effect The effect to apply in the `Environment`. */ void SetEffect(const Effect* effect) const; /** - * @brief Get the Effect linked to this environment. + * @brief Gets the `Effect` linked to this environment. * - * @return An Effect instance. + * @return An `Effect` instance. */ [[nodiscard]] const Effect* GetEffect() const; /** - * @brief Set the Zone for this environment. + * @brief Sets the `Zone` for this environment. * - * @param zone The environment's zone. + * @param[in] zone The environment's zone. */ void SetZone(Zone* zone) const; /** - * @brief Get the Zone linked to this environment. + * @brief Gets the `Zone` linked to this environment. * - * @return An Zone instance. + * @return An `Zone` instance. */ [[nodiscard]] Zone* GetZone() const; /** - * @brief Returns the internal state of this Environment. + * @brief Returns the internal state of this `Environment`. * - * @return The Environment internal state. + * @return The `Environment` internal state. + * + * @warning This method is for internal usage only. */ [[nodiscard]] EnvironmentInternalState* GetState() const; /** - * @brief Update the state of this Environment. + * @brief Updates the state of this `Environment`. + * + * This method is called automatically by the `Engine` + * on each frames to update the internal state of the `Environment`. * - * This method is called automatically by the Engine - * on each frames. + * @warning This method is for internal usage only. */ void Update() const; private: + /** + * @brief The internal state of the entity. + * + * @internal + */ EnvironmentInternalState* _state; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Event.h b/include/SparkyStudios/Audio/Amplitude/Core/Event.h index dbe4da8b..5ce261d2 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Event.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Event.h @@ -27,23 +27,27 @@ namespace SparkyStudios::Audio::Amplitude class EventInstance; /** - * @brief A class which can cancel a triggered Event. + * @brief An helper class used to cancel a running `Event`. + * + * @see Event + * + * @ingroup engine */ class AM_API_PUBLIC EventCanceler { public: /** - * @brief Creates an uninitialized EventCanceler. + * @brief Creates an uninitialized `EventCanceler`. * - * An uninitialized Event cannot be triggered. + * An uninitialized `EventCanceler` cannot be canceled. */ EventCanceler(); /** - * @brief Creates an @c EventCanceler which will abort + * @brief Creates an `EventCanceler` which will abort * the given event once cancelled. * - * @param event The event instance to cancel. + * @param[in] event The event instance to cancel. */ explicit EventCanceler(EventInstance* event); @@ -54,34 +58,47 @@ namespace SparkyStudios::Audio::Amplitude ~EventCanceler(); /** - * @brief Checks whether this EventCanceler has been initialized. + * @brief Checks whether this `EventCanceler` has been initialized. * - * @return true if this EventCanceler has been initialized, false otherwise. + * @return `true` if this `EventCanceler` has been initialized, `false` otherwise. */ [[nodiscard]] bool Valid() const; /** - * @brief Cancels and abort the wrapped Event. + * @brief Cancels and abort the wrapped `Event`. */ void Cancel() const; /** - * @brief Returns the Event wrapped by this EventCanceler. + * @brief Returns the `Event` wrapped by this `EventCanceler`. * - * @return The Event wrapped by this EventCanceler. + * @return The `Event` wrapped by this `EventCanceler`. */ [[nodiscard]] EventInstance* GetEvent() const; private: + /** + * @brief The wrapped event instance. + * + * @internal + */ EventInstance* _event; }; /** - * @brief An event is mainly used to apply a set of actions at a given time in game. + * @brief Amplitude Event Asset. + * + * An event is used to apply a set of actions (synchronously or asynchronously) at a given time + * in the game. + * + * This `Event` class is only referenced through an `EventCanceler` object and it is + * managed by the `Engine`. Events can be triggered at runtime by using the `Trigger()` + * method of the `Engine` instance: + * ```cpp + * amEngine->Trigger("an_event_name"); // You can also use the event ID, or its handle. + * ``` * - * This Event class is only referenced through an EventCanceler object and it is - * managed by the Engine. Events can be triggered at runtime by calling the - * Engine::Trigger() method using the name of the event. + * @ingroup assets */ class AM_API_PUBLIC Event : public Asset { @@ -90,30 +107,44 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A triggered event. * - * EventInstance are created when an Event is effectively triggered. They represent + * `EventInstance` objects are created when an `Event` is triggered. They represent * the lifetime of that event at that particular time. + * + * The internal state of an `EventInstance` is owned by that `EventInstance`, that means + * each time you trigger an `Event`, a new instance with its own state is created. + * + * @see Event + * + * @ingroup engine */ class AM_API_PUBLIC EventInstance { public: + /** + * @brief Default constructor. + */ virtual ~EventInstance() = default; /** - * @brief Applies a frame update on this Event. + * @brief Applies a frame update on this `Event`. + * + * This method is called once per frame to update the event instance's state. + * + * @param[in] deltaTime The time elapsed since the last frame. * - * @param deltaTime The time elapsed since the last frame. + * @warning This method is for internal usage only. */ virtual void AdvanceFrame(AmTime deltaTime) = 0; /** - * @brief Returns whether thisEvent is running. + * @brief Returns whether this `EventInstance` is running. * - * @return true if the event is running, false otherwise. + * @return `true` if the event is running, `false` otherwise. */ [[nodiscard]] virtual bool IsRunning() const = 0; /** - * @brief Aborts the execution of this Event. + * @brief Aborts the execution of this `Event`. */ virtual void Abort() = 0; }; diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Listener.h b/include/SparkyStudios/Audio/Amplitude/Core/Listener.h index bcf34bbb..aa0dd828 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Listener.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Listener.h @@ -24,144 +24,173 @@ namespace SparkyStudios::Audio::Amplitude class ListenerInternalState; /** - * @brief An object whose distance from sounds determines their gain. + * @brief A object which can render sound sources. * - * The Listener class is a lightweight reference to a ListenerInternalState - * which is managed by the Engine. Multiple Listener objects may point to + * The `Listener` class is a lightweight reference to a `ListenerInternalState` + * which is managed by the `Engine`. Multiple `Listener` objects may point to * the same underlying data. + * + * @ingroup engine */ class AM_API_PUBLIC Listener { public: /** - * @brief Construct an uninitialized Listener. + * @brief Construct an uninitialized `Listener`. + * + * An uninitialized `Listener` cannot have its location set or queried, nor + * render sound sources. * - * An uninitialized Listener cannot have its location set or queried. - * To initialize the Listener, use Engine::AddListener();. + * To create an initialized `Listener`, use the `AddListener()` method of the + * `Engine` instance. + * ```cpp + * amEngine->AddListener(1234); // You should provide an unique ID + * ``` */ Listener(); + /** + * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. + */ explicit Listener(ListenerInternalState* state); /** - * @brief Deinitialize this Listener. + * @brief Uninitializes this `Listener`. * * Note that this does not destroy the internal state it references, - * it just removes this reference to it. To destroy the Listener, - * use Engine::RemoveListener();. + * it just removes this reference to it. + * + * To completely destroy the `Listener`, use `RemoveListener()` method + * of the `Engine` instance. + * ```cpp + * amEngine->RemoveListener(1234); // You should provide the listener ID + * ``` */ void Clear(); /** - * @brief Checks whether this Listener has been initialized. + * @brief Checks whether this `Listener` has been initialized. * - * @return bool true if this Listener has been initialized. + * @return `true` if this `Listener` is initialized, `false` otherwise. */ [[nodiscard]] bool Valid() const; /** - * @brief Gets the ID of this Listener in game. + * @brief Gets the ID of this `Listener`. * - * @return The game Listener ID. + * @return The `Listener` ID. */ [[nodiscard]] AmListenerID GetId() const; /** - * @brief Gets the velocity of the Listener. + * @brief Gets the velocity of the `Listener`. * - * @return The Listener's velocity. + * @return The listener's velocity. */ [[nodiscard]] const AmVec3& GetVelocity() const; /** - * @brief Returns the location of this Listener. + * @brief Gets the location of this `Listener`. * - * @return AmVec3 The location of this Listener. + * @return The location of this `Listener`. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Set the location of this Listener. + * @brief Sets the location of this `Listener`. * - * @param location The new location of this Listener. + * @param[in] location The new location of this `Listener`. */ void SetLocation(const AmVec3& location) const; /** - * @brief Get the direction vector of the Listener. + * @brief Gets the direction vector of the `Listener`. * * @return The direction vector. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Get the up vector of the Listener. + * @brief Gets the up vector of the `Listener`. * * @return The up vector. */ [[nodiscard]] AmVec3 GetUp() const; /** - * @brief Set the location, direction and up vector of this Listener. + * @brief Sets the location, direction and up vector of this `Listener`. * - * @param orientation The new orientation of this Listener. + * @param[in] orientation The new orientation of this `Listener`. */ void SetOrientation(const Orientation& orientation) const; /** - * @brief Get the orientation of the Listener. + * @brief Gets the orientation of the `Listener`. * - * @return The orientation of this Listener. + * @return The orientation of this `Listener`. */ [[nodiscard]] Orientation GetOrientation() const; /** - * @brief Sets the directivity and sharpness of Listener. This affects how sounds are perceived - * by the Listener. + * @brief Sets the directivity and sharpness of `Listener`. This affects how sounds are perceived + * by the `Listener`. * - * @param directivity The directivity of the listener, in the range [0, 1]. - * @param sharpness The directivity sharpness of the listener, in the range [1, +INF]. + * @param[in] directivity The directivity of the listener, in the range [0, 1]. + * @param[in] sharpness The directivity sharpness of the listener, in the range [1, +INF]. * Increasing this value increases the directivity towards the front of the listener. */ void SetDirectivity(AmReal32 directivity, AmReal32 sharpness) const; /** - * @brief Gets the directivity of sounds played by this Entity. + * @brief Gets the directivity of sounds played by this `Listener`. * * @return The directivity of sound sources. */ [[nodiscard]] AmReal32 GetDirectivity() const; /** - * @brief Gets the directivity sharpness of sounds played by this Entity. + * @brief Gets the directivity sharpness of sounds played by this `Listener`. * - * @return The directivity sharpness of sounds played by this Entity. + * @return The directivity sharpness of sounds played by this `Listener`. */ [[nodiscard]] AmReal32 GetDirectivitySharpness() const; /** - * @brief Gets the inverse matrix of the Listener. + * @brief Gets the inverse matrix of the `Listener`. * - * You can use this matrix to transform 3D global space into Listener space. + * You can use this matrix to convert locations from global space to `Listener` space. */ [[nodiscard]] const AmMat4& GetInverseMatrix() const; /** - * @brief Update the state of this Listener. + * @brief Update the state of this `Listener`. + * + * This method is called automatically by the `Engine` + * on each frames to update the internal state of the `Listener` * - * This method is called automatically by the Engine - * on each frames. + * @warning This method is for internal usage only. */ void Update() const; /** * @brief Returns the internal state of this Listener. * - * @return ListenerInternalState* + * @return The `Listener` internal state. + * + * @warning This method is for internal usage only. */ [[nodiscard]] ListenerInternalState* GetState() const; private: + /** + * @brief The internal state of the listener. + * + * @internal + */ ListenerInternalState* _state; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Log.h b/include/SparkyStudios/Audio/Amplitude/Core/Log.h index 71cb7b68..504fed48 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Log.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Log.h @@ -19,6 +19,8 @@ /** * @brief The global logger instance. + * + * @ingroup core */ #define amLogger SparkyStudios::Audio::Amplitude::Logger::GetLogger() @@ -28,6 +30,8 @@ * @param _level_ The level of the log message. * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLog(_level_, _message_, ...) \ if (amLogger != nullptr) \ @@ -44,6 +48,8 @@ * * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLogDebug(_message_, ...) amLog(Debug, _message_, ##__VA_ARGS__) @@ -52,6 +58,8 @@ * * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLogInfo(_message_, ...) amLog(Info, _message_, ##__VA_ARGS__) @@ -60,6 +68,8 @@ * * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLogWarning(_message_, ...) amLog(Warning, _message_, ##__VA_ARGS__) @@ -68,6 +78,8 @@ * * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLogError(_message_, ...) amLog(Error, _message_, ##__VA_ARGS__) @@ -76,6 +88,8 @@ * * @param _message_ The message to log. * @param ... The arguments to format the message with. + * + * @ingroup core */ #define amLogCritical(_message_, ...) amLog(Critical, _message_, ##__VA_ARGS__) @@ -85,14 +99,16 @@ namespace SparkyStudios::Audio::Amplitude * @brief The level of a log message. * * This is used to determine the importance of a log message. + * + * @ingroup core */ - enum LogMessageLevel : AmUInt8 + enum eLogMessageLevel : AmUInt8 { - eLML_DEBUG = 0, - eLML_INFO = 1, - eLML_WARNING = 2, - eLML_ERROR = 3, - eLML_CRITICAL = 4, + eLogMessageLevel_Debug = 0, ///< Debug messages. + eLogMessageLevel_Info = 1, ///< Informational messages. + eLogMessageLevel_Warning = 2, ///< Warning messages. + eLogMessageLevel_Error = 3, ///< Error messages. + eLogMessageLevel_Critical = 4, ///< Critical messages. }; /** @@ -100,21 +116,26 @@ namespace SparkyStudios::Audio::Amplitude * * Base class used to perform logging. Implementations of this class have the ability to display or store * log messages wherever they are needed. + * + * @ingroup core */ class AM_API_PUBLIC Logger { public: + /** + * @brief Default destructor. + */ virtual ~Logger() = default; /** - * @brief Sets the logger instance to use when calling @c amLogger + * @brief Sets the logger instance to use when calling `amLogger` * - * @param loggerInstance The logger instance. + * @param[in] loggerInstance The logger instance. */ static void SetLogger(Logger* loggerInstance); /** - * @brief Gets the logger instance to use when calling @c amLogger + * @brief Gets the logger instance to use when calling `amLogger` * * @return The logger instance. */ @@ -123,45 +144,45 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Logs a debug message. * - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ void Debug(const char* file, int line, const AmString& message); /** * @brief Logs an informational message. * - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ void Info(const char* file, int line, const AmString& message); /** * @brief Logs a warning message. * - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ void Warning(const char* file, int line, const AmString& message); /** * @brief Logs an error message. * - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ void Error(const char* file, int line, const AmString& message); /** * @brief Logs a critical message. * - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ void Critical(const char* file, int line, const AmString& message); @@ -169,29 +190,41 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Logs a message with the given level. * - * @param level The level of the log message. - * @param file The file where the message was logged. - * @param line The line where the message was logged. - * @param message The message to log. + * @param[in] level The level of the log message. + * @param[in] file The file where the message was logged. + * @param[in] line The line where the message was logged. + * @param[in] message The message to log. */ - virtual void Log(LogMessageLevel level, const char* file, int line, const AmString& message) = 0; + virtual void Log(eLogMessageLevel level, const char* file, int line, const AmString& message) = 0; }; /** * @brief The console logger class. * - * This class logs messages to the console. + * This class logs messages to the console or terminal. + * + * @ingroup core */ class AM_API_PUBLIC ConsoleLogger final : public Logger { public: + /** + * @brief Constructs a new console logger. + * + * @param[in] displayFileAndLine Whether to display the file and line number in the log messages. + */ explicit ConsoleLogger(bool displayFileAndLine = true); + + /** + * @brief Destructor. + */ ~ConsoleLogger() override = default; + protected: /** - * @copydoc Logger::Log + * @inherit */ - void Log(LogMessageLevel level, const char* file, int line, const AmString& message) override; + void Log(eLogMessageLevel level, const char* file, int line, const AmString& message) override; private: bool m_displayFileAndLine = true; diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Memory.h b/include/SparkyStudios/Audio/Amplitude/Core/Memory.h index d75e8fea..b66bfb5a 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Memory.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Memory.h @@ -15,6 +15,7 @@ #pragma once +#include "SparkyStudios/Audio/Amplitude/Core/Common/Platforms/UNIX/Config.h" #ifndef _AM_CORE_MEMORY_H #define _AM_CORE_MEMORY_H @@ -22,6 +23,8 @@ /** * @brief Shortcut access to the Amplitude's memory manager instance. + * + * @ingroup memory */ #define amMemory SparkyStudios::Audio::Amplitude::MemoryManager::GetInstance() @@ -30,6 +33,8 @@ * * @param _pool_ The memory pool to allocate from. * @param _size_ The size of the memory to allocate. + * + * @ingroup memory */ #define ampoolmalloc(_pool_, _size_) amMemory->Malloc(_pool_, _size_, __FILE__, __LINE__) @@ -39,6 +44,8 @@ * @param _pool_ The memory pool to deallocate from. * @param _size_ The size of the memory to allocate. * @param _alignment_ The alignment of the memory to allocate. + * + * @ingroup memory */ #define ampoolmalign(_pool_, _size_, _alignment_) amMemory->Malign(_pool_, _size_, _alignment_, __FILE__, __LINE__) @@ -48,6 +55,8 @@ * @param _pool_ The memory pool to reallocate from. Should be the same as the one used to allocate the memory. * @param _ptr_ The pointer to reallocate. * @param _size_ The new size of the memory. + * + * @ingroup memory */ #define ampoolrealloc(_pool_, _ptr_, _size_) amMemory->Realloc(_pool_, _ptr_, _size_, __FILE__, __LINE__) @@ -57,7 +66,9 @@ * @param _pool_ The memory pool to reallocate from. Should be the same as the one used to allocate the memory. * @param _ptr_ The pointer to reallocate. * @param _size_ The new size of the memory. - * @param _alignment_ The alignment of the memory to allocate. + * @param _alignment_ The alignment of the memory to reallocate. + * + * @ingroup memory */ #define ampoolrealign(_pool_, _ptr_, _size_, _alignment_) amMemory->Realign(_pool_, _ptr_, _size_, _alignment_, __FILE__, __LINE__) @@ -66,6 +77,8 @@ * * @param _pool_ The memory pool to deallocate from. * @param _ptr_ The pointer to deallocate. + * + * @ingroup memory */ #define ampoolfree(_pool_, _ptr_) amMemory->Free(_pool_, _ptr_) @@ -74,7 +87,9 @@ * * @param _size_ The size of the memory to allocate. * - * @see ampoolmalloc + * @see @ref ampoolmalloc ampoolmalloc + * + * @ingroup memory */ #define ammalloc(_size_) ampoolmalloc(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _size_) @@ -84,17 +99,21 @@ * @param _size_ The size of the memory to allocate. * @param _alignment_ The alignment of the memory to allocate. * - * @see ampoolmalign + * @see @ref ampoolmalign ampoolmalign + * + * @ingroup memory */ #define ammalign(_size_, _alignment_) ampoolmalign(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _size_, _alignment_) /** - * @brief Reallocates a block of memory from the deault memory pool. + * @brief Reallocates a block of memory from the default memory pool. * * @param _ptr_ The pointer to reallocate. * @param _size_ The new size of the memory. * - * @see ampoolrealloc + * @see @ref ampoolrealloc ampoolrealloc + * + * @ingroup memory */ #define amrealloc(_ptr_, _size_) ampoolrealloc(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _ptr_, _size_) @@ -103,9 +122,11 @@ * * @param _ptr_ The pointer to reallocate. * @param _size_ The new size of the memory. - * @param _alignment_ The alignment of the memory to allocate. + * @param _alignment_ The alignment of the memory to reallocate. + * + * @see @ref ampoolrealign ampoolrealign * - * @see ampoolrealign + * @ingroup memory */ #define amrealign(_ptr_, _size_, _alignment_) \ ampoolrealign(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _ptr_, _size_, _alignment_) @@ -115,26 +136,40 @@ * * @param _ptr_ The pointer to deallocate. * - * @see ampoolfree + * @see @ref ampoolfree ampoolfree + * + * @ingroup memory */ #define amfree(_ptr_) ampoolfree(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _ptr_) /** - * @brief Allocates memory for a new object in the Default pool using the memory manager. + * @brief Allocates memory for a new object in the given memory pool. * - * This will create a new memory allocation in the Default pool. The allocated - * memory will be freed when the object is destroyed using @a amdelete. + * This will create a new memory allocation in the given pool. The allocated + * memory will be freed when the object is destroyed using @ref ampooldelete ampooldelete. * - * @see ampooldelete + * @param _pool_ The memory pool to allocate from. + * @param _type_ The type of the object to allocate. + * @param ... Additional arguments to pass to the constructor of the object. + * + * @see @ref ampooldelete ampooldelete + * + * @ingroup memory */ #define ampoolnew(_pool_, _type_, ...) new (ampoolmalign((_pool_), sizeof(_type_), alignof(_type_))) _type_(__VA_ARGS__) /** - * @brief Deallocates a memory allocated with @a ampoolnew. + * @brief Deallocates a memory allocated with @ref ampoolnew ampoolnew. * - * This will call the object's destructor before the memory is freed. + * This will call the object's destructor before to free the memory. + * + * @param _pool_ The memory pool to deallocate from. + * @param _type_ The type of the object to deallocate. + * @param _ptr_ The pointer to the object to deallocate. + * + * @see @ref ampoolnew ampoolnew * - * @see ampoolnew + * @ingroup memory */ #define ampooldelete(_pool_, _type_, _ptr_) \ { \ @@ -149,18 +184,28 @@ * @brief Allocates memory for a new object in the Default pool using the memory manager. * * This will create a new memory allocation in the Default pool. The allocated - * memory will be freed when the object is destroyed using @a amdelete. + * memory will be freed when the object is destroyed using @ref amdelete amdelete. + * + * @param _type_ The type of the object to allocate. + * @param ... Additional arguments to pass to the constructor of the object. * - * @see amdelete + * @see @ref amdelete amdelete + * + * @ingroup memory */ #define amnew(_type_, ...) ampoolnew(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _type_, __VA_ARGS__) /** - * @brief Deallocates a memory allocated with @a amnew. + * @brief Deallocates a memory allocated with @ref amnew amnew. * * This will call the object's destructor before the memory is freed. * - * @see amnew + * @param _type_ The type of the object to deallocate. + * @param _ptr_ The pointer to the object to deallocate. + * + * @see @ref amnew amnew + * + * @ingroup memory */ #define amdelete(_type_, _ptr_) ampooldelete(SparkyStudios::Audio::Amplitude::MemoryPoolKind::Default, _type_, _ptr_) @@ -168,6 +213,8 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief Available memory pools. + * + * @ingroup memory */ enum class MemoryPoolKind : AmUInt8 { @@ -204,7 +251,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Default allocations pool. Use this when the allocated memory pool is not available. - * @note amnew use this pool to allocate memory from the memory manager. + * + * @note `amnew` use this pool to allocate memory from the memory manager. */ Default, @@ -230,6 +278,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Configures the memory management system. + * + * @ingroup memory */ struct AM_API_PUBLIC MemoryManagerConfig { @@ -279,6 +329,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Collects the statistics about the memory allocations * for a specific pool + * + * @ingroup memory */ struct AM_API_PUBLIC MemoryPoolStats { @@ -310,28 +362,46 @@ namespace SparkyStudios::Audio::Amplitude {} /** - * @brief Creates a new MemoryPoolStats object. + * @brief Creates a new `MemoryPoolStats` object. * - * @param pool The pool to get the statistics for. + * @param[in] pool The pool to get the statistics for. */ explicit MemoryPoolStats(MemoryPoolKind pool); + /** + * @brief Copy constructor. + * + * @param[in] copy The `MemoryPoolStats` object to copy from. + */ MemoryPoolStats(const MemoryPoolStats& copy); + /** + * @brief Assignment operator. + * + * @param[in] other The `MemoryPoolStats` object to assign from. + */ MemoryPoolStats& operator=(const MemoryPoolStats& other); }; #endif /** * @brief Manages memory allocations inside the engine. + * + * @ingroup memory */ class AM_API_PUBLIC MemoryManager { public: + /** + * @brief A single memory allocation. + * + * This struct describes a single memory allocation. It is used to track memory allocations made by + * the engine for each pool, and inspect memory leaks. + */ struct Allocation { /** - * @brief The memory pool kind. + * @brief The memory pool. */ MemoryPoolKind pool; @@ -355,22 +425,48 @@ namespace SparkyStudios::Audio::Amplitude */ AmUInt32 line; - explicit operator AmVoidPtr() const + /** + * @brief Explicit conversion to the address of the allocation. + * + * @return The address of the allocation. + */ + [[nodiscard]] AM_INLINE explicit operator AmVoidPtr() const { return address; } - bool operator==(const AmVoidPtr& ptr) const + /** + * @brief Checks if the address matches the provided pointer. + * + * @param[in] ptr The pointer to compare with. + * + * @return `true` if the addresses match, `false` otherwise. + */ + [[nodiscard]] AM_INLINE bool operator==(const AmVoidPtr& ptr) const { return address == ptr; } - bool operator==(const Allocation& other) const + /** + * @brief Checks if the address matches the provided pointer. + * + * @param[in] ptr The pointer to compare with. + * + * @return `true` if the addresses match, `false` otherwise. + */ + [[nodiscard]] AM_INLINE bool operator==(const Allocation& other) const { return pool == other.pool && address == other.address; } - bool operator<(const Allocation& other) const + /** + * @brief Checks if the address is less than the provided address. + * + * @param[in] other The other allocation to compare with. + * + * @return `true` if the addresses are less than, `false` otherwise. + */ + [[nodiscard]] AM_INLINE bool operator<(const Allocation& other) const { return address < other.address; } @@ -379,7 +475,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Initializes the memory manager. * - * @remarks This should be done prior to any call of GetInstance(). + * @remarks This should be done prior to any call of @ref GetInstance `GetInstance()` + * or any usage of `amMemory`. */ static void Initialize(const MemoryManagerConfig& config); @@ -391,7 +488,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks whether the memory manager is initialized. * - * @return Whether the memory manager is initialized. + * @return `true` if the memory manager is initialized, `false` otherwise. */ [[maybe_unused]] static bool IsInitialized(); @@ -401,26 +498,25 @@ namespace SparkyStudios::Audio::Amplitude static MemoryManager* GetInstance(); /** - * @brief Allocates a block of memory with the given size in the given pool. + * @brief Allocates a block of memory. * - * @param pool The memory pool to allocate from. - * @param size The size of the block to allocate. - * @param file The file in which the allocation was made. - * @param line The line in which the allocation was made. + * @param[in] pool The memory pool to allocate from. + * @param[in] size The size of the block to allocate. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. * * @return A pointer to the allocated block. */ [[nodiscard]] AmVoidPtr Malloc(MemoryPoolKind pool, AmSize size, const char* file, AmUInt32 line); /** - * @brief Allocates a block of memory with the given size and the given alignment, - * in the given pool. + * @brief Allocates an aligned block of memory. * - * @param pool The memory pool to allocate from. - * @param size The size of the block to allocate. - * @param alignment The alignment of the block to allocate. - * @param file The file in which the allocation was made. - * @param line The line in which the allocation was made. + * @param[in] pool The memory pool to allocate from. + * @param[in] size The size of the block to allocate. + * @param[in] alignment The alignment of the block to allocate. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. * * @return A pointer to the allocated block. */ @@ -429,27 +525,27 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Updates the size of a previously allocated memory. * - * @param pool The memory pool to update. - * @param address The address of the memory to update. - * @param size The new size of the memory. - * @param file The file in which the allocation was made. - * @param line The line in which the allocation was made. + * @param[in] pool The memory pool to update. + * @param[in] address The address of the memory to update. + * @param[in] size The new size of the memory. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. * - * @return A pointer to the allocated block. Maybe equal to address if the original pointer had enough memory. + * @return A pointer to the allocated block. Maybe equal to `address` if the original pointer had enough memory. */ [[nodiscard]] AmVoidPtr Realloc(MemoryPoolKind pool, AmVoidPtr address, AmSize size, const char* file, AmUInt32 line); /** * @brief Updates the size of a previously allocated aligned memory. * - * @param pool The memory pool to update. - * @param address The address of the aligned memory to update. - * @param size The new size of the aligned memory. - * @param alignment The new alignment of the aligned memory. - * @param file The file in which the allocation was made. - * @param line The line in which the allocation was made. + * @param[in] pool The memory pool to update. + * @param[in] address The address of the aligned memory to update. + * @param[in] size The new size of the aligned memory. + * @param[in] alignment The new alignment of the aligned memory. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. * - * @return A pointer to the allocated block. Maybe equal to address if the original pointer had enough memory. + * @return A pointer to the allocated block. Maybe equal to `address` if the original pointer had enough memory. */ [[nodiscard]] AmVoidPtr Realign( MemoryPoolKind pool, AmVoidPtr address, AmSize size, AmUInt32 alignment, const char* file, AmUInt32 line); @@ -457,8 +553,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Releases an allocated memory block. * - * @param pool The memory pool to release from. - * @param address The address of the memory to release. + * @param[in] pool The memory pool to release from. + * @param[in] address The address of the memory to release. */ void Free(MemoryPoolKind pool, AmVoidPtr address); @@ -472,8 +568,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the size of the given memory block. * - * @param pool The memory pool to get the size from. - * @param address The address of the memory block. + * @param[in] pool The memory pool to get the size from. + * @param[in] address The address of the memory block. * * @return The size of the given memory block. */ @@ -483,7 +579,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the name of the given memory pool. * - * @param pool The memory pool to get the name for. + * @param[in] pool The memory pool to get the name for. * * @return The name of the memory pool. */ @@ -492,15 +588,15 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the memory allocation statistics for the given pool. * - * @param pool The pool to get the statistics for. + * @param[in] pool The pool to get the statistics for. */ [[nodiscard]] const MemoryPoolStats& GetStats(MemoryPoolKind pool) const; /** - * @brief Inspect the memory manager for memory leaks. + * @brief Inspects the memory manager for memory leaks. * - * @note This function is most useful after the engine has been deinitialized. Calling it before may just - * report a lot of false positives (allocated memories still in use). + * @tip This function is most useful after the engine has been deinitialized. Calling it before may just + * report a lot of false positives (allocated memories which are still in use). * * @return A string containing a report for the detected memory leaks. */ @@ -525,29 +621,70 @@ namespace SparkyStudios::Audio::Amplitude * * That allocation will be restricted to the current scope, and will be freed * automatically when the scope ends. + * + * @ingroup memory */ class AM_API_PUBLIC ScopedMemoryAllocation { public: + /** + * @brief Default constructor. + */ ScopedMemoryAllocation() = default; + /** + * @brief Creates a new new scoped memory allocation. + * + * @param[in] pool The memory pool to allocate from. + * @param[in] size The size of the block to allocate. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. + */ ScopedMemoryAllocation(MemoryPoolKind pool, AmSize size, const char* file, AmUInt32 line); + + /** + * @brief Creates a new new scoped aligned memory allocation. + * + * @param[in] pool The memory pool to allocate from. + * @param[in] size The size of the block to allocate. + * @param[in] alignment The alignment of the block to allocate. + * @param[in] file The file in which the allocation was made. + * @param[in] line The line in which the allocation was made. + */ ScopedMemoryAllocation(MemoryPoolKind pool, AmSize size, AmUInt32 alignment, const char* file, AmUInt32 line); + /** + * @brief Releases the allocated memory. + */ ~ScopedMemoryAllocation(); + /** + * @brief Gets the allocated memory address. + * + * @return The allocated memory address. + */ template - [[nodiscard]] T* PointerOf() const + [[nodiscard]] AM_INLINE T* PointerOf() const { return reinterpret_cast(_address); } + /** + * @brief Converts the allocated memory address to a different type. + * + * @return The allocated memory address converted to the specified type. + */ template, bool> = false> - [[nodiscard]] T As() const + [[nodiscard]] AM_INLINE T As() const { return reinterpret_cast(_address); } + /** + * @brief Gets the allocated memory address. + * + * @return The allocated memory address. + */ [[nodiscard]] AM_INLINE AmVoidPtr Address() const { return _address; @@ -558,18 +695,41 @@ namespace SparkyStudios::Audio::Amplitude void* _address = nullptr; }; + /** + * @brief Deleter for unique pointers. + * + * @tparam Pool The memory pool to delete the pointer from. + * @tparam T The type of the pointer to delete. + * + * @note This deleter uses the `ampooldelete` function to delete the pointer. + * It is templated to ensure that the correct pool is used. + * This allows for a single implementation of the deleter for all pointer types. + * The `std::unique_ptr` will automatically call this deleter when the pointer is deleted. + * + * @see ampooldelete, AmUniquePtr + * + * @ingroup memory + */ template struct am_delete { constexpr am_delete() noexcept = default; - AM_INLINE void operator()(T * asset) const noexcept + AM_INLINE void operator()(T* ptr) const noexcept { static_assert(!std::is_void_v, "Cannot delete a void pointer."); - ampooldelete(Pool, T, asset); + ampooldelete(Pool, T, ptr); } }; + /** + * @brief Unique pointer type. + * + * @tparam Pool The memory pool to allocate the pointer from. + * @tparam T The type of the pointer to allocate. + * + * @ingroup memory + */ template using AmUniquePtr = std::unique_ptr>; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Playback/Bus.h b/include/SparkyStudios/Audio/Amplitude/Core/Playback/Bus.h index 12ddf623..74c6e90c 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Playback/Bus.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Playback/Bus.h @@ -24,33 +24,36 @@ namespace SparkyStudios::Audio::Amplitude class BusInternalState; /** - * @brief An object representing one node in the tree of buses. - * Buses are used to adjust a set of channel gains in tandem. + * @brief An object representing one node in the tree of buses. Buses are used to adjust a set of channel gains in tandem. * - * The Bus class is a lightweight reference to a BusInternalState object which - * is managed by the Engine. There is always at least one bus, the master bus, + * The `Bus` class is a lightweight reference to a `BusInternalState` object which + * is managed by the Engine. There is always at least one bus, the **master** bus, * and any number of additional buses may be defined as well. Each bus can be - * thought as a node in the tree. The gain on a Bus is applied to all child buses as well. + * thought as a node in the tree. The gain on a `Bus` is applied to all child buses as well. + * + * @ingroup engine */ class AM_API_PUBLIC Bus { public: /** - * @brief Creates an uninitialized @c Bus. + * @brief Creates an uninitialized `Bus`. * * An uninitialized Bus cannot set or get any of it's fields. - * To initialize the Listener, use Engine::AddListener();. */ - Bus() - : _state(nullptr) - {} + Bus(); - explicit Bus(BusInternalState* state) - : _state(state) - {} + /** + * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. + */ + explicit Bus(BusInternalState* state); /** - * @brief Uninitializes this @c Bus. + * @brief Uninitializes this `Bus`. * * Note that this does not destroy the internal state it references, * it just removes this reference to it. @@ -58,83 +61,88 @@ namespace SparkyStudios::Audio::Amplitude void Clear(); /** - * @brief Checks whether this @c Bus has been initialized. + * @brief Checks whether this `Bus` has been initialized. * - * @return @c true if this @c Bus has been initialized. + * @return `true` if this `Bus` has been initialized. */ [[nodiscard]] bool Valid() const; /** - * @brief Gets the unique ID of this @c Bus. + * @brief Gets the unique ID of this `Bus`. * * @return The bus unique ID. */ [[nodiscard]] AmBusID GetId() const; /** - * @brief Gets the name of this @c Bus. + * @brief Gets the name of this `Bus`. * * @return The bus name. */ - [[nodiscard]] const std::string& GetName() const; + [[nodiscard]] const AmString& GetName() const; /** - * @brief Sets the gain of this @c Bus. + * @brief Sets the gain of this `Bus`. * - * @param gain The new gain value. + * @param[in] gain The new gain value. */ void SetGain(AmReal32 gain) const; /** - * @brief Returns the user specified gain on this @c Bus. + * @brief Returns the user specified gain on this `Bus`. * * @return The user specified gain. */ [[nodiscard]] AmReal32 GetGain() const; /** - * @brief Fades to \c gain over \c duration milliseconds. + * @brief Fades to `gain` over `duration` milliseconds. * - * @param gain The gain value to fade to. - * @param duration The amount of time in milliseconds to take to reach the desired gain. + * @param[in] gain The gain value to fade to. + * @param[in] duration The amount of time in milliseconds to take to reach the desired gain. */ void FadeTo(AmReal32 gain, AmTime duration) const; /** - * @brief Returns the final calculated gain on this @c Bus. + * @brief Returns the final calculated gain on this `Bus`. * * @note The final gain of a bus is the product of the gain specified in the bus - * definition file, the gain specified by the user, and the final gain of the - * parent bus. + * definition file, with the gain specified by the user, and with the final gain + * of the parent bus. * * @return The final calculated gain. */ [[nodiscard]] AmReal32 GetFinalGain() const; /** - * @brief Sets the muted state of this @c Bus. + * @brief Sets the muted state of this `Bus`. * - * @param mute The muted state. + * @param[in] mute The muted state. */ void SetMute(bool mute) const; /** - * @brief Returns whether this @c Bus is muted. + * @brief Returns whether this `Bus` is muted. * - * @return @c true if this Bus is muted, @c false otherwise. + * @return `true` if this Bus is muted, `false` otherwise. */ [[nodiscard]] bool IsMuted() const; /** - * @brief Returns the internal state of this @c Bus. + * @brief Returns the internal state of this `Bus`. * - * @note This is not meant to be used by the user. + * @warning This method is only for internal usage. * * @return The bus internal state. */ [[nodiscard]] BusInternalState* GetState() const; private: + /** + * @brief Internal state of the Bus. + * + * @internal This field is not exposed to the public API. + */ BusInternalState* _state; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Playback/Channel.h b/include/SparkyStudios/Audio/Amplitude/Core/Playback/Channel.h index ab638e42..3edf7227 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Playback/Channel.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Playback/Channel.h @@ -27,162 +27,190 @@ namespace SparkyStudios::Audio::Amplitude { class ChannelInternalState; + /** + * @brief Enumerates the playback states for a `Channel`. + * + * @ingroup engine + */ enum class ChannelPlaybackState : AmUInt8 { - Stopped = 0, - Playing = 1, - FadingIn = 2, - FadingOut = 3, - SwitchingState = 4, - Paused = 5, + Stopped = 0, ///< The channel is stopped and not rendering audio. + Playing = 1, ///< The channel is playing audio. + FadingIn = 2, ///< The channel has just been played or resumed and is fading in to the `Playing` state. + FadingOut = 3, ///< The channel has just been stopped or paused and is fading out to the `Stopped` or `Paused` state. + SwitchingState = 4, ///< The channel is updating the value of his linked switch state. + Paused = 5, ///< The channel is paused. }; + /** + * @brief Enumerates the events triggered by a `Channel` during playback. + * + * @ingroup engine + */ enum class ChannelEvent : AmUInt8 { - Begin = 0, - End = 1, - Resume = 2, - Pause = 3, - Stop = 4, - Loop = 5 + Begin = 0, ///< The playback of the channel has started. + End = 1, ///< The playback of the channel has ended. + Resume = 2, ///< The playback of the channel has resumed after being paused. + Pause = 3, ///< The playback of the channel has been paused. + Stop = 4, ///< The playback of the channel has been stopped. + Loop = 5 ///< The playback of the channel has looped. }; /** * @brief An object that represents a single channel of audio. * - * The Channel class is a lightweight reference to a ChannelInternalState object - * which is managed by the Engine. Multiple Channel objects may point to the same + * The `Channel` class is a lightweight reference to a `ChannelInternalState` object + * which is managed by the Engine. Multiple channels may point to the same * underlying data. + * + * @ingroup engine */ class AM_API_PUBLIC Channel { public: /** - * @brief Construct an uninitialized Channel. + * @brief Construct an uninitialized `Channel`. * - * An uninitialized Channel cannot have its data set or queried. - * To initialize the Channel, use Engine::PlaySound();. + * An uninitialized `Channel` cannot have its data set or queried. */ Channel(); + /** + * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. + */ explicit Channel(ChannelInternalState* state); - Channel(const Channel& other); - /** - * @brief Uninitializes this Channel. + * @brief Uninitializes this `Channel`. * * Note that this does not stop the audio or destroy the internal * state it references, it just removes this reference to it. - * To stop the Channel, use Channel::Stop();. */ void Clear(); /** - * @brief Checks whether this Channel has been initialized. + * @brief Checks whether this `Channel` has been initialized. * - * @return true if this Channel has been initialized. + * @return `true` if this `Channel` has been initialized. */ [[nodiscard]] bool Valid() const; /** - * @brief Gets the ID of this @c Channel. + * @brief Gets the ID of this `Channel`. * - * @return The ID of this @c Channel. + * @return The ID of this `Channel`. */ [[nodiscard]] AmUInt64 GetId() const; /** - * @brief Checks if the sound associated to this @c Channel is playing. + * @brief Checks if the sound associated to this `Channel` is playing. * * @return Whether the channel is currently playing. */ [[nodiscard]] bool Playing() const; /** - * @brief Stops a channel. + * @brief Stops the `Channel`. * - * Stops this channel from playing. A sound will stop on its own if its not set - * to loop. Looped audio must be explicitly stopped. + * A sound will stop on its own if its not set to loop. Looped audio must be explicitly stopped. * - * @param duration The fade out duration before to stop the channel. + * @param[in] duration The fade out duration before to stop the channel. */ void Stop(AmTime duration = kMinFadeDuration) const; /** - * @brief Pauses a channel. + * @brief Pauses the `Channel`. * - * Pauses this channel. A paused channel may be resumed where it left off. + * A paused channel may be resumed where it left off. * - * @param duration The fade out duration before to pause the channel. + * @param[in] duration The fade out duration before to pause the channel. */ void Pause(AmTime duration = kMinFadeDuration) const; /** - * @brief Resumes a paused channel. + * @brief Resumes the `Channel`. * - * Resumes this channel. If this channel was paused it will continue where it - * left off. + * If this channel was paused it will continue where it left off. * - * @param duration The fade in duration after resuming the channel. + * @param[in] duration The fade in duration after resuming the channel. */ void Resume(AmTime duration = kMinFadeDuration) const; /** - * @brief Gets the location of this Channel. + * @brief Gets the location of this `Channel`. * * If the audio on this channel is not set to be Positional, this method will * return an invalid location. * - * @return The location of this Channel. + * @return The location of this `Channel`. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Sets the location of this Channel. + * @brief Sets the location of this `Channel`. * * If the audio on this channel is not set to be Positional, this method * does nothing. * - * @param location The new location of the Channel. + * @param[in] location The new location of the `Channel`. */ void SetLocation(const AmVec3& location) const; /** - * @brief Sets the gain on this Channel. + * @brief Sets the gain on this `Channel`. * - * @param gain The new gain value. + * @param[in] gain The new gain value. */ void SetGain(AmReal32 gain) const; /** - * @brief Returns the gain on this Channel. + * @brief Returns the gain on this `Channel`. * - * @return Returns the gain. + * @return The channel's gain. */ [[nodiscard]] AmReal32 GetGain() const; /** - * @brief Returns the playback state of this Channel. + * @brief Returns the playback state of this `Channel`. + * + * @return A `ChannelPlaybackState` enumeration value representing the current state of the `Channel`. */ [[nodiscard]] ChannelPlaybackState GetPlaybackState() const; /** - * @brief Returns the entity associated with this Channel. + * @brief Returns the `Entity` associated with this `Channel`. * - * @return The entity associated with this Channel. + * @note If no `Entity` is associated with this `Channel`, this method will return an + * uninitialized `Entity` object. You should check if the entity is valid before using it. + * + * @return The entity associated with this `Channel`. + * + * @see Entity */ [[nodiscard]] Entity GetEntity() const; /** - * @brief Returns the listener associated with this Channel. + * @brief Returns the `Listener` associated with this `Channel`. + * + * @note If no `Listener` is associated with this `Channel`, this method will return an + * uninitialized `Listener` object. You should check if the listener is valid before using it. + * + * @return The listener associated with this `Channel`. * - * @return The listener associated with this Channel. + * @see Listener */ [[nodiscard]] Listener GetListener() const; /** - * @brief Returns the room associated with this Channel. + * @brief Returns the `Room` associated with this `Channel`. + * + * @note If no `Room` is associated with this `Channel`, this method will return an + * uninitialized `Room` object. You should check if the room is valid before using it. * * @return The room associated with this Channel. */ @@ -192,25 +220,52 @@ namespace SparkyStudios::Audio::Amplitude * @brief Returns the internal state of this Channel. * * @return The internal state of this Channel. + * + * @warning This method is for internal usage only. */ [[nodiscard]] ChannelInternalState* GetState() const; /** * @brief Registers a callback for a channel event. * - * @param event The channel event. - * @param callback The callback function. - * @param userData The user data to pass to the callback. + * @param[in] event The channel event. + * @param[in] callback The callback function. + * @param[in] userData The user data to pass to the callback. + * + * @see ChannelEvent + * @see ChannelEventCallback */ void On(ChannelEvent event, ChannelEventCallback callback, void* userData = nullptr) const; private: + /** + * @brief Private constructor to wrap an existing state. + * + * @internal + */ Channel(ChannelInternalState* state, AmUInt64 id); + /** + * @brief Checks if the internal state ID is valid. + * + * @return `true` if the internal state ID is valid. + * + * @internal + */ [[nodiscard]] bool IsValidStateId() const; + /** + * @brief The internal state of the channel. + * + * @internal + */ ChannelInternalState* _state; + /** + * @brief The ID of the channel. + * + * @internal + */ AmUInt64 _stateId; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Playback/ChannelEventListener.h b/include/SparkyStudios/Audio/Amplitude/Core/Playback/ChannelEventListener.h index cd20708d..570f292c 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Playback/ChannelEventListener.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Playback/ChannelEventListener.h @@ -27,10 +27,19 @@ namespace SparkyStudios::Audio::Amplitude class ChannelInternalState; /** - * @brief The event info passed to the event listener. + * @brief The event info passed to the channel event listener. + * + * @ingroup engine */ struct ChannelEventInfo { + /** + * @brief Constructor. + * + * @param[in] source The source of the event. + * + * @warning This constructor is for internal usage only. + */ explicit ChannelEventInfo(ChannelInternalState* source); /** @@ -44,6 +53,11 @@ namespace SparkyStudios::Audio::Amplitude void* m_userData; }; + /** + * @brief A callback function for handling channel events. + * + * @ingroup engine + */ typedef std::function ChannelEventCallback; /** @@ -51,38 +65,73 @@ namespace SparkyStudios::Audio::Amplitude * * Event handlers are registered to the event listener through a callback to receive * event notifications. + * + * @ingroup engine */ class AM_API_PUBLIC ChannelEventListener { public: + /** + * @brief Initializes a new channel event listener. + */ ChannelEventListener(); + + /** + * @brief Destroys the channel event listener. + */ ~ChannelEventListener(); /** * @brief Registers a custom callback to this event listener. * - * @param callback The event callback. - * @param userData The additional data to pass to the handler when this listener receive the event. + * @param[in] callback The event callback. + * @param[in] userData The additional data to pass to the handler when this listener receive the event. */ void Add(const ChannelEventCallback& callback, void* userData = nullptr); /** * @brief Executes the event by calling all the registered event handlers. * - * @param channel The channel which have triggered the event. + * @param[in] channel The channel which have triggered the event. + * + * @warning This method is for internal usage only. */ void Call(ChannelInternalState* channel); private: + /** + * @brief Adds a custom callback to the internal list of handlers. + * + * @param[in] callback The event callback. + * @param[in] userData The additional data to pass to the handler when this listener receive the event. + * + * @internal + */ void AddInternal(const ChannelEventCallback& callback, void* userData = nullptr); + + /** + * @brief Removes all the custom callbacks from the internal list of handlers. + * + * @internal + */ void CleanLinks(); + /** + * @brief Internal structure to hold a callback and its user data. + * + * @internal + */ struct HandlerInstance { - ChannelEventCallback m_callback; - void* m_userData; + ChannelEventCallback m_callback; ///< The callback function + void* m_userData; ///< The user data }; + /** + * @brief Internal list of registered event handlers. + * + * @internal + */ std::list _handlers; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/RefCounter.h b/include/SparkyStudios/Audio/Amplitude/Core/RefCounter.h index 02e0775d..237f98f4 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/RefCounter.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/RefCounter.h @@ -23,12 +23,14 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief Holds the number of references to an object. + * + * @ingroup core */ class AM_API_PUBLIC RefCounter { public: /** - * @brief Constructs a new RefCounter. + * @brief Constructs a new `RefCounter`. * * This initializes the internal counter to 0. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Room.h b/include/SparkyStudios/Audio/Amplitude/Core/Room.h index cab097cf..db11a28f 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Room.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Room.h @@ -26,14 +26,16 @@ namespace SparkyStudios::Audio::Amplitude class RoomInternalState; /** - * @brief Defines the material type of a @c Room wall. + * @brief Defines the material type of a `Room` wall. * * Use this enum when you want use predefined absorption coefficients for a wall. * Note that the predefined coefficients are only for reference, and may not be * accurate for your specific use case. * - * You can use the @c RoomMaterialType::Custom to define a custom material. This + * You can use the `RoomMaterialType::Custom` to define a custom material. This * will need you to provide the absorption coefficients yourself. + * + * @ingroup engine */ enum class RoomMaterialType : AmUInt8 { @@ -56,7 +58,9 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Enumerates the walls of a @c Room. + * @brief Enumerates the walls of a `Room`. + * + * @ingroup engine */ enum class RoomWall : AmUInt8 { @@ -99,21 +103,23 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Represents the material of a @c Room wall. + * @brief Represents the material of a `Room` wall. + * + * @ingroup engine */ struct AM_API_PUBLIC RoomMaterial { /** - * @brief Constructs a new @c RoomMaterial. + * @brief Constructs a new `RoomMaterial`. * - * @note This constructor initializes a @c RoomMaterialType::Custom material. + * @note This constructor initializes a `RoomMaterialType`::Custom material. */ RoomMaterial(); /** - * @brief Constructs a new predefined @c RoomMaterial. + * @brief Constructs a new predefined `RoomMaterial`. * - * @param type The type of the material. + * @param[in] type The type of the material. */ explicit RoomMaterial(RoomMaterialType type); @@ -129,132 +135,156 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Represents a physical space where sound waves can propagate. Any sound source within the room will be affected - * by the room's properties, and got applied early reflections and reverberation effects. + * @brief Represents a physical space where sound waves can propagate. + * + * Any sound source within the room will be affected by the room's properties, + * and got applied early reflections and reverberation effects. * - * @note This class is a lightweight wrapper around the internal @c RoomInternalState class. + * This class is a lightweight wrapper around the internal `RoomInternalState` class. + * + * @ingroup engine */ class AM_API_PUBLIC Room { public: /** - * @brief Creates an uninitialized @c Room. + * @brief Creates an uninitialized `Room`. + * + * An uninitialized `Room` doesn't affect sound sources. * - * @note An uninitialized @c Room doesn't affect sound sources. + * To create an initialized `Room`, use the `AddRoom()` method of the + * `Engine` instance. + * ```cpp + * amEngine->AddRoom(1234); // You should provide an unique ID + * ``` */ Room(); /** * @brief Creates a wrapper instance over the provided state. + * + * @param[in] state The internal state to wrap. + * + * @warning This constructor is for internal usage only. */ explicit Room(RoomInternalState* state); /** - * @brief Uninitializes this @c Room. + * @brief Uninitializes this `Room`. * - * @note This doesn't destroy the internal state it references, + * This doesn't destroy the internal state it references, * it just removes this reference to it. + * + * To completely destroy the `Room`, use `RemoveRoom()` method + * of the `Engine` instance. + * ```cpp + * amEngine->RemoveRoom(1234); // You should provide the room ID + * ``` */ void Clear(); /** - * @brief Checks whether this @c Room has been initialized. + * @brief Checks whether this `Room` has been initialized. * - * @return @c true if this @c Room has been initialized with a + * @return `true` if this `Room` has been initialized with a * valid state. */ [[nodiscard]] bool Valid() const; /** - * @brief Returns the unique ID of this @c Room. + * @brief Returns the unique ID of this `Room`. * - * @return The @c Room unique ID. + * @return The `Room` unique ID. */ [[nodiscard]] AmRoomID GetId() const; /** - * @brief Sets the location @c Room. + * @brief Sets the location `Room`. * - * @param location The new location. + * @param[in] location The new location. */ void SetLocation(const AmVec3& location) const; /** - * @brief Gets the current location of this @c Room. + * @brief Gets the current location of this `Room`. * - * @return The current location of this @c Room. + * @return The current location of this `Room`. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Sets the orientation of this @c Room. + * @brief Sets the orientation of this `Room`. * - * @param orientation The new orientation. + * @param[in] orientation The new orientation. */ void SetOrientation(const Orientation& orientation) const; /** - * @brief Gets the current orientation of this @c Room. + * @brief Gets the current orientation of this `Room`. * - * @return The current orientation of this @c Room. + * @return The current orientation of this `Room`. */ [[nodiscard]] const Orientation& GetOrientation() const; /** - * @brief Gets the direction vector of this @c Room. + * @brief Gets the direction vector of this `Room`. * * @return The direction (forward) vector. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Gets the up vector of this @c Room. + * @brief Gets the up vector of this `Room`. * * @return The up vector. */ [[nodiscard]] AmVec3 GetUp() const; /** - * @brief Sets the shape's dimensions of this @c Room. + * @brief Sets the shape's dimensions of this `Room`. + * + * @param[in] dimensions The new dimensions. */ void SetDimensions(AmVec3 dimensions) const; /** - * @brief Sets the shape representing this @c Room. + * @brief Sets the shape representing this `Room`. + * + * @param[in] shape The new shape. */ void SetShape(const BoxShape& shape) const; /** - * @brief Gets the shape representing this @c Room. + * @brief Gets the shape representing this `Room`. * - * @return The @c Room shape. + * @return The `Room` shape. */ [[nodiscard]] const BoxShape& GetShape() const; /** - * @brief Sets the material of a specific wall of this @c Room. + * @brief Sets the material of a specific wall of this `Room`. * - * @param wall The wall to set the material for. - * @param material The new material. + * @param[in] wall The wall to set the material for. + * @param[in] material The new material. */ void SetWallMaterial(RoomWall wall, const RoomMaterial& material) const; /** - * @brief Sets the material of all walls of this @c Room. + * @brief Sets the material of all walls of this `Room`. * - * @param material The new material. + * @param[in] material The new material. */ void SetAllWallMaterials(const RoomMaterial& material) const; /** - * @brief Sets the material of each wall of this @c Room. + * @brief Sets the material of each wall of this `Room`. * - * @param leftWallMaterial The material for the left wall. - * @param rightWallMaterial The material for the right wall. - * @param floorMaterial The material for the floor. - * @param ceilingMaterial The material for the ceiling. - * @param frontWallMaterial The material for the front wall. - * @param backWallMaterial The material for the back wall. + * @param[in] leftWallMaterial The material for the left wall. + * @param[in] rightWallMaterial The material for the right wall. + * @param[in] floorMaterial The material for the floor. + * @param[in] ceilingMaterial The material for the ceiling. + * @param[in] frontWallMaterial The material for the front wall. + * @param[in] backWallMaterial The material for the back wall. */ void SetWallMaterials( const RoomMaterial& leftWallMaterial, @@ -265,61 +295,69 @@ namespace SparkyStudios::Audio::Amplitude const RoomMaterial& backWallMaterial) const; /** - * @brief Gets the material of a specific wall of this @c Room. + * @brief Gets the material of a specific wall of this `Room`. * - * @param wall The wall to get the material for. + * @param[in] wall The wall to get the material for. * * @return The material of the specified wall. */ [[nodiscard]] const RoomMaterial& GetWallMaterial(RoomWall wall) const; /** - * @brief Sets the gain of the early reflections of sound sources - * of this room. + * @brief Sets the room effects gain. * - * @param gain The gain applied to early reflections of sound sources. + * @param[in] gain The gain applied to early reflections and reverberations effects. */ void SetGain(AmReal32 gain) const; /** - * @brief Gets the early reflections gain. + * @brief Gets the room effects gain. * - * @return The early reflections gain. + * @return The room effects gain. */ [[nodiscard]] AmReal32 GetGain() const; /** - * @brief Gets the volume of the @c Room in m3. + * @brief Gets the volume of the `Room` in m3. * - * @return The volume of the room. + * @return The volume of the room's shape. */ [[nodiscard]] AmReal32 GetVolume() const; /** - * @brief Gets the surface area of a specific wall of this @c Room. + * @brief Gets the surface area of a specific wall of this `Room`. * - * @param wall The wall to get the surface area for. + * @param[in] wall The wall to get the surface area for. * * @return The surface area of the specified wall. */ [[nodiscard]] AmReal32 GetSurfaceArea(RoomWall wall) const; /** - * @brief Update the state of this @c Room. + * @brief Updates the state of this `Room`. * * This method is called automatically by the Engine - * on each frames. + * on each frames to update the internal state of the `Room` + * + * @warning This method is for internal usage only. */ void Update() const; /** - * @brief Gets the internal state of the @c Room. + * @brief Gets the internal state of the `Room`. * - * @note This method is intended for internal usage only. + * @return The `Room` internal state. + * + * @warning This method is for internal usage only. */ [[nodiscard]] RoomInternalState* GetState() const; private: + /** + * @brief The internal state of the room. + * + * @internal + */ RoomInternalState* _state; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Thread.h b/include/SparkyStudios/Audio/Amplitude/Core/Thread.h index 5500867d..3390c62a 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Thread.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Thread.h @@ -31,6 +31,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The AmThreadFunction signature is used to create threads. + * + * @ingroup core */ typedef void (*AmThreadFunction)(AmVoidPtr param); @@ -46,78 +48,105 @@ namespace SparkyStudios::Audio::Amplitude * A mutex is an object that a thread can acquire, preventing other * threads from acquiring it. * - * To acquire the mutex ownership, you should use LockMutex() with - * the mutex handle as parameter. To release the ownership, use UnlockMutex() + * To acquire the mutex ownership, you should use @ref LockMutex `LockMutex()` with + * the mutex handle as parameter. To release the ownership, use @ref UnlockMutex `UnlockMutex()` * with the mutex handle as parameter. + * + * @param[in] spinCount The number of times the mutex should spin before checking if it's available. + * + * @ingroup core */ AM_API_PUBLIC AmMutexHandle CreateMutex(AmUInt64 spinCount = 100); /** * @brief Destroys a mutex object. * - * @param handle The mutex object handle. + * @param[in] handle The mutex object handle. + * + * @ingroup core */ AM_API_PUBLIC void DestroyMutex(AmMutexHandle handle); /** * @brief Takes ownership of a mutex. * - * @param handle The mutex object handle. + * @param[in] handle The mutex object handle. + * + * @ingroup core */ AM_API_PUBLIC void LockMutex(AmMutexHandle handle); /** * @brief Releases ownership of a mutex. * - * @param handle The mutex object handle. + * @param[in] handle The mutex object handle. + * + * @ingroup core */ AM_API_PUBLIC void UnlockMutex(AmMutexHandle handle); /** * @brief Creates a new thread. * - * @param threadFunction The function to run in the thread. - * @param parameter An optional shared data to pass to the thread + * @param[in] threadFunction The function to run in the thread. + * @param[in] parameter An optional shared data to pass to the thread + * + * @ingroup core */ AM_API_PUBLIC AmThreadHandle CreateThread(AmThreadFunction threadFunction, AmVoidPtr parameter = nullptr); /** * @brief Makes the calling thread sleep for the given amount of milliseconds. * - * @param milliseconds The amount of time the calling thread should sleep. + * @param[in] milliseconds The amount of time the calling thread should sleep. + * + * @ingroup core */ AM_API_PUBLIC void Sleep(AmInt32 milliseconds); /** * @brief Waits for the given thread to stop. * - * @param thread The handle of the thread to wait. + * @param[in] thread The handle of the thread to wait. + * + * @ingroup core */ AM_API_PUBLIC void Wait(AmThreadHandle thread); /** * @brief Manually stops a thread execution. * - * @param thread The handle of the thread to stop. + * @param[in] thread The handle of the thread to stop. + * + * @ingroup core */ AM_API_PUBLIC void Release(AmThreadHandle& thread); /** * @brief Gets the total execution time in milliseconds for the calling thread. + * + * @ingroup core */ AM_API_PUBLIC AmUInt64 GetTimeMillis(); /** * @brief Gets the handle of the calling thread. + * + * @ingroup core */ AM_API_PUBLIC AmThreadID GetCurrentThreadId(); /** * @brief Base class for pool tasks. + * + * @ingroup core */ class AM_API_PUBLIC PoolTask { public: + /** + * @brief Default destructor. + */ virtual ~PoolTask() = default; /** @@ -130,13 +159,16 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the task is ready to be picked by the pool scheduler. - * @return @c true if the task is ready @c false otherwise. + * + * @return `true` if the task is ready, `false` otherwise. */ virtual bool Ready(); }; /** * @brief A pool task that allows a thread to wait until it finishes. + * + * @ingroup core */ class AM_API_PUBLIC AwaitablePoolTask : public PoolTask { @@ -145,7 +177,7 @@ namespace SparkyStudios::Audio::Amplitude ~AwaitablePoolTask() override = default; /** - * @copydoc PoolTask::Work + * @inherit */ void Work() final; @@ -161,7 +193,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Makes the calling thread wait for this task to finish. - * @param duration The maximum amount of time to wait in milliseconds. + * + * @param[in] duration The maximum amount of time to wait in milliseconds. */ bool Await(AmUInt64 duration); @@ -176,8 +209,10 @@ namespace SparkyStudios::Audio::Amplitude * The Pool tasks scheduler can pick and run pool tasks on several multiple * threads. The number of threads is defined at initialization. * - * The maximum number of tasks the pool can manage is defined by the @c AM_MAX_THREAD_POOL_TASKS - * macro. The default value is @c 1024 + * The maximum number of tasks the pool can manage is defined by the `AM_MAX_THREAD_POOL_TASKS` + * macro. The default value is `1024` + * + * @ingroup core */ class AM_API_PUBLIC Pool { @@ -187,45 +222,55 @@ namespace SparkyStudios::Audio::Amplitude */ Pool(); - // Waits for the threads to finish. Work may be unfinished. + /** + * @brief Destructor. + * + * It waits for the threads to finish. Work may be unfinished. + */ ~Pool(); /** - * @brief Initialize and run thread pool. + * @brief Initializes and run thread pool. * - * @param threadCount The number of thread in the pool. For thread count 0, work is done - * at @c AddTask call in the calling thread. + * @param[in] threadCount The number of threads in the pool. For thread count 0, work is done + * at @ref AddTask `AddTask()` call in the calling thread. */ void Init(AmUInt32 threadCount); /** * @brief Add a task to the tasks list. * - * @param task The PoolTask to add. The task is not automatically deleted when the work is done. + * @param[in] task The `PoolTask` to add. The task is not automatically deleted when the work is done. */ void AddTask(const std::shared_ptr& task); /** * @brief Called from worker thread to get a new task. * - * @note This method is called internally, and should not be called in user code. + * @warning This method is called internally, and should not be called in user code. * - * @return The next PoolTask to execute, or nullptr if no task is available. + * @return The next `PoolTask` to execute, or `nullptr` if no task is available. */ std::shared_ptr GetWork(); /** * @brief Gets the number of threads this pool is using. + * + * @return The total number of threads in the pool. */ [[nodiscard]] AmUInt32 GetThreadCount() const; /** * @brief Indicates that the pool is running. + * + * @return `true` if the pool is running, `false` otherwise. */ [[nodiscard]] bool IsRunning() const; /** * @brief Indicates that has tasks pending. + * + * @return `true` if there are tasks pending, `false` otherwise. */ [[nodiscard]] bool HasTasks() const; diff --git a/include/SparkyStudios/Audio/Amplitude/Core/Version.h b/include/SparkyStudios/Audio/Amplitude/Core/Version.h index b8d174c2..58f8edc0 100644 --- a/include/SparkyStudios/Audio/Amplitude/Core/Version.h +++ b/include/SparkyStudios/Audio/Amplitude/Core/Version.h @@ -21,8 +21,10 @@ /** * @brief Gets the current Amplitude SDK version. + * + * @ingroup core */ -#define amVersion SparkyStudios::Audio::Amplitude::Version() +#define amVersion SparkyStudios::Audio::Amplitude::GetVersion() #define AM_VERSION_MAJOR 1 #define AM_VERSION_MINOR 0 @@ -32,6 +34,8 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief A structure containing the version number of the library. + * + * @ingroup core */ struct Version { @@ -59,9 +63,11 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the version. * - * @return The version. + * @return The current SDK version. + * + * @ingroup core */ - AM_API_PUBLIC const struct Version& Version(); + AM_API_PUBLIC const struct Version& GetVersion(); } // namespace SparkyStudios::Audio::Amplitude #endif // _AM_CORE_VERSION_H diff --git a/include/SparkyStudios/Audio/Amplitude/DSP/AudioConverter.h b/include/SparkyStudios/Audio/Amplitude/DSP/AudioConverter.h index 342766c2..ef78e9c9 100644 --- a/include/SparkyStudios/Audio/Amplitude/DSP/AudioConverter.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/AudioConverter.h @@ -25,14 +25,17 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Allow converting audio buffers between different sample rates and channel counts. * - * @note This class uses the @c Resampler class to perform sample rate conversion. - * @note Only mono to stereo or vice versa conversions are supported. + * @note This class uses the `Resampler` class to perform sample rate conversion. + * + * @note Only mono to stereo or vice versa conversions are currently supported. + * + * @ingroup dsp */ class AudioConverter final { public: /** - * @brief Store conversion settings for an @c AudioConverter instance. + * @brief Store conversion settings for an `AudioConverter` instance. */ struct Settings { @@ -62,50 +65,51 @@ namespace SparkyStudios::Audio::Amplitude */ AudioConverter(); + /** + * @brief Destroys the instance and release associated resources. + */ ~AudioConverter(); /** * @brief Initializes the audio converter with the given conversion settings. * - * @param settings The conversion settings. + * @param[in] settings The conversion settings. * - * @return @c true if the initialization was successful, @c false otherwise. + * @return `true` if the initialization was successful, `false` otherwise. */ bool Configure(const Settings& settings); /** * @brief Converts the audio buffer from the source sample rate and channel count to the target sample rate and channel count. * - * @param input The source audio buffer. - * @param inputFrames The number of frames to process in the input audio buffer. - * @param output The target audio buffer to store the converted audio. - * @param outputFrames The number of frames to process in the target audio buffer. + * @param[in] input The source audio buffer. + * @param[in,out] inputFrames The number of frames to process in the input audio buffer. + * @param[out] output The target audio buffer to store the converted audio. + * @param[in,out] outputFrames The number of frames to process in the target audio buffer. */ void Process(const AudioBuffer& input, AmUInt64& inputFrames, AudioBuffer& output, AmUInt64& outputFrames); /** * @brief Updates the source sample rate and target sample rate. * - * @param sourceSampleRate The source sample rate. - * @param targetSampleRate The target sample rate. + * @param[in] sourceSampleRate The source sample rate. + * @param[in] targetSampleRate The target sample rate. */ void SetSampleRate(AmUInt64 sourceSampleRate, AmUInt64 targetSampleRate); /** - * @brief Returns the required number of frames to have as input for the - * given amount of output frames. + * @brief Returns the required number of frames to have as input for the given amount of output frames. * - * @param outputFrameCount The number of output frames. + * @param[in] outputFrameCount The number of output frames. * * @return The input frame count needed to produce the given output frame count. */ [[nodiscard]] AmUInt64 GetRequiredInputFrameCount(AmUInt64 outputFrameCount) const; /** - * @brief Returns the expected number of frames to have as output for the - * given amount of input frames. + * @brief Returns the expected number of frames to have as output for the given amount of input frames. * - * @param inputFrameCount The number of input frames. + * @param[in] inputFrameCount The number of input frames. * * @return The expected number of output frames for the given input frame count. */ @@ -139,18 +143,22 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Convert stereo audio to mono. + * @brief Converts stereo audio to mono. + * + * @param[in] input The input audio buffer. + * @param[out] output The output audio buffer to store the converted audio. * - * @param input The input audio buffer. - * @param output The output audio buffer to store the converted audio. + * @internal */ static void ConvertStereoFromMono(const AudioBuffer& input, AudioBuffer& output); /** - * @brief Convert mono audio to stereo. + * @brief Converts mono audio to stereo. + * + * @param[in] input The input audio buffer. + * @param[out] output The output audio buffer to store the converted audio. * - * @param input The input audio buffer. - * @param output The output audio buffer to store the converted audio. + * @internal */ static void ConvertMonoFromStereo(const AudioBuffer& input, AudioBuffer& output); diff --git a/include/SparkyStudios/Audio/Amplitude/Convolution/Convolver.h b/include/SparkyStudios/Audio/Amplitude/DSP/Convolver.h similarity index 73% rename from include/SparkyStudios/Audio/Amplitude/Convolution/Convolver.h rename to include/SparkyStudios/Audio/Amplitude/DSP/Convolver.h index 2324256a..e78fca84 100644 --- a/include/SparkyStudios/Audio/Amplitude/Convolution/Convolver.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/Convolver.h @@ -17,17 +17,17 @@ #pragma once -#ifndef _AM_CONVOLUTION_CONVOLVER_H -#define _AM_CONVOLUTION_CONVOLVER_H +#ifndef _AM_DSP_CONVOLVER_H +#define _AM_DSP_CONVOLVER_H #include -#include +#include namespace SparkyStudios::Audio::Amplitude { /** - * @brief Implementation of a partitioned FFT convolution algorithm with uniform block size + * @brief Implementation of a partitioned FFT convolution algorithm with uniform block size. * * Some notes on how to use it: * @@ -43,11 +43,24 @@ namespace SparkyStudios::Audio::Amplitude * "unpredictable" operations like allocations, locking, API calls, etc. are * performed during processing (all necessary allocations and preparations take * place during initialization). + * + * @ingroup dsp */ class Convolver { public: + /** + * @brief Default constructor. + * + * Creates an uninitialized convolver. + */ Convolver(); + + /** + * @brief Destructor. + * + * Destroys the convolver and frees all allocated resources. + */ virtual ~Convolver(); // Prevent uncontrolled usage @@ -55,26 +68,29 @@ namespace SparkyStudios::Audio::Amplitude Convolver& operator=(const Convolver&) = delete; /** - * @brief Initializes the convolver + * @brief Initializes the convolver. * - * @param blockSize Block size internally used by the convolver (partition size) - * @param ir The impulse response - * @param irLen Length of the impulse response + * @param[in] blockSize Block size internally used by the convolver (partition size) + * @param[in] ir The impulse response + * @param[in] irLen Length of the impulse response * - * @return true: Success - false: Failed + * @return `true` when the convolver is successfully initialized, `false` otherwise. */ bool Init(AmSize blockSize, const AmAudioSample* ir, AmSize irLen); /** - * @brief Convolves the the given input samples and immediately outputs the result - * @param input The input samples - * @param output The convolution result - * @param len Number of input/output samples + * @brief Convolves the the given input samples and immediately outputs the result. + * + * @param[in] input The input samples. + * @param[out] output The convolution result. + * @param[in] len Number of input/output samples to process. */ void Process(const AmAudioSample* input, AmAudioSample* output, AmSize len); /** - * @brief Resets the convolver and discards the set impulse response + * @brief Resets the convolver state and discards the set impulse response. + * + * The convolver will need to be @ref Init initialized again after this call. */ void Reset(); @@ -110,4 +126,4 @@ namespace SparkyStudios::Audio::Amplitude }; } // namespace SparkyStudios::Audio::Amplitude -#endif // _AM_CONVOLUTION_CONVOLVER_H +#endif // _AM_DSP_CONVOLVER_H diff --git a/include/SparkyStudios/Audio/Amplitude/Math/FFT.h b/include/SparkyStudios/Audio/Amplitude/DSP/FFT.h similarity index 64% rename from include/SparkyStudios/Audio/Amplitude/Math/FFT.h rename to include/SparkyStudios/Audio/Amplitude/DSP/FFT.h index ea7a9fc8..bbc05911 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/FFT.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/FFT.h @@ -14,12 +14,12 @@ #pragma once -#ifndef _AM_MATH_FFT_H -#define _AM_MATH_FFT_H +#ifndef _AM_DSP_FFT_H +#define _AM_DSP_FFT_H #include -#include +#include namespace SparkyStudios::Audio::Amplitude { @@ -33,6 +33,8 @@ namespace SparkyStudios::Audio::Amplitude * * The output of the operation is ready-to-use, that means all the post processing * operations (scale, normalization, etc.) have been applied. + * + * @ingroup dsp */ class AM_API_PUBLIC FFT { @@ -40,7 +42,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the FFT output buffer size. * - * @param inputSize The size of the input buffer. + * @param[in] inputSize The size of the input buffer. * * @return The size of the FFT output buffer for the given input size. */ @@ -62,29 +64,38 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Initializes the FFT instance. * - * @param size The size of the input (as a power of 2). + * @param[in] size The size of the input (as a power of 2). */ void Initialize(AmSize size) const; /** * @brief Performs the forward FFT operation. * - * @param input The input audio data. This buffer needs to be of the same size as the one provided to the Initialize() method. - * @param splitComplex The complex buffer output separated into real and imaginary parts. The buffer will be resized if necessary. + * @param[in] input The input audio data. This buffer needs to be of the same size as the one provided to the @ref Initialize + * `Initialize()` method. + * @param[out] splitComplex The complex buffer output separated into real and imaginary parts. The buffer will be resized if + * necessary. */ - void Forward(AmConstAudioSampleBuffer input, SplitComplex& splitComplex) const; + void Forward(const AmReal32* input, SplitComplex& splitComplex) const; /** * @brief Performs the inverse FFT operation. * - * @param output The output audio data. This buffer needs to be of the same size as the one provided to the Initialize() method. - * @param splitComplex The complex buffer output separated into real and imaginary parts. The buffer will be resized if necessary. + * @param[out] output The output audio data. This buffer needs to be of the same size as the one provided to the @ref Initialize + * `Initialize()` method. + * @param[in] splitComplex The complex buffer output separated into real and imaginary parts. The buffer will be resized if + * necessary. */ - void Backward(AmAudioSampleBuffer output, SplitComplex& splitComplex) const; + void Backward(AmReal32* output, SplitComplex& splitComplex) const; private: + /** + * @brief The FFT platform-optimized implementation. + * + * @internal + */ void* _implementation; }; } // namespace SparkyStudios::Audio::Amplitude -#endif // _AM_MATH_FFT_H +#endif // _AM_DSP_FFT_H diff --git a/include/SparkyStudios/Audio/Amplitude/DSP/Filter.h b/include/SparkyStudios/Audio/Amplitude/DSP/Filter.h index f63da0d7..c58b2c2e 100644 --- a/include/SparkyStudios/Audio/Amplitude/DSP/Filter.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/Filter.h @@ -26,49 +26,53 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A Filter instance. * - * An object of this class will be created each time a @c Filter is requested. + * An object of this class will be created each time a `Filter` is requested. + * + * @ingroup dsp */ class AM_API_PUBLIC FilterInstance { public: /** - * @brief Constructs a new @c FilterInstance object. + * @brief Constructs a new `FilterInstance` object. * - * @param parent The parent @c Filter object that created this instance. + * @param[in] parent The parent `Filter` object that created this instance. */ explicit FilterInstance(Filter* parent); + /** + * @brief Destroys the `FilterInstance` object. + */ virtual ~FilterInstance(); /** - * @brief Initializes the filter instance with the provided number of - * parameters. + * @brief Initializes the filter instance with the provided number of parameters. * - * @param paramCount The number of parameters the filter will need. + * @param[in] paramCount The number of parameters the filter will need. */ AmResult Initialize(AmUInt32 paramCount); /** * @brief Updates the filter instance state for the provided delta time. * - * @param deltaTime The time in milliseconds since the last frame. + * @param[in] deltaTime The time in milliseconds since the last frame. */ virtual void AdvanceFrame(AmTime deltaTime); /** * @brief Executes the filter instance. * - * @param in The input buffer on which the filter should be applied. - * @param out The output buffer where the filtered output will be stored. - * @param frames The number of frames to process. - * @param sampleRate The current sample rate of the @c buffer. + * @param[in] in The input buffer on which the filter should be applied. + * @param[out] out The output buffer where the filtered output will be stored. + * @param[in] frames The number of frames to process. + * @param[in] sampleRate The current sample rate of the `buffer`. */ virtual void Process(const AudioBuffer& in, AudioBuffer& out, AmUInt64 frames, AmUInt32 sampleRate); /** * @brief Gets the current value of the parameter at the given index. * - * @param parameterIndex The index of the parameter to retrieve. + * @param[in] parameterIndex The index of the parameter to retrieve. * * @return The current value of the parameter. */ @@ -77,8 +81,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Sets the value of the parameter at the given index. * - * @param parameterIndex The index of the parameter to retrieve. - * @param value The value to set to the parameter. + * @param[in] parameterIndex The index of the parameter to retrieve. + * @param[in] value The value to set to the parameter. */ virtual void SetParameter(AmUInt32 parameterIndex, AmReal32 value); @@ -86,11 +90,11 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Executes the filter instance on a single channel of the given buffer. * - * @param in The input buffer on which the filter should be applied. - * @param out The output buffer where the filtered output will be stored. - * @param channel The index of the channel to process. - * @param frames The number of frames to process. - * @param sampleRate The current sample rate of the @c buffer. + * @param[in] in The input buffer on which the filter should be applied. + * @param[out] out The output buffer where the filtered output will be stored. + * @param[in] channel The index of the channel to process. + * @param[in] frames The number of frames to process. + * @param[in] sampleRate The current sample rate of the `buffer`. */ virtual void ProcessChannel(const AudioBuffer& in, AudioBuffer& out, AmUInt16 channel, AmUInt64 frames, AmUInt32 sampleRate); @@ -99,81 +103,107 @@ namespace SparkyStudios::Audio::Amplitude * * @param sample The audio sample to process. * @param channel The index of the channel to process. - * @param sampleRate The current sample rate of the @c buffer. + * @param sampleRate The current sample rate of the `buffer`. */ virtual AmAudioSample ProcessSample(AmAudioSample sample, AmUInt16 channel, AmUInt32 sampleRate); + /** + * @brief The parent filter object that created this instance. + */ Filter* m_parent; + /** + * @brief The number of parameters available for this filter. + */ AmUInt32 m_numParams; + + /** + * @brief The number of parameters that have changed since the last frame. + */ AmUInt32 m_numParamsChanged; - AmReal32Buffer m_parameters; + + /** + * @brief The parameters buffer. + */ + AmReal32* m_parameters; }; /** - * @brief Helper class to manage filters. + * @brief Base class to manage filters. * - * A filter applies transformations on an audio buffer.. + * A filter applies transformations to an audio buffer. The `Filter` class implements factory methods to create + * instances of `FilterInstance` objects, which are where the the filtering is done. + * + * The `Filter` class follows the [plugins architecture](/plugins/anatomy.md), and thus, you are able to create your own filters + * by inheriting from this class, and by implementing the necessary dependencies. + * + * @ingroup dsp */ class AM_API_PUBLIC Filter { friend class FilterInstance; public: - enum PARAM_TYPE + /** + * @brief The type of a filter parameter. + */ + enum ParameterType { - PARAM_FLOAT = 0, - PARAM_INT, - PARAM_BOOL + kParameterTypeFloat = 0, ///< The parameter is a float. + kParameterTypeInt, ///< The parameter is an integer. + kParameterTypeBool ///< The parameter is a boolean. }; /** - * @brief Create a new @c Filter instance. + * @brief Create a new `Filter` instance. * - * @param name The filter name. eg. "Delay". + * @param[in] name The filter name. eg. "Echo". */ explicit Filter(AmString name); + /** + * @brief Default destructor. + */ virtual ~Filter(); /** - * @brief Get the maximum number of parameters available for this filter. + * @brief Gets the maximum number of parameters available for this filter. * * @return The maximum number of filter parameters. */ [[nodiscard]] virtual AmUInt32 GetParamCount() const; /** - * @brief Get the name of the parameter at the given index. + * @brief Gets the name of the parameter at the given index. * - * @param index The parameter index. + * @param[in] index The parameter index. * * @return The name of the parameter at the given index. */ [[nodiscard]] virtual AmString GetParamName(AmUInt32 index) const; /** - * @brief Get the type of the parameter at the given index. + * @brief Gets the type of the parameter at the given index. * - * @param index The parameter index. + * @param[in] index The parameter index. * * @return The type of the parameter at the given index. */ [[nodiscard]] virtual AmUInt32 GetParamType(AmUInt32 index) const; /** - * @brief Get the maximum allowed value of the parameter at the given index. + * @brief Gets the maximum allowed value of the parameter at the given index. * - * @param index The parameter index. + * @param[in] index The parameter index. * * @return The maximum allowed value of the parameter at the given index. */ [[nodiscard]] virtual AmReal32 GetParamMax(AmUInt32 index) const; /** - * @brief Get the minimum allowed value of the parameter at the given index. + * @brief Gets the minimum allowed value of the parameter at the given index. * - * @param index The parameter index. + * @param[in] index The parameter index. * * @return The minimum allowed value of the parameter at the given index. */ @@ -187,10 +217,12 @@ namespace SparkyStudios::Audio::Amplitude virtual FilterInstance* CreateInstance() = 0; /** - * @brief Destroys an instance of the filter. The instance should have - * been created with @c Filter::CreateInstance(). + * @brief Destroys an instance of the filter. * - * @param instance The filter instance to be destroyed. + * @warning The instance should have been created with @ref CreateInstance `CreateInstance()` + * before being destroyed with this method. + * + * @param[in] instance The filter instance to be destroyed. */ virtual void DestroyInstance(FilterInstance* instance) = 0; @@ -204,57 +236,58 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new filter. * - * @param filter The filter to add in the registry. + * @param[in] filter The filter to add in the registry. */ static void Register(Filter* filter); /** * @brief Unregisters a filter. * - * @param filter The filter to remove from the registry. + * @param[in] filter The filter to remove from the registry. */ static void Unregister(const Filter* filter); /** * @brief Look up a filter by name. * - * @return The filter with the given name, or @c nullptr if none. + * @return The filter with the given name, or `nullptr` if none. */ static Filter* Find(const AmString& name); /** - * @brief Creates a new instance of the the filter with the given name - * and returns its pointer. The returned pointer should be deleted using @c Filter::Destruct(). + * @brief Creates a new instance of the the filter with the given name and returns its pointer. + * + * @note The returned pointer should be deleted using @ref Destruct `Destruct()`. * - * @param name The name of the filter. + * @param[in] name The name of the filter. * - * @return The filter with the given name, or @c nullptr if none. + * @return The filter with the given name, or `nullptr` if none. */ static FilterInstance* Construct(const AmString& name); /** * @brief Destroys the given filter instance. * - * @param name The name of the filter. - * @param instance The filter instance to destroy. + * @param[in] name The name of the filter. + * @param[in] instance The filter instance to destroy. */ static void Destruct(const AmString& name, FilterInstance* instance); /** * @brief Locks the filters registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new filters after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new filters after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the filters registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new filters after the engine is fully unloaded. */ static void UnlockRegistry(); diff --git a/include/SparkyStudios/Audio/Amplitude/DSP/Resampler.h b/include/SparkyStudios/Audio/Amplitude/DSP/Resampler.h index 35276382..4c0bf629 100644 --- a/include/SparkyStudios/Audio/Amplitude/DSP/Resampler.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/Resampler.h @@ -14,96 +14,101 @@ #pragma once -#ifndef _AM_MIXER_RESAMPLER_H -#define _AM_MIXER_RESAMPLER_H +#ifndef _AM_DSP_RESAMPLER_H +#define _AM_DSP_RESAMPLER_H #include #include namespace SparkyStudios::Audio::Amplitude { + class Resampler; + /** * @brief A Resampler instance. * - * An object of this class will be created each time a @c Resampler is requested. + * An object of this class will be created each time a `Resampler` is requested. + * + * @ingroup dsp */ class AM_API_PUBLIC ResamplerInstance { public: /** - * @brief Construct a new ResamplerInstance object. + * @brief Constructs a new `ResamplerInstance` object. * * This will initialize the resampler instance state to default values. */ ResamplerInstance() = default; + /** + * @brief Default destructor. + */ virtual ~ResamplerInstance() = default; /** - * @brief Initialize a new instance of the resampler. + * @brief Initializes a new instance of the resampler. * - * @param channelCount The number of channels in the audio data. - * @param sampleRateIn The input sample rate. - * @param sampleRateOut The output sample rate. + * @param[in] channelCount The number of channels in the audio data. + * @param[in] sampleRateIn The input sample rate. + * @param[in] sampleRateOut The output sample rate. */ virtual void Initialize(AmUInt16 channelCount, AmUInt32 sampleRateIn, AmUInt32 sampleRateOut) = 0; /** * @brief Processes the audio data. * - * @param input The input audio data. - * @param inputFrames The number of frames in the input buffer. - * @param output The output audio data. - * @param outputFrames The number of frames in the output buffer. + * @param[in] input The input audio data. + * @param[in,out] inputFrames The number of frames in the input buffer. + * @param[out] output The output audio data. + * @param[in,out] outputFrames The number of frames in the output buffer. * - * @return @c true if the resampling was successful, otherwise @c false. + * @return `true` if the resampling was successful, `false` otherwise. */ virtual bool Process(const AudioBuffer& input, AmUInt64& inputFrames, AudioBuffer& output, AmUInt64& outputFrames) = 0; /** * @brief Changes the input and output sample rate. * - * @param sampleRateIn The new input sample rate. - * @param sampleRateOut The new output sample rate. + * @param[in] sampleRateIn The new input sample rate. + * @param[in] sampleRateOut The new output sample rate. */ virtual void SetSampleRate(AmUInt32 sampleRateIn, AmUInt32 sampleRateOut) = 0; /** - * @brief Get the current input sample rate. + * @brief Gets the current input sample rate. * * @return The current input sample rate. */ [[nodiscard]] virtual AmUInt32 GetSampleRateIn() const = 0; /** - * @brief Get the current output sample rate. + * @brief Gets the current output sample rate. * * @return The current output sample rate. */ [[nodiscard]] virtual AmUInt32 GetSampleRateOut() const = 0; /** - * @brief Get the current channels count. + * @brief Gets the current channels count. * * @return The current channels count. */ [[nodiscard]] virtual AmUInt16 GetChannelCount() const = 0; /** - * @brief Returns the required number of frames to have as input for the - * given amount of output frames. + * @brief Returns the required number of frames to have as input for the given amount of output frames. * - * @param outputFrameCount The number of output frames. + * @param[in] outputFrameCount The number of output frames. * * @return The input frame count needed to produce the given output frame count. */ [[nodiscard]] virtual AmUInt64 GetRequiredInputFrames(AmUInt64 outputFrameCount) const = 0; /** - * @brief Returns the expected number of frames to have as output for the - * given amount of input frames. + * @brief Returns the expected number of frames to have as output for the given amount of input frames. * - * @param inputFrameCount The number of input frames. + * @param[in] inputFrameCount The number of input frames. * * @return The expected number of output frames for the given input frame count. */ @@ -130,18 +135,30 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Cleans up the internal resampler state and allocated data. + * * @note This method is called when the resampler is about to be destroyed. */ virtual void Clear() = 0; }; + /** + * @brief Base class to manage resamplers. + * + * A resampler is used to change the sample rate of an audio buffer. The `Resampler` class implements + * factory methods to create instances of `ResamplerInstance` objects, which are where the the resampling is done. + * + * The `Resampler` class follows the [plugins architecture](/plugins/anatomy.md), and thus, you are able to create your own resamplers + * and register them to the `Engine` by inheriting from this class, and by implementing the necessary dependencies. + * + * @ingroup dsp + */ class AM_API_PUBLIC Resampler { public: /** * @brief Create a new Resampler instance. * - * @param name The resampler name. eg. "MiniAudioLinear". + * @param[in] name The resampler name. eg. "MiniAudioLinear". */ explicit Resampler(AmString name); @@ -152,18 +169,25 @@ namespace SparkyStudios::Audio::Amplitude */ Resampler(); + /** + * @brief Default destructor. + */ virtual ~Resampler(); /** * @brief Creates a new instance of the resampler. + * * @return A new instance of the resampler. */ virtual ResamplerInstance* CreateInstance() = 0; /** - * @brief Destroys an instance of the resampler. The instance should have - * been created with CreateInstance(). - * @param instance The resampler instance to be destroyed. + * @brief Destroys an instance of the resampler. + * + * @warning The instance should have been created with @ref CreateInstance `CreateInstance()` + * before being destroyed with this method. + * + * @param[in] instance The resampler instance to be destroyed. */ virtual void DestroyInstance(ResamplerInstance* instance) = 0; @@ -177,50 +201,51 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new resampler. * - * @param resampler The resampler to add in the registry. + * @param[in] resampler The resampler to add in the registry. */ static void Register(Resampler* resampler); /** * @brief Unregisters a resampler. * - * @param resampler The resampler to remove from the registry. + * @param[in] resampler The resampler to remove from the registry. */ static void Unregister(const Resampler* resampler); /** - * @brief Creates a new instance of the the resampler with the given name - * and returns its pointer. The returned pointer should be deleted using Resampler::Destruct(). + * @brief Creates a new instance of the the resampler with the given name and returns its pointer. * - * @param name The name of the resampler. + * @note The returned pointer should be deleted using @ref Destruct `Destruct()`. * - * @return The resampler with the given name, or NULL if none. + * @param[in] name The name of the resampler. + * + * @return The resampler with the given name, or `nullptr` if none. */ static ResamplerInstance* Construct(const AmString& name); /** * @brief Destroys the given resampler instance. * - * @param name The name of the resampler. - * @param instance The resampler instance to destroy. + * @param[in] name The name of the resampler. + * @param[in] instance The resampler instance to destroy. */ static void Destruct(const AmString& name, ResamplerInstance* instance); /** * @brief Locks the resamplers registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new resamplers after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new resamplers after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the resamplers registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new resamplers after the engine is fully unloaded. */ static void UnlockRegistry(); @@ -234,10 +259,12 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Look up a resampler by name. * - * @return The resampler with the given name, or NULL if none. + * @return The resampler with the given name, or `nullptr` if none. + * + * @internal */ static Resampler* Find(const AmString& name); }; } // namespace SparkyStudios::Audio::Amplitude -#endif // _AM_MIXER_RESAMPLER_H +#endif // _AM_DSP_RESAMPLER_H diff --git a/include/SparkyStudios/Audio/Amplitude/Math/SplitComplex.h b/include/SparkyStudios/Audio/Amplitude/DSP/SplitComplex.h similarity index 84% rename from include/SparkyStudios/Audio/Amplitude/Math/SplitComplex.h rename to include/SparkyStudios/Audio/Amplitude/DSP/SplitComplex.h index 61f4c962..a0d40b23 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/SplitComplex.h +++ b/include/SparkyStudios/Audio/Amplitude/DSP/SplitComplex.h @@ -14,8 +14,8 @@ #pragma once -#ifndef _AM_MATH_SPLIT_COMPLEX_H -#define _AM_MATH_SPLIT_COMPLEX_H +#ifndef _AM_DSP_SPLIT_COMPLEX_H +#define _AM_DSP_SPLIT_COMPLEX_H #include #include @@ -28,6 +28,8 @@ namespace SparkyStudios::Audio::Amplitude * The split-complex representation stores the real and imaginary parts * of FFT results in two different memory buffers which is useful e.g. for * SIMD optimizations. + * + * @ingroup dsp */ class AM_API_PUBLIC SplitComplex { @@ -35,7 +37,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new split-complex buffer with the given initial size. * - * @param initialSize The initial size of the split-complex buffer. + * @param[in] initialSize The initial size of the split-complex buffer. */ explicit SplitComplex(AmSize initialSize = 0); @@ -55,9 +57,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Resizes the split-complex buffer to the given size. * - * @param newSize The new size of the split-complex buffer. - * @param clear - * @param clear + * @param[in] newSize The new size of the split-complex buffer. + * @param[in] clear Whether to clear the buffer after resizing. */ void Resize(AmSize newSize, bool clear = false); @@ -69,7 +70,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Copies the given split-complex buffer to this one. * - * @param other The split-complex buffer to copy. + * @param[in] other The split-complex buffer to copy. */ void CopyFrom(const SplitComplex& other) const; @@ -111,6 +112,13 @@ namespace SparkyStudios::Audio::Amplitude */ [[nodiscard]] const AmAudioSample* im() const; + /** + * @brief Gets the complex value at the given index. + * + * @param[in] index The index of the complex value. + * + * @return The complex value at the given index. + */ [[nodiscard]] std::complex operator[](AmSize index) const; private: @@ -120,4 +128,4 @@ namespace SparkyStudios::Audio::Amplitude }; } // namespace SparkyStudios::Audio::Amplitude -#endif \ No newline at end of file +#endif // _AM_DSP_SPLIT_COMPLEX_H \ No newline at end of file diff --git a/include/SparkyStudios/Audio/Amplitude/HRTF/HRIRSphere.h b/include/SparkyStudios/Audio/Amplitude/HRTF/HRIRSphere.h index 2220bb8b..e5179d09 100644 --- a/include/SparkyStudios/Audio/Amplitude/HRTF/HRIRSphere.h +++ b/include/SparkyStudios/Audio/Amplitude/HRTF/HRIRSphere.h @@ -26,29 +26,31 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief The model of the HRIR sphere dataset. + * + * @ingroup core */ enum HRIRSphereDatasetModel : AmUInt8 { /** - * @brief The HRIR sphere uses data from the IRCAM (LISTEN) dataset. + * The HRIR sphere uses data from the IRCAM (LISTEN) dataset. * (http://recherche.ircam.fr/equipes/salles/listen/download.html) */ eHRIRSphereDatasetModel_IRCAM = 0, /** - * @brief The HRIR sphere uses data from the MIT (KEMAR) dataset. + * The HRIR sphere uses data from the MIT (KEMAR) dataset. * (http://sound.media.mit.edu/resources/KEMAR.html). */ eHRIRSphereDatasetModel_MIT = 1, /** - * @brief The HRIR sphere uses data from the SADIE II dataset. + * The HRIR sphere uses data from the SADIE II dataset. * (https://www.york.ac.uk/sadie-project/database.html). */ eHRIRSphereDatasetModel_SADIE = 2, /** - * @brief The HRIR sphere uses data from a SOFA (Spatially Oriented Format for Acoustics) file. + * The HRIR sphere uses data from a SOFA (Spatially Oriented Format for Acoustics) file. * (https://www.sofaconventions.org/). */ eHRIRSphereDatasetModel_SOFA = 3, @@ -61,6 +63,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Provides metadata about an HRIR sphere file. + * + * @ingroup core */ struct HRIRSphereFileHeaderDescription { @@ -97,6 +101,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A vertex of the HRIR sphere. + * + * @ingroup core */ struct HRIRSphereVertex { @@ -128,6 +134,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A 3D sphere of HRIR data. + * + * @ingroup core */ class AM_API_PUBLIC HRIRSphere : public Resource { diff --git a/include/SparkyStudios/Audio/Amplitude/IO/DiskFile.h b/include/SparkyStudios/Audio/Amplitude/IO/DiskFile.h index ca4ac506..6570c67c 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/DiskFile.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/DiskFile.h @@ -22,31 +22,34 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief A File implementation that reads and writes a file on disk. + * @brief A `File` implementation that reads and writes a file on disk. + * + * @ingroup io */ class AM_API_PUBLIC DiskFile : public File { public: /** - * @brief Creates a new DiskFile instance. + * @brief Creates a new `DiskFile` instance. */ DiskFile(); /** - * @brief Creates a new DiskFile instance from a file handle. + * @brief Creates a new `DiskFile` instance from a file handle. * - * @param fp The file handle to manage in this instance. + * @param[in] fp The file handle to manage in this instance. */ explicit DiskFile(AmFileHandle fp); /** * @brief Creates a new DiskFile instance by opening a file at the given path. * - * @param fileName The path to the file to open. - * @param mode The open mode to use. - * @param kind The type of file to open. + * @param[in] fileName The path to the file to open. + * @param[in] mode The open mode to use. + * @param[in] kind The type of file to open. */ - explicit DiskFile(const std::filesystem::path& fileName, FileOpenMode mode = eFOM_READ, FileOpenKind kind = eFOK_BINARY); + explicit DiskFile( + const std::filesystem::path& fileName, eFileOpenMode mode = eFileOpenMode_Read, eFileOpenKind kind = eFileOpenKind_Binary); /** * @brief Destroys the instance and release the file handler. @@ -54,60 +57,61 @@ namespace SparkyStudios::Audio::Amplitude ~DiskFile() override; /** - * @copydoc File::GetPath + * @inherit */ [[nodiscard]] AmOsString GetPath() const override; /** - * @copydoc File::Eof + * @inherit */ bool Eof() override; /** - * @copydoc File::Read + * @inherit */ AmSize Read(AmUInt8Buffer dst, AmSize bytes) override; /** - * @copydoc File::Write + * @inherit */ AmSize Write(AmConstUInt8Buffer src, AmSize bytes) override; /** - * @copydoc File::Length + * @inherit */ AmSize Length() override; /** - * @copydoc File::Seek + * @inherit */ - void Seek(AmInt64 offset, FileSeekOrigin origin) override; + void Seek(AmInt64 offset, eFileSeekOrigin origin) override; /** - * @copydoc File::Position + * @inherit */ AmSize Position() override; /** - * @copydoc File::GetPtr + * @inherit */ AmVoidPtr GetPtr() override; /** - * @copydoc File::IsValid + * @inherit */ [[nodiscard]] bool IsValid() const override; /** * @brief Opens a file at the given path. * - * @param filePath The path to the file to open. - * @param mode The open mode to use. - * @param kind The type of file to open. + * @param[in] filePath The path to the file to open. + * @param[in] mode The open mode to use. + * @param[in] kind The type of file to open. * * @return The result of the operation. */ - AmResult Open(const std::filesystem::path& filePath, FileOpenMode mode = eFOM_READ, FileOpenKind kind = eFOK_BINARY); + AmResult Open( + const std::filesystem::path& filePath, eFileOpenMode mode = eFileOpenMode_Read, eFileOpenKind kind = eFileOpenKind_Binary); /** * @brief Closes the file. diff --git a/include/SparkyStudios/Audio/Amplitude/IO/DiskFileSystem.h b/include/SparkyStudios/Audio/Amplitude/IO/DiskFileSystem.h index e1bb0505..9386d4a0 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/DiskFileSystem.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/DiskFileSystem.h @@ -24,69 +24,70 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief A FileSystem implementation that reads and write files - * from disk. + * @brief A `FileSystem` implementation that reads and write files from disk. + * + * @ingroup io */ class AM_API_PUBLIC DiskFileSystem final : public FileSystem { public: /** - * @brief Create a new instance of the DiskFileSystem class. + * @brief Creates a new instance of the DiskFileSystem class. */ DiskFileSystem(); /** - * @copydoc FileSystem::SetBasePath + * @inherit */ void SetBasePath(const AmOsString& basePath) override; /** - * @copydoc FileSystem::GetBasePath + * @inherit */ [[nodiscard]] const AmOsString& GetBasePath() const override; /** - * @copydoc FileSystem::ResolvePath + * @inherit */ [[nodiscard]] AmOsString ResolvePath(const AmOsString& path) const override; /** - * @copydoc FileSystem::Exists + * @inherit */ [[nodiscard]] bool Exists(const AmOsString& path) const override; /** - * @copydoc FileSystem::IsDirectory + * @inherit */ [[nodiscard]] bool IsDirectory(const AmOsString& path) const override; /** - * @copydoc FileSystem::Join + * @inherit */ [[nodiscard]] AmOsString Join(const std::vector& parts) const override; /** - * @copydoc FileSystem::OpenFile + * @inherit */ - [[nodiscard]] std::shared_ptr OpenFile(const AmOsString& path, FileOpenMode mode) const override; + [[nodiscard]] std::shared_ptr OpenFile(const AmOsString& path, eFileOpenMode mode) const override; /** - * @copydoc FileSystem::StartOpenFileSystem + * @inherit */ void StartOpenFileSystem() override; /** - * @copydoc FileSystem::TryFinalizeOpenFileSystem + * @inherit */ bool TryFinalizeOpenFileSystem() override; /** - * @copydoc FileSystem::StartCloseFileSystem + * @inherit */ void StartCloseFileSystem() override; /** - * @copydoc FileSystem::TryFinalizeCloseFileSystem + * @inherit */ bool TryFinalizeCloseFileSystem() override; diff --git a/include/SparkyStudios/Audio/Amplitude/IO/File.h b/include/SparkyStudios/Audio/Amplitude/IO/File.h index adc71e64..8716f806 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/File.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/File.h @@ -24,77 +24,85 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Describes the mode in which open the file. + * @brief Describes the mode in which to open a file. + * + * @ingroup io */ - enum FileOpenMode : AmUInt8 + enum eFileOpenMode : AmUInt8 { - eFOM_READ = 0, - eFOM_WRITE = 1, - eFOM_APPEND = 2, - eFOM_READWRITE = 3, - eFOM_READAPPEND = 4, + eFileOpenMode_Read = 0, + eFileOpenMode_Write = 1, + eFileOpenMode_Append = 2, + eFileOpenMode_ReadWrite = 3, + eFileOpenMode_ReadAppend = 4, }; /** * @brief The type of file being opened. + * + * @ingroup io */ - enum FileOpenKind : AmUInt8 + enum eFileOpenKind : AmUInt8 { - eFOK_BINARY = 0, - eFOK_TEXT = 1, + eFileOpenKind_Binary = 0, + eFileOpenKind_Text = 1, }; /** * @brief Defines from where to seek in the file. + * + * @ingroup io */ - enum FileSeekOrigin : AmUInt8 + enum eFileSeekOrigin : AmUInt8 { - eFSO_START = SEEK_SET, - eFSO_CURRENT = SEEK_CUR, - eFSO_END = SEEK_END, + eFileSeekOrigin_Start = SEEK_SET, + eFileSeekOrigin_Current = SEEK_CUR, + eFileSeekOrigin_End = SEEK_END, }; /** - * @brief Base class for a file in a FileSystem. + * @brief Base class for a file in a `FileSystem`. + * + * @ingroup io */ class AM_API_PUBLIC File { public: /** - * @brief Virtual destructor. + * @brief Default destructor. */ virtual ~File() = default; /** - * @brief Gets the path to the file in the loaded FileSystem. + * @brief Gets the path to the file in the loaded `FileSystem`. * * @return The path to the file. */ [[nodiscard]] virtual AmOsString GetPath() const = 0; /** - * @brief Reads a single byte from the file in an @c AmUInt8. + * @brief Reads a single byte from the file in an `AmUInt8`. * * @return The read value. */ AmUInt8 Read8(); /** - * @brief Reads two bytes from the file in an @c AmUInt16. + * @brief Reads two bytes from the file in an `AmUInt16`. * * @return The read value. */ AmUInt16 Read16(); /** - * @brief Reads four bytes from the file in an @c AmUInt32. + * @brief Reads four bytes from the file in an `AmUInt32`. * * @return The read value. */ AmUInt32 Read32(); /** - * @brief Reads eight bytes from the file in an @c AmUInt64. + * @brief Reads eight bytes from the file in an `AmUInt64`. * * @return The read value. */ @@ -108,53 +116,53 @@ namespace SparkyStudios::Audio::Amplitude AmString ReadString(); /** - * @brief Writes a single byte to the file from an @c AmUInt8. + * @brief Writes a single byte to the file from an `AmUInt8`. * - * @param value The value to write. + * @param[in] value The value to write. */ AmSize Write8(AmUInt8 value); /** - * @brief Writes two bytes to the file from an @c AmUInt16. + * @brief Writes two bytes to the file from an `AmUInt16`. * - * @param value The value to write. + * @param[in] value The value to write. */ AmSize Write16(AmUInt16 value); /** - * @brief Writes four bytes to the file from an @c AmUInt32. + * @brief Writes four bytes to the file from an `AmUInt32`. * - * @param value The value to write. + * @param[in] value The value to write. */ AmSize Write32(AmUInt32 value); /** - * @brief Writes eight bytes to the file from an @c AmUInt64. + * @brief Writes eight bytes to the file from an `AmUInt64`. * - * @param value The value to write. + * @param[in] value The value to write. */ AmSize Write64(AmUInt64 value); /** * @brief Writes a string to the file. * - * @param value The value to write. + * @param[in] value The value to write. */ AmSize WriteString(const AmString& value); /** - * @brief Check if the read cursor is at the end of the file. + * @brief Checks if the read cursor is at the end of the file. * - * @return True if the read cursor is at the end of the file, false otherwise. + * @return `true` if the read cursor is at the end of the file, `false` otherwise. */ virtual bool Eof() = 0; /** * @brief Reads data from the file. * - * @param dst The destination buffer of the read data. - * @param bytes The number of bytes to read from the file. The destination buffer must be at least as large as the number of bytes - * to read. + * @param[in] dst The destination buffer of the read data. + * @param[in] bytes The number of bytes to read from the file. The destination buffer must be at least as large as the number of + * bytes to read. * * @return The number of bytes read from the file. */ @@ -163,8 +171,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Writes data to the file. * - * @param src The source buffer of the data to write. - * @param bytes The number of bytes to write to the file. The source buffer must be at least as large as the number of bytes to + * @param[in] src The source buffer of the data to write. + * @param[in] bytes The number of bytes to write to the file. The source buffer must be at least as large as the number of bytes to * write. * * @return The number of bytes written to the file. @@ -181,18 +189,17 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Seeks the read/write to the specified offset. * - * @param offset The offset in bytes from the beginning of the file. + * @param[in] offset The offset in bytes from the beginning of the file. */ void Seek(AmSize offset); /** - * @brief Seeks the read/write to the specified offset, starting at the given - * origin. + * @brief Seeks the read/write to the specified offset, starting at the given origin. * - * @param offset The offset in bytes from the beginning of the file. - * @param origin The origin from which to begin seeking. + * @param[in] offset The offset in bytes from the beginning of the file. + * @param[in] origin The origin from which to begin seeking. */ - virtual void Seek(AmInt64 offset, FileSeekOrigin origin) = 0; + virtual void Seek(AmInt64 offset, eFileSeekOrigin origin) = 0; /** * @brief Gets the current position of the read/write cursor. @@ -214,7 +221,7 @@ namespace SparkyStudios::Audio::Amplitude * Validity of a file is determined by the underlying implementation. But this should * primarily mean that the file exists AND has been opened. * - * @return True if the file is valid, false otherwise. + * @return `true` if the file is valid, `false` otherwise. */ [[nodiscard]] virtual bool IsValid() const = 0; }; diff --git a/include/SparkyStudios/Audio/Amplitude/IO/FileSystem.h b/include/SparkyStudios/Audio/Amplitude/IO/FileSystem.h index d5efe81d..16bc12d8 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/FileSystem.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/FileSystem.h @@ -25,47 +25,54 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Base class for files and resources loaders. * - * The FileSystem class is used by the engine as an interface to - * load files and other resources. It provides basic functionnalities - * needed by a filesystem + * The `FileSystem` class is used by the engine as an interface to + * load files and other resources. It provides basic functionalities + * needed by a file system. + * + * You are able to implement your own `FileSystem` subclass to fit your needs, for example, + * reading files from a network drive or a custom storage system. + * + * @ingroup io */ class AM_API_PUBLIC FileSystem { public: /** - * @brief Default virtual destructor. + * @brief Default destructor. */ virtual ~FileSystem() = default; /** - * @brief Changes the filesystem base path. That path is interpreted by the implementation - * and doesn't necessarily have to be a real path on disk. It's just used as the base path - * for resolving relative paths from which the engine will load resources. + * @brief Changes the file system base path. + * + * That path is interpreted by the implementation and doesn't necessarily have to be a real + * path on disk. It's just used as the base path for resolving relative paths from which the + * engine will load resources. * - * @param basePath The filesystem base path. + * @param[in] basePath The file system base path. */ virtual void SetBasePath(const AmOsString& basePath) = 0; /** - * @brief Returns the base path of the filesystem. + * @brief Returns the base path of the file system. * * @return The base path for resolving relative paths from which the engine will load resources. */ [[nodiscard]] virtual const AmOsString& GetBasePath() const = 0; /** - * @brief Resolves a relative path from the filesystem base path. + * @brief Resolves a relative path from the file system base path. * * @return The resolved path. */ [[nodiscard]] virtual AmOsString ResolvePath(const AmOsString& path) const = 0; /** - * @brief Checks if an item (file or folder) exists on the filesystem. + * @brief Checks if an item (file or folder) exists on the file system. * - * @param path The path to the item. + * @param[in] path The path to the item. * - * @return True if the file exists, false otherwise. + * @return `true` if the file exists, `false` otherwise. */ [[nodiscard]] virtual bool Exists(const AmOsString& path) const = 0; @@ -74,69 +81,70 @@ namespace SparkyStudios::Audio::Amplitude * * @param path The path to the item. * - * @return True if the file is a directory, false otherwise. + * @return `true` if the file is a directory, `false` otherwise. */ [[nodiscard]] virtual bool IsDirectory(const AmOsString& path) const = 0; /** - * @brief Merge the given parts of the path into a single path, by joining them with the filesystem - * path separator. + * @brief Merge the given parts of the path into a single path, by joining them with the file system's path separator. * - * @param parts The parts of the path. + * @param[in] parts The parts of the path. * - * @return A path concatenated with the given parts and the filesystem path separator. + * @return A path concatenated with the given parts and the file system path separator. */ [[nodiscard]] virtual AmOsString Join(const std::vector& parts) const = 0; /** * @brief Opens the file at the given path. * - * @param path The path to the file to open. - * @param mode The file open mode. + * @param[in] path The path to the file to open. + * @param[in] mode The file open mode. * - * @return The opened file. The returned File implementation depends on the FileSystem implementation. + * @return The opened file. The returned `File` implementation depends on the `FileSystem` implementation. */ - [[nodiscard]] virtual std::shared_ptr OpenFile(const AmOsString& path, FileOpenMode mode = eFOM_READ) const = 0; + [[nodiscard]] virtual std::shared_ptr OpenFile(const AmOsString& path, eFileOpenMode mode = eFileOpenMode_Read) const = 0; /** - * @brief Opens the FileSystem. + * @brief Opens the `FileSystem`. + * + * This function __MUST__ be called before any other actions in the file system. + * It is used to initialize the file system (eg: mounting an archive). * - * This function MUST be called before any other actions in the filesystem. - * It is used to initialize the filesystem (eg: mounting an archive). It is - * recommended to process the initialization in a separate thread. + * @tip For implementations, It is recommended to process the initialization in a separate thread. * * The implementation is free to ignore this if not needed. */ virtual void StartOpenFileSystem() = 0; /** - * @brief Checks if the FileSystem is initialized. + * @brief Checks if the `FileSystem` is loaded. * - * Since the StartOpenFileSystem() function is designed to be asynchronous, this function - * is used to check if the FileSystem has been successfully initialized. + * Since the @ref StartOpenFileSystem `StartOpenFileSystem()` function is designed to be asynchronous, this function + * is used to check if the `FileSystem` has been successfully initialized. * - * @return True if the FileSystem has been initialized, false otherwise. + * @return `true` if the `FileSystem` has been fully loaded, `false` otherwise. */ virtual bool TryFinalizeOpenFileSystem() = 0; /** - * @brief Stops the FileSystem. + * @brief Stops the `FileSystem`. + * + * This function __MUST__ be called when the `FileSystem` is no longer needed. + * It is used to stop the file system (eg: unmounting an archive). * - * This function MUST be called when the FileSystem is no longer needed. - * It is used to stop the filesystem (eg: unmounting an archive). It is - * recommended to process the stopping in a separate thread. + * @tip For implementations, it is recommended to process the stopping in a separate thread. * * The implementation is free to ignore this if not needed. */ virtual void StartCloseFileSystem() = 0; /** - * @brief Checks if the FileSystem is stopped. + * @brief Checks if the `FileSystem` is stopped. * - * Since the StartCloseFileSystem() function is designed to be asynchronous, this function - * is used to check if the FileSystem has been successfully stopped. + * Since the @ref StartCloseFileSystem `StartCloseFileSystem()` function is designed to be asynchronous, this function + * is used to check if the `FileSystem` has been successfully stopped. * - * @return True if the FileSystem has been stopped, false otherwise. + * @return `true` if the `FileSystem` has been fully stopped, `false` otherwise. */ virtual bool TryFinalizeCloseFileSystem() = 0; }; diff --git a/include/SparkyStudios/Audio/Amplitude/IO/MemoryFile.h b/include/SparkyStudios/Audio/Amplitude/IO/MemoryFile.h index a58b3551..7283b0c3 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/MemoryFile.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/MemoryFile.h @@ -22,23 +22,25 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief A File implementation that reads and writes a memory buffer. + * @brief A `File` implementation that reads from and writes to a memory buffer. + * + * @ingroup io */ class AM_API_PUBLIC MemoryFile : public File { public: /** - * @brief Creates a new MemoryFile instance. + * @brief Creates a new `MemoryFile` instance. */ MemoryFile(); /** - * @brief Creates a new MemoryFile instance from a memory buffer. + * @brief Creates a new `MemoryFile` instance from a memory buffer. * - * @param buffer The memory buffer to manage in this instance. - * @param size The size of the memory buffer. - * @param copy If true, the memory buffer will be copied. - * @param takeOwnership If true, the memory buffer will be owned by this instance, and released when this instance is destroyed. + * @param[in] buffer The memory buffer to manage in this instance. + * @param[in] size The size of the memory buffer. + * @param[in] copy If true, the memory buffer will be copied. + * @param[in] takeOwnership If true, the memory buffer will be owned by this instance, and released when this instance is destroyed. */ MemoryFile(AmUInt8Buffer buffer, AmSize size, bool copy = false, bool takeOwnership = true); @@ -48,54 +50,54 @@ namespace SparkyStudios::Audio::Amplitude ~MemoryFile() override; /** - * @copydoc File::GetPath + * @inherit */ [[nodiscard]] AmOsString GetPath() const override; /** - * @copydoc File::Eof + * @inherit */ bool Eof() override; /** - * @copydoc File::Read + * @inherit */ AmSize Read(AmUInt8Buffer dst, AmSize bytes) override; /** - * @copydoc File::Write + * @inherit */ AmSize Write(AmConstUInt8Buffer src, AmSize bytes) override; /** - * @copydoc File::Length + * @inherit */ AmSize Length() override; /** - * @copydoc File::Seek + * @inherit */ - void Seek(AmInt64 offset, FileSeekOrigin origin) override; + void Seek(AmInt64 offset, eFileSeekOrigin origin) override; /** - * @copydoc File::Position + * @inherit */ AmSize Position() override; /** - * @copydoc File::GetPtr + * @inherit */ AmVoidPtr GetPtr() override; /** - * @copydoc File::IsValid + * @inherit */ [[nodiscard]] bool IsValid() const override; /** * @brief Opens a new memory buffer with the specified size. * - * @param size The size of the buffer. + * @param[in] size The size of the buffer. * * @return The result of the operation. */ @@ -104,10 +106,10 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Opens a memory buffer. * - * @param buffer The memory buffer to open. - * @param size The size of the memory buffer. - * @param copy If true, the memory buffer will be copied. - * @param takeOwnership If true, the memory buffer will be owned by this instance, and released when this instance is destroyed. + * @param[in] buffer The memory buffer to open. + * @param[in] size The size of the memory buffer. + * @param[in] copy If true, the memory buffer will be copied. + * @param[in] takeOwnership If true, the memory buffer will be owned by this instance, and released when this instance is destroyed. * * @return The result of the operation. */ @@ -116,7 +118,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Opens a memory buffer from a file content. * - * @param fileName The path to the file to open. + * @param[in] fileName The path to the file to open. * * @return The result of the operation. */ @@ -125,7 +127,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Copies data from a file instance to a memory buffer. The file content is entirely copied. * - * @param file The file isntance to copy data from. + * @param[in] file The file instance to copy data from. * * @return The result of the operation. */ diff --git a/include/SparkyStudios/Audio/Amplitude/IO/PackageFileSystem.h b/include/SparkyStudios/Audio/Amplitude/IO/PackageFileSystem.h index e41706e9..905b67bb 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/PackageFileSystem.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/PackageFileSystem.h @@ -17,6 +17,7 @@ #ifndef _AM_IO_PACKAGE_FILESYSTEM_H #define _AM_IO_PACKAGE_FILESYSTEM_H +#include #include #include #include @@ -24,36 +25,41 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Defines the compression algorithms a package file can be compressed with. + * @brief Defines the algorithms a package file can be compressed with. + * + * @ingroup io */ - enum PackageFileCompressionAlgorithm : AmUInt8 + enum ePackageFileCompressionAlgorithm : AmUInt8 { /** * @brief No compression algorithm has been used for the package file. */ - ePCA_None, + ePackageFileCompressionAlgorithm_None, /** * @brief The package file has been compressed using ZLib. */ - ePCA_ZLib, + ePackageFileCompressionAlgorithm_ZLib, /** * @brief Invalid compression algorithm. */ - ePCA_Invalid + ePackageFileCompressionAlgorithm_Invalid }; /** * @brief Describes an item in the package file. * * The item description is stored in the package file's header. + * + * @ingroup io */ struct PackageFileItemDescription { /** - * @brief The name of the package item. It usually refers to the - * resource path. + * @brief The name of the package item. + * + * @note It usually refers to the resource path. */ AmString m_Name; @@ -70,16 +76,22 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Provides metadata about the package file. + * + * @ingroup io */ struct PackageFileHeaderDescription { /** - * @brief Package file header tag. Should be equal to 'AMPK'. + * @brief Package file header tag. + * + * @note Should be equal to 'AMPK'. */ AmUInt8 m_Header[4] = { 'A', 'M', 'P', 'K' }; /** - * @brief Package file version. Used to implement new features in package + * @brief Package file version. + * + * This is used to implement new features in package * files and still be backward compatible with old versions. */ AmUInt16 m_Version = 0; @@ -87,7 +99,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief The compression algorithm used for this package file. */ - PackageFileCompressionAlgorithm m_CompressionAlgorithm = ePCA_Invalid; + ePackageFileCompressionAlgorithm m_CompressionAlgorithm = ePackageFileCompressionAlgorithm_Invalid; /** * @brief The description of each item in the package file. @@ -98,75 +110,86 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief A FileSystem implementation that provides access - * to an Amplitude package file. + * @brief A `FileSystem` implementation that provides access to an Amplitude package file. + * + * @ingroup io */ class AM_API_PUBLIC PackageFileSystem final : public FileSystem { public: /** - * @brief Constructs a new @c PackageFileSystem instance. + * @brief Constructs a new `PackageFileSystem` instance. */ PackageFileSystem(); + /** + * @brief Destroys the `PackageFileSystem` instance. + */ ~PackageFileSystem() override; /** - * @copydoc FileSystem::SetBasePath + * @inherit */ void SetBasePath(const AmOsString& basePath) override; /** - * @copydoc FileSystem::GetBasePath + * @inherit */ [[nodiscard]] const AmOsString& GetBasePath() const override; /** - * @copydoc FileSystem::ResolvePath + * @inherit */ [[nodiscard]] AmOsString ResolvePath(const AmOsString& path) const override; /** - * @copydoc FileSystem::Exists + * @inherit */ [[nodiscard]] bool Exists(const AmOsString& path) const override; /** - * @copydoc FileSystem::IsDirectory + * @inherit */ [[nodiscard]] bool IsDirectory(const AmOsString& path) const override; /** - * @copydoc FileSystem::Join + * @inherit */ [[nodiscard]] AmOsString Join(const std::vector& parts) const override; /** - * @copydoc FileSystem::OpenFile + * @inherit */ - [[nodiscard]] std::shared_ptr OpenFile(const AmOsString& path, FileOpenMode mode = eFOM_READ) const override; + [[nodiscard]] std::shared_ptr OpenFile(const AmOsString& path, eFileOpenMode mode = eFileOpenMode_Read) const override; /** - * @copydoc FileSystem::StartOpenFileSystem + * @inherit */ void StartOpenFileSystem() override; /** - * @copydoc FileSystem::TryFinalizeOpenFileSystem + * @inherit */ bool TryFinalizeOpenFileSystem() override; /** - * @copydoc FileSystem::StartCloseFileSystem + * @inherit */ void StartCloseFileSystem() override; /** - * @copydoc FileSystem::TryFinalizeCloseFileSystem + * @inherit */ bool TryFinalizeCloseFileSystem() override; private: + /** + * @brief Loads the package in a background thread. + * + * @param[in] pParam The `PackageFileSystem` instance to load. + * + * @internal + */ static void LoadPackage(AmVoidPtr pParam); std::filesystem::path _packagePath; diff --git a/include/SparkyStudios/Audio/Amplitude/IO/PackageItemFile.h b/include/SparkyStudios/Audio/Amplitude/IO/PackageItemFile.h index 48e78486..41693093 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/PackageItemFile.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/PackageItemFile.h @@ -23,48 +23,56 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief A File implementation that provides access to an item in an - * Amplitude package file. + * @brief A `File` implementation that provides access to an item in an Amplitude package file. + * + * @ingroup io */ class AM_API_PUBLIC PackageItemFile : public DiskFile { public: + /** + * @brief Constructs a new `PackageItemFile` instance. + * + * @param[in] item The description of the package item. + * @param[in] packageFile The path to the package file. + * @param[in] headerSize The size of the package file header. + */ PackageItemFile(const PackageFileItemDescription* item, const std::filesystem::path& packageFile, AmSize headerSize); /** - * @copydoc DiskFile::GetPath + * @inherit */ [[nodiscard]] AmOsString GetPath() const override; /** - * @copydoc DiskFile::Eof + * @inherit */ bool Eof() override; /** - * @copydoc DiskFile::Read + * @inherit */ AmSize Read(AmUInt8Buffer dst, AmSize bytes) override; /** - * @copydoc DiskFile::Write + * @inherit * * @note Writing is disabled for packages item files. */ AmSize Write(AmConstUInt8Buffer src, AmSize bytes) override; /** - * @copydoc DiskFile::Length + * @inherit */ AmSize Length() override; /** - * @copydoc DiskFile::Seek + * @inherit */ - void Seek(AmInt64 offset, FileSeekOrigin origin) override; + void Seek(AmInt64 offset, eFileSeekOrigin origin) override; /** - * @copydoc DiskFile::Position + * @inherit */ AmSize Position() override; diff --git a/include/SparkyStudios/Audio/Amplitude/IO/Resource.h b/include/SparkyStudios/Audio/Amplitude/IO/Resource.h index d7a88e93..3fd2f195 100644 --- a/include/SparkyStudios/Audio/Amplitude/IO/Resource.h +++ b/include/SparkyStudios/Audio/Amplitude/IO/Resource.h @@ -23,13 +23,18 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief An Amplitude resource in a FileSystem. + * @brief An Amplitude resource in a `FileSystem`. * - * This base class represents a resource (sound files, assets, etc.) in a FileSystem. + * This base class represents a resource (sound files, assets, etc.) in a `FileSystem`. + * + * @ingroup io */ class AM_API_PUBLIC Resource { public: + /** + * @brief Default destructor. + */ virtual ~Resource() = default; /** diff --git a/include/SparkyStudios/Audio/Amplitude/Math/BarycentricCoordinates.h b/include/SparkyStudios/Audio/Amplitude/Math/BarycentricCoordinates.h index 3738e1eb..1db89bdc 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/BarycentricCoordinates.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/BarycentricCoordinates.h @@ -23,18 +23,20 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief Represents barycentric coordinates between a point and 3 vertices of a triangle. + * + * @ingroup math */ struct BarycentricCoordinates { /** * @brief Computes the barycentric coordinates of the intersection of a ray with a triangle. * - * @param rayOrigin The origin of the ray. - * @param rayDirection The direction of the ray. - * @param triangle The vertices of the triangle. - * @param result The result of the intersection. + * @param[in] rayOrigin The origin of the ray. + * @param[in] rayDirection The direction of the ray. + * @param[in] triangle The vertices of the triangle. + * @param[out] result The result of the intersection. * - * @return @c true if the ray intersects the triangle, @c false otherwise. + * @return `true` if the ray intersects the triangle, `false` otherwise. */ static bool RayTriangleIntersection( const AmVec3& rayOrigin, const AmVec3& rayDirection, const std::array& triangle, BarycentricCoordinates& result); @@ -45,17 +47,17 @@ namespace SparkyStudios::Audio::Amplitude BarycentricCoordinates(); /** - * @brief Computes barcentric coordinates from a position and a triangle. + * @brief Computes barycentric coordinates from a position and a triangle. * - * @param position The position of the intersection. - * @param triangle The triangle. + * @param[in] position The position of the intersection. + * @param[in] triangle The triangle. */ BarycentricCoordinates(const AmVec3& position, const std::array& triangle); /** * @brief Checks whether the coordinates are valid. * - * @return @c true if the coordinates are valid, @c false otherwise. + * @return `true` if the coordinates are valid, `false` otherwise. */ [[nodiscard]] bool IsValid() const; diff --git a/include/SparkyStudios/Audio/Amplitude/Math/CartesianCoordinateSystem.h b/include/SparkyStudios/Audio/Amplitude/Math/CartesianCoordinateSystem.h index 984f8083..82dbe4f7 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/CartesianCoordinateSystem.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/CartesianCoordinateSystem.h @@ -26,6 +26,8 @@ namespace SparkyStudios::Audio::Amplitude * * It's used to know which direction is positive along each axis, and also allows * Amplitude to convert incoming data to the internal coordinate system. + * + * @ingroup math */ class AM_API_PUBLIC CartesianCoordinateSystem { @@ -75,15 +77,15 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Constructs a converter from two cartesian coordinate systems. * - * @param from The source cartesian coordinate system. - * @param to The target cartesian coordinate system. + * @param[in] from The source cartesian coordinate system. + * @param[in] to The target cartesian coordinate system. */ Converter(const CartesianCoordinateSystem& from, const CartesianCoordinateSystem& to); /** * @brief Converts a vector from the source coordinate system to the target coordinate system. * - * @param vector The vector to convert. + * @param[in] vector The vector to convert. * * @return A vector in the target coordinate system. */ @@ -92,7 +94,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts a quaternion from the source coordinate system to the target coordinate system. * - * @param quaternion The quaternion to convert. + * @param[in] quaternion The quaternion to convert. * * @return A quaternion in the target coordinate system. */ @@ -101,7 +103,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts a scalar from the source coordinate system to the target coordinate system. * - * @param scalar The scalar to convert. + * @param[in] scalar The scalar to convert. * * @return A scalar in the target coordinate system. */ @@ -110,7 +112,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts a vector from the target coordinate system to the source coordinate system. * - * @param vector The vector to convert. + * @param[in] vector The vector to convert. * * @return A vector in the source coordinate system. */ @@ -119,7 +121,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts a quaternion from the target coordinate system to the source coordinate system. * - * @param quaternion The quaternion to convert. + * @param[in] quaternion The quaternion to convert. * * @return A quaternion in the source coordinate system. */ @@ -128,7 +130,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts a scalar from the target coordinate system to the source coordinate system. * - * @param scalar The scalar to convert. + * @param[in] scalar The scalar to convert. * * @return A scalar in the source coordinate system. */ @@ -263,7 +265,7 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] AmVec3 Convert(const AmVec3& vector, const CartesianCoordinateSystem& from) const; /** - * @biref Converts a quaternion from one coordinate system to the current one. + * @brief Converts a quaternion from one coordinate system to the current one. * * @param quaternion The quaternion to convert. * @param from The original coordinate system of the quaternion. diff --git a/include/SparkyStudios/Audio/Amplitude/Math/Curve.h b/include/SparkyStudios/Audio/Amplitude/Math/Curve.h index 106d726d..0392d11c 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/Curve.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/Curve.h @@ -28,97 +28,105 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A single point in a Curve. + * + * @ingroup math */ struct AM_API_PUBLIC CurvePoint { /** * @brief The coordinates of the point over the X axis. */ - double x; + AmReal64 x; /** * @brief The coordinates of the point over the Y axis. */ - float y; + AmReal32 y; bool operator==(const CurvePoint& rhs) const; bool operator!=(const CurvePoint& rhs) const; }; /** - * @brief A part of a Curve. + * @brief A segment of a `Curve`. * - * CurveParts allows to a curve to have different fading algorithms at the same time. - * Each CurvePart has a start and end point, and the fading algorithm which moves the value + * A `CurvePart` allows a curve to have different fading algorithms at the same time. + * Each `CurvePart` has a start and end point, and the fading algorithm which moves the value * from the start point to the end point. + * + * @ingroup math */ class AM_API_PUBLIC CurvePart { public: /** - * @brief Creates an empty CurvePart. + * @brief Creates an empty `CurvePart`. */ CurvePart(); + + /** + * @brief Destroys this `CurvePart`. + */ ~CurvePart(); /** - * @brief Initializes this CurvePart from a definition. + * @brief Initializes this `CurvePart` from a definition. * - * @param definition The definition of the curve part generated - * from a flatbuffer binary. + * @param[in] definition The definition of the curve part generated + * from a flatbuffer binary. */ void Initialize(const CurvePartDefinition* definition); /** - * @brief Returns the start point of this CurvePart. + * @brief Returns the start point of this `CurvePart`. * - * @return The start point of this CurvePart. + * @return The start point of this `CurvePart`. */ [[nodiscard]] const CurvePoint& GetStart() const; /** - * @brief Sets the start point of this CurvePart. + * @brief Sets the start point of this `CurvePart`. * - * @param start The new start point. + * @param[in] start The new start point. */ void SetStart(const CurvePoint& start); /** - * @brief Returns the end point of this CurvePart. + * @brief Returns the end point of this `CurvePart`. * - * @return The end point of this CurvePart. + * @return The end point of this `CurvePart`. */ [[nodiscard]] const CurvePoint& GetEnd() const; /** - * @brief Sets the end point of this CurvePart. + * @brief Sets the end point of this `CurvePart`. * - * @param end The new end point. + * @param[in] end The new end point. */ void SetEnd(const CurvePoint& end); /** - * @brief Returns the Fader of this CurvePart. + * @brief Returns the Fader of this `CurvePart`. * - * @return The Fader of this CurvePart. + * @return The `FaderInstance` of this `CurvePart`. */ [[nodiscard]] FaderInstance* GetFader() const; /** - * @brief Sets the Fader of this CurvePart. + * @brief Sets the fader of this `CurvePart`. * - * @param fader The new Fader. + * @param[in] fader The name of the `Fader` to set. */ void SetFader(const AmString& fader); /** * @brief Gets the Y coordinates of a point given its coordinates over the X axis. * - * @param x The coordinates of the point over the X axis. + * @param[in] x The coordinates of the point over the X axis. * * @return The Y coordinates of the point. */ - [[nodiscard]] float Get(double x) const; + [[nodiscard]] AmReal32 Get(AmReal64 x) const; private: CurvePoint _start; @@ -129,32 +137,37 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief A Curve which describe the variation of a value (on the Y-axis) according to another (on the X-axis). + * @brief A `Curve` which describe the variation of a value (on the Y-axis) according to another (on the X-axis). + * + * @ingroup math */ class AM_API_PUBLIC Curve { public: + /** + * @brief Creates an empty `Curve`. + */ Curve(); /** * @brief Initializes curve parts from the given definition. * - * @param definition The curve definition data. + * @param[in] definition The curve definition data. */ void Initialize(const CurveDefinition* definition); /** * @brief Get the curve value corresponding to the given X value. * - * @param x The X value. + * @param[in] x The X value. * * @return The curve value. */ - [[nodiscard]] float Get(double x) const; + [[nodiscard]] AmReal32 Get(AmReal64 x) const; private: // Finds the curve part corresponding to the given X value. - [[nodiscard]] const CurvePart* _findCurvePart(double x) const; + [[nodiscard]] const CurvePart* _findCurvePart(AmReal64 x) const; // The parts of the curve. std::vector _parts; diff --git a/include/SparkyStudios/Audio/Amplitude/Math/Geometry.h b/include/SparkyStudios/Audio/Amplitude/Math/Geometry.h index fb987fdb..d2c9d257 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/Geometry.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/Geometry.h @@ -23,23 +23,40 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief Represents a triangulated face. + * + * A face is defined by three vertices. This structure is optimized for use + * with an existing indexed vertex array, so only the indices of each face's + * vertex need to be provided. + * + * @ingroup math */ struct AM_API_PUBLIC Face { - AmSize m_A; - AmSize m_B; - AmSize m_C; + AmSize m_A; ///< Index of the first vertex. + AmSize m_B; ///< Index of the second vertex. + AmSize m_C; ///< Index of the third vertex. + /** + * @brief Checks if the face is valid. + * + * @return `true` if the face is valid, `false` otherwise. + */ [[nodiscard]] bool IsValid() const; }; /** - * @brief Represents a triangulated edge. + * @brief Represents an edge. + * + * An edge is defined by two vertices. This structure is optimized for use + * with an existing indexed vertex array, so only the indices of each edge's + * vertex need to be provided. + * + * @ingroup math */ struct AM_API_PUBLIC Edge { - AmSize m_E0; - AmSize m_E1; + AmSize m_E0; ///< Index of the first vertex. + AmSize m_E1; ///< Index of the second vertex. bool operator<(const Edge& other) const; bool operator==(const Edge& other) const; diff --git a/include/SparkyStudios/Audio/Amplitude/Math/Orientation.h b/include/SparkyStudios/Audio/Amplitude/Math/Orientation.h index df6d325b..3adac53f 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/Orientation.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/Orientation.h @@ -29,6 +29,8 @@ namespace SparkyStudios::Audio::Amplitude * or from a forward and up vector. Once built, the orientation is stored in the ZYX representation * (yaw, pitch, roll), in the ZYZ representation, in the quaternion representation, and in forward-up * vectors representation. + * + * @ingroup math */ struct AM_API_PUBLIC Orientation { @@ -42,24 +44,24 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Constructs an Orientation instance with the given yaw, pitch, and roll angles. * - * @param yaw The angle of rotation around the X-axis in radians. - * @param pitch The angle of rotation around the Y-axis in radians. - * @param roll The angle of rotation around the Z-axis in radians. + * @param[in] yaw The angle of rotation around the X-axis in radians. + * @param[in] pitch The angle of rotation around the Y-axis in radians. + * @param[in] roll The angle of rotation around the Z-axis in radians. */ Orientation(AmReal32 yaw, AmReal32 pitch, AmReal32 roll); /** * @brief Constructs an Orientation instance from a forward and up vector. * - * @param forward The forward vector of the orientation. - * @param up The up vector of the orientation. + * @param[in] forward The forward vector of the orientation. + * @param[in] up The up vector of the orientation. */ Orientation(AmVec3 forward, AmVec3 up); /** * @brief Constructs an Orientation instance from a quaternion. * - * @param quaternion The quaternion representing the orientation. + * @param[in] quaternion The quaternion representing the orientation. */ Orientation(AmQuat quaternion); @@ -145,7 +147,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Converts the orientation to a look-at matrix. * - * @param eye The eye's location. + * @param[in] eye The eye's location. * * @return A look-at matrix representing the current orientation, with the eye at the given location. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Math/Shape.h b/include/SparkyStudios/Audio/Amplitude/Math/Shape.h index 24e6defc..8fbedb57 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/Shape.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/Shape.h @@ -30,54 +30,60 @@ namespace SparkyStudios::Audio::Amplitude class SphereShapeDefinition; /** - * @brief A Shape. + * @brief A geometrical closed 3D shape. * - * A Shape define a zone in the world where listeners and sound sources can be localized. This is used by the - * engine to detect the position on these objects and apply a specific effect (environmental effect or - * attenuation effect) to them. + * A `Shape` defines a zone in the world where game objects (listener, sound sources, entities, etc.) can + * be localized. Shapes are used in many places of the engine, like to define a sound attenuation shape, or to build a room. + * + * @ingroup math */ class AM_API_PUBLIC Shape { public: /** - * @brief Creates a new Shape from a definition. + * @brief Creates a new `Shape` from a definition. + * + * @param[in] definition The definition of the shape generated + * from a flatbuffer binary. * - * @param definition The definition of the shape generated - * from a flatbuffer binary. + * @warning This method is intended for internal usage only. */ static Shape* Create(const ShapeDefinition* definition); /** - * @brief Construct a new Shape. + * @brief Constructs a new `Shape`. */ Shape(); + /** + * @brief Default destructor. + */ virtual ~Shape() = default; /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param entity The entity from which calculate the distance. + * @param[in] entity The entity from which calculate the distance. * - * @return The shortest distance from the location to the edge - * of this shape. If negative, the given location in outside the shape. + * @return The shortest distance from the entity location to the edge + * of this shape. If negative, the given entity in outside the shape. */ [[nodiscard]] virtual AmReal32 GetShortestDistanceToEdge(const Entity& entity); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param listener The listener from which calculate the distance. + * @param[in] listener The listener from which calculate the distance. * - * @return The shortest distance from the location to the edge - * of this shape. If negative, the given location in outside the shape. + * @return The shortest distance from the listener location to the edge + * of this shape. If negative, the given listener in outside the shape. */ [[nodiscard]] virtual AmReal32 GetShortestDistanceToEdge(const Listener& listener); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param location The location from which calculate the distance. + * @param[in] location The location from which calculate the distance. * * @return The shortest distance from the location to the edge * of this shape. If negative, the given location in outside the shape. @@ -87,41 +93,41 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the given entity is contained in this shape. * - * @param entity The entity to check. + * @param[in] entity The entity to check. * - * @return true if the shape contains the entity, false otherwise. + * @return `true` if the shape contains the entity, `false` otherwise. */ [[nodiscard]] virtual bool Contains(const Entity& entity); /** * @brief Checks if the given listener is contained in this shape. * - * @param listener The listener to check. + * @param[in] listener The listener to check. * - * @return true if the shape contains the listener, false otherwise. + * @return `true` if the shape contains the listener, `false` otherwise. */ [[nodiscard]] virtual bool Contains(const Listener& listener); /** * @brief Checks if the given position is contained in this shape. * - * @param location The 3D position to check. + * @param[in] location The 3D position to check. * - * @return true if the shape contains the given position, false otherwise. + * @return `true` if the shape contains the given position, `false` otherwise. */ [[nodiscard]] virtual bool Contains(const AmVec3& location) = 0; /** - * @brief Set the location of this shape in the 3D environment. + * @brief Sets the location of this shape in the 3D environment. * - * @param location The shape location. + * @param[in] location The shape location. */ void SetLocation(const AmVec3& location); /** - * @brief Set the orientation of this shape. + * @brief Sets the orientation of this shape. * - * @param orientation The new orientation. + * @param[in] orientation The new orientation. */ void SetOrientation(const Orientation& orientation); @@ -133,28 +139,28 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] const Orientation& GetOrientation() const; /** - * @brief Get the LookAt transformation matrix for this shape. + * @brief Gets the LookAt transformation matrix for this shape. * - * @return The lookAt transformation matrix. + * @return The look-at transformation matrix. */ [[nodiscard]] const AmMat4& GetLookAt() const; /** - * @brief Get the position of this shape in the 3D environment. + * @brief Gets the position of this shape in the 3D environment. * * @return The shape's position. */ [[nodiscard]] const AmVec3& GetLocation() const; /** - * @brief Get the position of this shape in the 3D environment. + * @brief Gets the position of this shape in the 3D environment. * * @return The shape's position. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Get the up vector of the zone. + * @brief Gets the up vector of the zone. * * @return The up vector. */ @@ -170,60 +176,75 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief A shape that represents a zone in the world. + * @brief A tuple of shapes that represents a zone in the world. + * + * This shape is mainly used by attenuations and environments. It's composed of an inner `Shape` and an outer `Shape`. + * The inner shape is the place where the @ref GetFactor factor is equal to one all the time. The outer shape is the place where the + * @ref GetFactor factor increase or decrease according to the shortest distance of the game object from the outer edge. * - * This shape is mainly used by attenuations and environments. It's composed of an inner shape and an outer shape. - * The inner shape is the zone where the factor is equal to one all the time. The outer shape is the zone where the - * factor increase or decrease according to the shortest distance of the game object from the outer edge. + * If the game object is outside the outer shape (thus, outside the zone), the @ref GetFactor factor is zero. * - * If the game object is outside the outer shape (thus, outside the zone), the factor is zero. + * @ingroup math */ class AM_API_PUBLIC Zone { public: + /** + * @brief Creates a new `Zone` from the given inner and outer shapes. + * + * @param[in] inner The inner shape. + * @param[in] outer The outer shape. + */ explicit Zone(Shape* inner, Shape* outer); + + /** + * @brief Default destructor. + */ virtual ~Zone() = default; /** - * @brief Gets the factor (a value in the range [0, 1]) according to the position - * of the given entity in the zone. + * @brief Gets the factor according to the position of the given entity in the zone. * - * @param entity The entity to get the factor for. + * @param[in] entity The entity to get the factor for. * * @return The factor. + * + * @note The factor is a value in the range [0, 1]. */ - [[nodiscard]] virtual AmReal32 GetFactor(const Entity& entity) + [[nodiscard]] virtual AM_INLINE AmReal32 GetFactor(const Entity& entity) { return GetFactor(entity.GetLocation()); } /** - * @brief Gets the factor (a value in the range [0, 1]) according to the position - * of the given listener in the zone. + * @brief Gets the factor according to the position of the given listener in the zone. * - * @param listener The listener to get the factor for. + * @param[in] listener The listener to get the factor for. * * @return The factor. + * + * @note The factor is a value in the range [0, 1]. */ - [[nodiscard]] virtual AmReal32 GetFactor(const Listener& listener) + [[nodiscard]] virtual AM_INLINE AmReal32 GetFactor(const Listener& listener) { return GetFactor(listener.GetLocation()); } /** - * @brief Gets the factor (a value in the range [0, 1]) according to the given - * position in the zone. + * @brief Gets the factor according to the given position in the zone. * - * @param position The position in the zone to get the factor for. + * @param[in] position The position in the zone to get the factor for. * * @return The factor. + * + * @note The factor is a value in the range [0, 1]. */ [[nodiscard]] virtual AmReal32 GetFactor(const AmVec3& position) = 0; /** * @brief Sets the location of this zone in the 3D environment. * - * @param location The zone location. + * @param[in] location The zone location. */ void SetLocation(const AmVec3& location); @@ -237,7 +258,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Sets the orientation of this zone. * - * @param orientation The new orientation. + * @param[in] orientation The new orientation. */ void SetOrientation(const Orientation& orientation); @@ -249,14 +270,14 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] const Orientation& GetOrientation() const; /** - * @brief Get the direction vector of the zone. + * @brief Gets the direction vector of the zone. * * @return The direction vector. */ [[nodiscard]] AmVec3 GetDirection() const; /** - * @brief Get the up vector of the zone. + * @brief Gets the up vector of the zone. * * @return The up vector. */ @@ -276,6 +297,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A box shape, defined by a width, an height, and a depth. + * + * @ingroup math */ class AM_API_PUBLIC BoxShape : public Shape { @@ -283,97 +306,99 @@ namespace SparkyStudios::Audio::Amplitude public: /** - * @brief Creates a new BoxShape from a definition. + * @brief Creates a new `BoxShape` from a definition. * - * @param definition The definition of the box shape generated - * from a flatbuffer binary. + * @param[in] definition The definition of the shape generated + * from a flatbuffer binary. + * + * @warning This method is intended for internal usage only. */ static BoxShape* Create(const BoxShapeDefinition* definition); /** - * @brief Construct a new Box Shape. + * @brief Constructs a new `BoxShape`. * - * @param halfWidth The half width of the box shape. - * @param halfHeight The half height of the box shape. - * @param halfDepth The half depth of the box shape. + * @param[in] halfWidth The half width of the box shape. + * @param[in] halfHeight The half height of the box shape. + * @param[in] halfDepth The half depth of the box shape. */ explicit BoxShape(AmReal32 halfWidth, AmReal32 halfHeight, AmReal32 halfDepth); /** - * @brief Construct a new Box Shape. + * @brief Constructs a new `BoxShape`. * - * @param position The position of the box shape. - * @param dimensions The dimensions of the box shape. + * @param[in] position The position of the box shape. + * @param[in] dimensions The dimensions of the box shape. */ explicit BoxShape(const AmVec3& position, const AmVec3& dimensions); /** - * @brief Get the half width of the box shape. + * @brief Gets the half width of the `BoxShape`. * * @return The box shape's half width. */ [[nodiscard]] AmReal32 GetHalfWidth() const; /** - * @brief Get the half height of the box shape. + * @brief Gets the half height of the `BoxShape`. * * @return The box shape's half height. */ [[nodiscard]] AmReal32 GetHalfHeight() const; /** - * @brief Get the half depth of the box shape. + * @brief Gets the half depth of the `BoxShape`. * * @return The box shape's half depth. */ [[nodiscard]] AmReal32 GetHalfDepth() const; /** - * @brief Get the width of the box shape. + * @brief Gets the width of the `BoxShape`. * * @return The box shape's width. */ [[nodiscard]] AmReal32 GetWidth() const; /** - * @brief Get the height of the box shape. + * @brief Gets the height of the `BoxShape`. * * @return The box shape's height. */ [[nodiscard]] AmReal32 GetHeight() const; /** - * @brief Get the depth of the box shape. + * @brief Gets the depth of the `BoxShape`. * * @return The box shape's depth. */ [[nodiscard]] AmReal32 GetDepth() const; /** - * @brief Set the half width of the box shape. + * @brief Sets the half width of the `BoxShape`. * - * @param halfWidth The new box shape's half width. + * @param[in] halfWidth The new box shape's half width. */ void SetHalfWidth(AmReal32 halfWidth); /** - * @brief Set the half height of the box shape. + * @brief Sets the half height of the `BoxShape`. * - * @param halfHeight The new box shape's half height. + * @param[in] halfHeight The new box shape's half height. */ void SetHalfHeight(AmReal32 halfHeight); /** - * @brief Set the half depth of the box shape. + * @brief Sets the half depth of the `BoxShape`. * - * @param halfDepth The new box shape's half depth. + * @param[in] halfDepth The new box shape's half depth. */ void SetHalfDepth(AmReal32 halfDepth); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param location The location from which calculate the distance. + * @param[in] location The location from which calculate the distance. * * @return The shortest distance from the location to the edge * of this shape. If negative, the given location in outside the shape. @@ -383,16 +408,16 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the given position is contained in this shape. * - * @param location The 3D position to check. + * @param[in] location The 3D position to check. * - * @return true if the shape contains the given position, false otherwise. + * @return `true` if the shape contains the given position, `false` otherwise. */ [[nodiscard]] bool Contains(const AmVec3& location) final; /** - * @brief Get the closest point to the given location. + * @brief Gets the closest point to the given location. * - * @param location The location to get the closest point for. + * @param[in] location The location to get the closest point for. * * @return The closest point to the given location. */ @@ -415,6 +440,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A capsule shape, defined by a radius and an height. + * + * @ingroup math */ class AM_API_PUBLIC CapsuleShape : public Shape { @@ -422,67 +449,69 @@ namespace SparkyStudios::Audio::Amplitude public: /** - * @brief Creates a new CapsuleShape from a definition. + * @brief Creates a new `CapsuleShape` from a definition. + * + * @param[in] definition The definition of the shape generated + * from a flatbuffer binary. * - * @param definition The definition of the capsule shape generated - * from a flatbuffer binary. + * @warning This method is intended for internal usage only. */ static CapsuleShape* Create(const CapsuleShapeDefinition* definition); /** - * @brief Construct a new Capsule Shape. + * @brief Constructs a new `CapsuleShape`. * - * @param radius The capsule radius. - * @param halfHeight The capsule half height. + * @param[in] radius The capsule radius. + * @param[in] halfHeight The capsule half height. */ explicit CapsuleShape(AmReal32 radius, AmReal32 halfHeight); /** - * @brief Get the radius of the capsule shape. + * @brief Gets the radius of the capsule shape. * * @return The capsule's radius. */ [[nodiscard]] AmReal32 GetRadius() const; /** - * @brief Get the half height of the capsule shape. + * @brief Gets the half height of the capsule shape. * * @return The capsule's half height. */ [[nodiscard]] AmReal32 GetHalfHeight() const; /** - * @brief Get the diameter of the capsule shape. + * @brief Gets the diameter of the capsule shape. * * @return The capsule's diameter. */ [[nodiscard]] AmReal32 GetDiameter() const; /** - * @brief Get the height of the capsule shape. + * @brief Gets the height of the capsule shape. * * @return The capsule's height. */ [[nodiscard]] AmReal32 GetHeight() const; /** - * @brief Set the radius of the capsule shape. + * @brief Sets the radius of the capsule shape. * - * @param radius The capsule's radius. + * @param[in] radius The capsule's radius. */ void SetRadius(AmReal32 radius); /** - * @brief Set the half height of the capsule shape. + * @brief Sets the half height of the capsule shape. * - * @param halfHeight The capsule's half height. + * @param[in] halfHeight The capsule's half height. */ void SetHalfHeight(AmReal32 halfHeight); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param location The location from which calculate the distance. + * @param[in] location The location from which calculate the distance. * * @return The shortest distance from the location to the edge * of this shape. If negative, the given location in outside the shape. @@ -492,9 +521,9 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the given position is contained in this shape. * - * @param location The 3D position to check. + * @param[in] location The 3D position to check. * - * @return true if the shape contains the given position, false otherwise. + * @return `true` if the shape contains the given position, `false` otherwise. */ [[nodiscard]] bool Contains(const AmVec3& location) final; @@ -509,6 +538,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A cone shape, defined by a radius and an height. + * + * @ingroup math */ class AM_API_PUBLIC ConeShape : public Shape { @@ -518,58 +549,60 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new ConeShape from a definition. * - * @param definition The definition of the cone shape generated - * from a flatbuffer binary. + * @param[in] definition The definition of the shape generated + * from a flatbuffer binary. + * + * @warning This method is intended for internal usage only. */ static ConeShape* Create(const ConeShapeDefinition* definition); /** - * @brief Construct a new Cone Shape. + * @brief Constructs a new `ConeShape`. * - * @param radius The radius of the cone's base. - * @param height The height of the cone. + * @param[in] radius The radius of the cone's base. + * @param[in] height The height of the cone. */ explicit ConeShape(AmReal32 radius, AmReal32 height); /** - * @brief Get the radius of the cone shape. + * @brief Gets the radius of the cone shape. * * @return The cone base's radius. */ [[nodiscard]] AmReal32 GetRadius() const; /** - * @brief Get the diameter of the cone shape. + * @brief Gets the diameter of the cone shape. * * @return The cone base's diameter. */ [[nodiscard]] AmReal32 GetDiameter() const; /** - * @brief Get the height of the cone shape. + * @brief Gets the height of the cone shape. * * @return The cone's height. */ [[nodiscard]] AmReal32 GetHeight() const; /** - * @brief Set the radius of the cone shape. + * @brief Sets the radius of the cone shape. * - * @param radius The cone base's radius. + * @param[in] radius The cone base's radius. */ void SetRadius(AmReal32 radius); /** - * @brief Set the height of the cone shape. + * @brief Sets the height of the cone shape. * - * @param height The cone's height. + * @param[in] height The cone's height. */ void SetHeight(AmReal32 height); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param location The location from which calculate the distance. + * @param[in] location The location from which calculate the distance. * * @return The shortest distance from the location to the edge * of this shape. If negative, the given location in outside the shape. @@ -579,7 +612,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the given position is contained in this shape. * - * @param location The 3D position to check. + * @param[in] location The 3D position to check. * * @return true if the shape contains the given position, false otherwise. */ @@ -594,6 +627,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A sphere shape, defined by a radius. + * + * @ingroup math */ class AM_API_PUBLIC SphereShape : public Shape { @@ -603,43 +638,45 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new SphereShape from a definition. * - * @param definition The definition of the sphere shape generated - * from a flatbuffer binary. + * @param[in] definition The definition of the shape generated + * from a flatbuffer binary. + * + * @warning This method is intended for internal usage only. */ static SphereShape* Create(const SphereShapeDefinition* definition); /** - * @brief Construct a new Sphere Shape. + * @brief Constructs a new `SphereShape`. * - * @param radius The sphere's radius. + * @param[in] radius The sphere's radius. */ explicit SphereShape(AmReal32 radius); /** - * @brief Get the radius of the sphere shape. + * @brief Gets the radius of the sphere shape. * * @return The sphere's radius. */ [[nodiscard]] AmReal32 GetRadius() const; /** - * @brief Get the diameter of the sphere shape. + * @brief Gets the diameter of the sphere shape. * * @return The sphere's diameter. */ [[nodiscard]] AmReal32 GetDiameter() const; /** - * @brief Set the radius of the sphere shape. + * @brief Sets the radius of the sphere shape. * - * @param radius The sphere's radius. + * @param[in] radius The sphere's radius. */ void SetRadius(AmReal32 radius); /** - * @brief Get the shortest distance to the edge of this shape. + * @brief Gets the shortest distance to the edge of this shape. * - * @param location The location from which calculate the distance. + * @param[in] location The location from which calculate the distance. * * @return The shortest distance from the location to the edge * of this shape. If negative, the given location in outside the shape. @@ -649,7 +686,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the given position is contained in this shape. * - * @param location The 3D position to check. + * @param[in] location The 3D position to check. * * @return true if the shape contains the given position, false otherwise. */ @@ -661,35 +698,91 @@ namespace SparkyStudios::Audio::Amplitude AmReal32 _radius; }; + /** + * @brief A `Zone` built with an inner `BoxShape` and an outer `BoxShape`. + * + * @ingroup math + */ class AM_API_PUBLIC BoxZone : public Zone { public: + /** + * @brief Constructs a new `BoxZone`. + * + * @param[in] inner The inner `BoxShape`. + * @param[in] outer The outer `BoxShape`. + */ BoxZone(BoxShape* inner, BoxShape* outer); + /** + * @inherit + */ [[nodiscard]] AmReal32 GetFactor(const AmVec3& position) final; }; + /** + * @brief A `Zone` built with an inner `CapsuleShape` and an outer `CapsuleShape`. + * + * @ingroup math + */ class AM_API_PUBLIC CapsuleZone : public Zone { public: + /** + * @brief Constructs a new `CapsuleZone`. + * + * @param[in] inner The inner `CapsuleShape`. + * @param[in] outer The outer `CapsuleShape`. + */ CapsuleZone(CapsuleShape* inner, CapsuleShape* outer); + /** + * @inherit + */ [[nodiscard]] AmReal32 GetFactor(const AmVec3& position) final; }; + /** + * @brief A `Zone` built with an inner `ConeShape` and an outer `ConeShape`. + * + * @ingroup math + */ class AM_API_PUBLIC ConeZone : public Zone { public: + /** + * @brief Constructs a new `ConeZone`. + * + * @param[in] inner The inner `ConeShape`. + * @param[in] outer The outer `ConeShape`. + */ ConeZone(ConeShape* inner, ConeShape* outer); + /** + * @inherit + */ [[nodiscard]] AmReal32 GetFactor(const AmVec3& position) final; }; + /** + * @brief A `Zone` built with an inner `SphereShape` and an outer `SphereShape`. + * + * @ingroup math + */ class AM_API_PUBLIC SphereZone : public Zone { public: + /** + * @brief Constructs a new `SphereZone`. + * + * @param[in] inner The inner `SphereShape`. + * @param[in] outer The outer `SphereShape`. + */ SphereZone(SphereShape* inner, SphereShape* outer); + /** + * @inherit + */ [[nodiscard]] AmReal32 GetFactor(const AmVec3& position) final; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/include/SparkyStudios/Audio/Amplitude/Math/SphericalPosition.h b/include/SparkyStudios/Audio/Amplitude/Math/SphericalPosition.h index d8cb8433..ff38d71e 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/SphericalPosition.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/SphericalPosition.h @@ -22,54 +22,59 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Describes the coordinates of a point on a sphere's surface, relative - * to the center of the sphere. + * @brief Spherical coordinates representation. + * + * Describes the coordinates of a point on a sphere's surface, relative to + * the center of that sphere. + * + * @ingroup math */ struct AM_API_PUBLIC SphericalPosition { /** - * @brief Create a spherical position from a 3D position in world space. + * @brief Creates a spherical position from a 3D position in world space. * - * @param position The position in world space. + * @param[in] position The position in world space. */ static SphericalPosition FromWorldSpace(const AmVec3& position); /** - * @brief Create a spherical position from a 3D position in world space. This - * method is optimized for use in HRTF (Head-Related Transfer Function) space, - * where the azimuth is rotated 90 degrees around the z-axis + * @brief Creates a spherical position from a 3D position in world space. * - * @param position The position in world space. + * This method is optimized for use in HRTF (Head-Related Transfer Function) space, + * where the azimuth is rotated 90 degrees around the z-axis. + * + * @param[in] position The position in world space. */ static SphericalPosition ForHRTF(const AmVec3& position); /** - * @brief Create a spherical position from given azimuth and elevation in degrees. + * @brief Creates a spherical position from given azimuth and elevation in degrees. * - * @param azimuthDegrees The azimuth in degrees. - * @param elevationDegrees The elevation in degrees. - * @param radius The distance from the center of the sphere to the point. + * @param[in] azimuthDegrees The azimuth in degrees. + * @param[in] elevationDegrees The elevation in degrees. + * @param[in] radius The distance from the center of the sphere to the point. * * @return A spherical position representing the given azimuth and elevation in degrees. */ static SphericalPosition FromDegrees(AmReal32 azimuthDegrees, AmReal32 elevationDegrees, AmReal32 radius = 1.0f); /** - * @brief Create a spherical position with default values (azimuth = 0, elevation = 0, radius = 1). + * @brief Creates a spherical position with default values (azimuth = 0, elevation = 0, radius = 1). */ SphericalPosition() = default; /** - * @brief Create a spherical position with given azimuth, elevation, and radius. + * @brief Creates a spherical position with given azimuth, elevation, and radius. * - * @param azimuth The rotation around the z-axis in radians. - * @param elevation The rotation around the x-axis in radians. - * @param radius The distance from the center of the sphere to the point. + * @param[in] azimuth The rotation around the z-axis in radians. + * @param[in] elevation The rotation around the x-axis in radians. + * @param[in] radius The distance from the center of the sphere to the point. */ SphericalPosition(AmReal32 azimuth, AmReal32 elevation, AmReal32 radius = 1.0f); /** - * @brief Flip the azimuth of the spherical position and returns a new instance. + * @brief Flips the azimuth of the spherical position and returns a new instance. * * @return A new spherical position with the azimuth flipped. */ @@ -78,7 +83,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Rotates the spherical position with the given rotation and returns a new instance. * - * @param rotation The rotation to apply to the spherical position. + * @param[in] rotation The rotation to apply to the spherical position. * * @return A rotated spherical position. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Math/Utils.h b/include/SparkyStudios/Audio/Amplitude/Math/Utils.h index cb535144..20a2c8dd 100644 --- a/include/SparkyStudios/Audio/Amplitude/Math/Utils.h +++ b/include/SparkyStudios/Audio/Amplitude/Math/Utils.h @@ -26,6 +26,11 @@ namespace SparkyStudios::Audio::Amplitude { + /** + * @brief A structure containing control points for a Bezier curve. + * + * @ingroup math + */ struct BeizerCurveControlPoints { /** @@ -54,18 +59,49 @@ namespace SparkyStudios::Audio::Amplitude AmInt32 state; } gLCG = { 4321 }; - AM_API_PRIVATE AM_INLINE float AmDitherReal32(const AmReal32 ditherMin, const AmReal32 ditherMax) + /** + * @brief Generates a random number between `ditherMin` and `ditherMax`. + * + * @param[in] ditherMin The minimum value for the random number. + * @param[in] ditherMax The maximum value for the random number. + * + * @return A random number between `ditherMin` and `ditherMax`. + * + * @ingroup math + */ + AM_API_PRIVATE AM_INLINE AmReal32 AmDitherReal32(const AmReal32 ditherMin, const AmReal32 ditherMax) { gLCG.state = (AM_LCG_A * gLCG.state + AM_LCG_C) % AM_LCG_M; const AmReal32 x = gLCG.state / (double)0x7FFFFFFF; return ditherMin + x * (ditherMax - ditherMin); } + /** + * @brief Converts a 32-bit floating-point audio sample to a fixed-point representation. + * + * @param[in] x The 32-bit floating-point audio sample to convert. + * + * @return The fixed-point representation of the input 32-bit floating-point audio sample. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmInt32 AmFloatToFixedPoint(const AmReal32 x) { return static_cast(x * kAmFixedPointUnit); } + /** + * @brief Converts a 16-bit signed integer audio sample to a 32-bit floating-point representation. + * + * @param[in] x The 16-bit signed integer audio sample to convert. + * + * @return The 32-bit floating-point representation of the input 16-bit signed integer audio sample. + * + * @tip For more accurate conversion, the SDK should be compiled with the `AM_ACCURATE_CONVERSION` + * macro defined. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmReal32 AmInt16ToReal32(const AmInt16 x) { auto y = static_cast(x); @@ -83,6 +119,18 @@ namespace SparkyStudios::Audio::Amplitude return y; } + /** + * @brief Converts a 32-bit signed integer audio sample to a 32-bit floating-point representation. + * + * @param[in] x The 32-bit signed integer audio sample to convert. + * + * @return The 32-bit floating-point representation of the input 32-bit signed integer audio sample. + * + * @tip For more accurate conversion, the SDK should be compiled with the `AM_ACCURATE_CONVERSION` + * macro defined. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmReal32 AmInt32ToReal32(const AmInt32 x) { auto y = static_cast(x); @@ -100,6 +148,19 @@ namespace SparkyStudios::Audio::Amplitude return y; } + /** + * @brief Converts a 32-bit floating-point audio sample to a 16-bit signed integer representation. + * + * @param[in] x The 32-bit floating-point audio sample to convert. + * @param[in] dithering If `true`, adds a dithering noise to the output. + * + * @return The 16-bit signed integer representation of the input 32-bit floating-point audio sample. + * + * @tip For more accurate conversion, the SDK should be compiled with the `AM_ACCURATE_CONVERSION` + * macro defined. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmInt16 AmReal32ToInt16(const AmReal32 x, bool dithering = false) { AmReal32 y = x; @@ -125,6 +186,19 @@ namespace SparkyStudios::Audio::Amplitude return static_cast(y); } + /** + * @brief Computes the Catmull-Rom interpolation value at a given time `t` between four points. + * + * @param[in] t The time value between 0 and 1. + * @param[in] p0 The first point. + * @param[in] p1 The second point. + * @param[in] p2 The third point. + * @param[in] p3 The fourth point. + * + * @return The Catmull-Rom interpolation value at the given time `t`. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmReal32 CatmullRom(const AmReal32 t, const AmReal32 p0, const AmReal32 p1, const AmReal32 p2, const AmReal32 p3) { @@ -138,6 +212,19 @@ namespace SparkyStudios::Audio::Amplitude // clang-format on } + /** + * @brief Computes the Doppler factor for a sound source at a given location. + * + * @param[in] locationDelta The distance vector from the listener to the sound source. + * @param[in] sourceVelocity The velocity of the sound source. + * @param[in] listenerVelocity The velocity of the listener. + * @param[in] soundSpeed The speed of sound. + * @param[in] dopplerFactor The Doppler factor. + * + * @return The computed Doppler factor. + * + * @ingroup math + */ AM_API_PRIVATE AM_INLINE AmReal32 ComputeDopplerFactor( const AmVec3& locationDelta, const AmVec3& sourceVelocity, @@ -166,9 +253,13 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the next power of 2 of a given number. * - * @param val The number. + * @tparam T An integer type, a floating-point type, or a any other type where operator *= is defined. + * + * @param[in] val The number. * * @return The next power of 2. + * + * @ingroup math */ template AM_API_PRIVATE AM_INLINE T NextPowerOf2(const T& val) @@ -183,11 +274,14 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Computes the value base^exp using the squared exponentiation method. * - * @tparam T An integer type, a floating-point type, or a any other type where operatror *= is defined. - * @param base Input of the power function. - * @param exp The exponent of the power function. Must be non-negative. + * @tparam T An integer type, a floating-point type, or a any other type where operator *= is defined. + + * @param[in] base Input of the power function. + * @param[in] exp The exponent of the power function. Must be non-negative. * * @return The result of raising the base to the power of the exponent. + * + * @ingroup math */ template AM_API_PRIVATE AM_INLINE T IntegerPow(T base, AmInt32 exp) @@ -214,11 +308,13 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns a direction vector relative to a given position and rotation. * - * @param originPosition Origin position of the direction. - * @param originRotation Origin rotation of the direction. - * @param position Target position of the direction. + * @param[in] originPosition Origin position of the direction. + * @param[in] originRotation Origin rotation of the direction. + * @param[in] position Target position of the direction. * * @return A relative direction vector (not normalized). + * + * @ingroup math */ AM_API_PRIVATE AM_INLINE AmVec3 GetRelativeDirection(const AmVec3& originPosition, const AmQuat& originRotation, const AmVec3& position) { @@ -228,10 +324,12 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Finds the greatest common divisor (GCD) of two integers. * - * @param a First integer. - * @param b Second integer. + * @param[in] a First integer. + * @param[in] b Second integer. * * @return The greatest common divisor of a and b. + * + * @ingroup math */ AM_API_PRIVATE AM_INLINE AmInt64 FindGCD(AmInt64 a, AmInt64 b) { diff --git a/include/SparkyStudios/Audio/Amplitude/Mixer/Amplimix.h b/include/SparkyStudios/Audio/Amplitude/Mixer/Amplimix.h index 7a5f15e6..a62bfa79 100644 --- a/include/SparkyStudios/Audio/Amplitude/Mixer/Amplimix.h +++ b/include/SparkyStudios/Audio/Amplitude/Mixer/Amplimix.h @@ -34,65 +34,278 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Called just before the mixer process audio data. + * + * @param[in] mixer The Amplimix instance. + * @param[in] buffer The audio buffer to be mixed. + * @param[in] frames The number of audio frames to be mixed. + * + * @ingroup mixer */ AM_CALLBACK(void, BeforeMixCallback)(Amplimix* mixer, AmVoidPtr buffer, AmUInt32 frames); /** * @brief Called just after the mixer process audio data. + * + * @param[in] mixer The Amplimix instance. + * @param[in] buffer The audio buffer that has been mixed. + * @param[in] frames The number of audio frames that have been mixed. + * + * @ingroup mixer */ AM_CALLBACK(void, AfterMixCallback)(Amplimix* mixer, AmVoidPtr buffer, AmUInt32 frames); + /** + * @brief A single layer in the mixer. + * + * A mixer layer is a container for audio data and associated properties. Each layer is linked + * to a single `SoundInstance`, and manage its life cycle inside `Amplimix`. + * + * @see [Amplimix](../Amplimix/index.md) + * + * @ingroup mixer + */ class AM_API_PUBLIC AmplimixLayer { public: + /** + * @brief Default destructor. + */ virtual ~AmplimixLayer() = default; + /** + * @brief Gets the unique identifier of the layer. + * + * @return The unique identifier of the layer. + */ virtual AmUInt32 GetId() const = 0; + /** + * @brief Gets the start position of the audio data in the layer. + * + * This position is in samples, not bytes. It represents the offset from the start of the + * linked sound data, where the mixer should start playing audio. + * + * @return The start position of the audio data in the layer. + */ virtual AmUInt64 GetStartPosition() const = 0; + /** + * @brief Gets the end position of the audio data in the layer. + * + * This position is in samples, not bytes. It represents the offset from the start of the + * linked sound data, where the mixer should stop playing audio. + * + * @return The end position of the audio data in the layer. + */ virtual AmUInt64 GetEndPosition() const = 0; + /** + * @brief Gets the current position of the audio data in the layer. + * + * This position is in samples, not bytes. It represents the current offset from the start of the + * linked sound data, where the mixer is currently playing audio. + * + * @return The current playback position of the audio data in the layer. + */ virtual AmUInt64 GetCurrentPosition() const = 0; + /** + * @brief Gets the final gain of the audio data in the layer. + * + * @return The final gain of the audio data in the layer. + */ virtual AmReal32 GetGain() const = 0; + /** + * @brief Gets the stereo pan of the audio data in the layer. + * + * The stereo pan of the audio data in the layer is a value between -1.0 (left) and 1.0 (right). A + * value of -1.0 will render the audio data to the left speaker, a value of 1.0 will render the audio data + * to the right speaker, and a value of 0.0 will render the audio data to the center speaker. + * + * @return The stereo pan of the audio data in the layer. + */ virtual AmReal32 GetStereoPan() const = 0; + /** + * @brief Gets the pitch of the audio data in the layer. + * + * This value is affected by the Doppler effect. A value of 1.0 will play the audio data at its original pitch, + * while any value greater than 1.0 will increase the pitch, and any value less than 1.0 will decrease the pitch. + * + * @return The pitch of the audio data in the layer. + */ virtual AmReal32 GetPitch() const = 0; + /** + * @brief Gets the obstruction amount of the audio data in the layer. + * + * This value is useful only when the layer is associated with a sound instance that has spatialization enabled. You + * can update this value using the `SetObstruction` method from the `Entity` this layer is associated with. + * + * @return The obstruction amount of the audio data in the layer. + * + * @see [Entity](../../engine/Entity/index.md) + */ virtual AmReal32 GetObstruction() const = 0; + /** + * @brief Gets the occlusion amount of the audio data in the layer. + * + * This value is useful only when the layer is associated with a sound instance that has spatialization enabled. You + * can update this value using the `SetOcclusion` method from the `Entity` this layer is associated with. + * + * @return The occlusion amount of the audio data in the layer. + * + * @see [Entity](../../engine/Entity/index.md) + */ virtual AmReal32 GetOcclusion() const = 0; + /** + * @brief Gets the play speed of the audio data in the layer. + * + * This values affects the final @ref GetPitch pitch. + * + * @return The play speed of the audio data in the layer. + */ virtual AmReal32 GetPlaySpeed() const = 0; + /** + * @brief Gets the location of the audio data in the layer. + * + * The location is expressed as a 3D vector in the global space. For sound instances linked + * to an `Entity`, the location of that entity is returned instead. + * + * @return The location of the audio data in the layer. + * + * @see [Entity](../../engine/Entity/index.md) + */ virtual AmVec3 GetLocation() const = 0; + /** + * @brief Gets the entity associated with the audio data in the layer. + * + * @return The entity associated with the audio data in the layer. If the layer is not associated with + * an `Entity`, an invalid entity is returned. + * + * @see [Entity](../../engine/Entity/index.md) + */ virtual Entity GetEntity() const = 0; + /** + * @brief Gets the listener currently rendering the audio data in the layer. + * + * @return The listener currently rendering the audio data in the layer. If the layer is not associated with + * a `Listener`, an invalid listener is returned. + * + * @see [Listener](../../engine/Listener/index.md) + */ virtual Listener GetListener() const = 0; + /** + * @brief Gets the room in which the audio data in the layer is currently located. + * + * @return The room in which the audio data in the layer is currently located. If the layer is not located + * in a `Room`, an invalid room is returned. + * + * @see [Room](../../engine/Room/index.md) + */ virtual Room GetRoom() const = 0; + /** + * @brief Gets the channel managing the audio data in the layer. + * + * Multiple layers can be linked to the same `Channel`. + * + * @return The channel managing the audio data in the layer. + * + * @see [Channel](../../engine/Channel/index.md) + */ virtual Channel GetChannel() const = 0; + /** + * @brief Gets the bus on which the audio data in the layer is playing. + * + * @return The bus on which the audio data in the layer is playing. + * + * @see [Bus](../../engine/Bus/index.md) + */ virtual Bus GetBus() const = 0; + /** + * @brief Gets the sound format of the audio data in the layer. + * + * The sound format specifies the number of channels, sample rate, and other audio properties. It is + * filled by the `Codec` that handled the decoding of the audio data. + * + * @return The sound format of the audio data in the layer. + * + * @see [SoundFormat](../../core/SoundFormat/index.md), [Codec](../../engine/Codec/index.md) + */ virtual SoundFormat GetSoundFormat() const = 0; + /** + * @brief Gets the spatialization mode of the audio data in the layer. + * + * The spatialization mode determines how the audio data in the layer is processed to produce a stereoscopic + * sound. This value must be set in the asset file of the sound object. + * + * @return The spatialization mode of the audio data in the layer. + * + * @see [eSpatialization](../../core/eSpatialization/index.md) + */ virtual eSpatialization GetSpatialization() const = 0; + /** + * @brief Checks if the audio data in the layer is looping. + * + * @return `true` if the audio data in the layer is looping, `false` otherwise. + */ virtual bool IsLoopEnabled() const = 0; + /** + * @brief Checks if the audio data in the layer is streaming from the file system. + * + * @return `true` if the audio data in the layer is streaming from the file system, `false` otherwise. + */ virtual bool IsStreamEnabled() const = 0; + /** + * @brief Gets the sound associated with the audio data in the layer. + * + * @return The sound associated with the audio data in the layer. + * + * @see [Sound](../../assets/Sound/index.md) + */ virtual const Sound* GetSound() const = 0; + /** + * @brief Gets the effect associated with the audio data in the layer. + * + * @return The effect associated with the audio data in the layer. + * + * @see [EffectInstance](../../engine/EffectInstance/index.md), [Effect](../../assets/Effect/index.md) + */ virtual const EffectInstance* GetEffect() const = 0; + /** + * @brief Gets the attenuation associated with the audio data in the layer. + * + * @return The attenuation associated with the audio data in the layer. + * + * @see [Attenuation](../../assets/Attenuation/index.md) + */ virtual const Attenuation* GetAttenuation() const = 0; + /** + * @brief Gets the current sample rate of the audio data in the layer. + * + * The current sample rate of the audio data in the layer can be different from the original sample rate + * stored in the sound format. Its value may change due to the Doppler effect, or due to an internal + * sample rate conversion to match the one specified in the loaded engine configuration. + * + * @return The current sample rate of the audio data in the layer. + */ virtual AmUInt32 GetSampleRate() const = 0; }; @@ -100,21 +313,28 @@ namespace SparkyStudios::Audio::Amplitude * @brief Amplitude Audio Mixer. * * This class handles processing of audio data by mixing multiple audio sources. - * The resulting audio stream are next handled by the @c Driver for playback or recording. + * The resulting audio stream are next handled by the `Driver` for playback or recording. + * + * @see [Driver](../../engine/Driver/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC Amplimix { public: + /** + * @brief Default Destructor. + */ virtual ~Amplimix() = default; /** * @brief Saves the information about the rendering audio device. * - * @param deviceID The ID of the audio device. - * @param deviceName The name of the audio device. - * @param deviceOutputSampleRate The sample rate of the audio device's output. - * @param deviceOutputChannels The number of audio channels of the audio device's output. - * @param deviceOutputFormat The format of the audio device's output. + * @param[in] deviceID The ID of the audio device. + * @param[in] deviceName The name of the audio device. + * @param[in] deviceOutputSampleRate The sample rate of the audio device's output. + * @param[in] deviceOutputChannels The number of audio channels of the audio device's output. + * @param[in] deviceOutputFormat The format of the audio device's output. */ virtual void UpdateDevice( AmObjectID deviceID, @@ -126,17 +346,17 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the mixer is initialized. * - * @return @c true if the mixer is initialized, @c false otherwise. + * @return `true` if the mixer is initialized, `false` otherwise. */ [[nodiscard]] virtual bool IsInitialized() const = 0; /** * @brief Processes the audio data by mixing multiple audio sources for the specified number of frames. * - * @param outBuffer The buffer to store the mixed audio data. - * @param frameCount The number of frames to mix. + * @param[out] outBuffer The buffer to store the mixed audio data. + * @param[in] frameCount The number of frames to mix. * - * @return The number of frames actually mixed. + * @return The number of processed frames. */ virtual AmUInt64 Mix(AudioBuffer** outBuffer, AmUInt64 frameCount) = 0; diff --git a/include/SparkyStudios/Audio/Amplitude/Mixer/Node.h b/include/SparkyStudios/Audio/Amplitude/Mixer/Node.h index f53c949d..2ee62b54 100644 --- a/include/SparkyStudios/Audio/Amplitude/Mixer/Node.h +++ b/include/SparkyStudios/Audio/Amplitude/Mixer/Node.h @@ -32,6 +32,8 @@ namespace SparkyStudios::Audio::Amplitude * This class represents the actual node executed within the * Amplimix pipeline. Each node instance has a unique ID assigned * to it, that matches the one provided in the pipeline asset. + * + * @ingroup mixer */ class AM_API_PUBLIC NodeInstance { @@ -41,31 +43,37 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Initializes the node instance. * - * @param id Unique identifier for the node instance. - * @param layer The Amplimix layer this node instance is currently associated with. - * @param pipeline The pipeline this node instance belongs to. + * @param[in] id Unique identifier for the node instance. + * @param[in] layer The Amplimix layer this node instance is currently associated with. + * @param[in] pipeline The pipeline this node instance belongs to. */ virtual void Initialize(AmObjectID id, const AmplimixLayer* layer, const PipelineInstance* pipeline); /** - * @brief NodeInstance destructor. + * @brief Default destructor. */ virtual ~NodeInstance() = default; /** - * @brief Returns the unique identifier for the node instance. + * @brief Gets the unique identifier for the node instance. + * + * @return The unique identifier for the node instance. */ [[nodiscard]] AmObjectID GetId() const; /** * @brief Gets the Amplimix layer this node instance is currently associated with. + * + * @return The Amplimix layer this node instance is currently associated with. + * + * @see [AmplimixLayer](../AmplimixLayer/index.md) */ [[nodiscard]] const AmplimixLayer* GetLayer() const; /** * @brief Resets the node instance's internal state. * - * This function should be called automatically by Amplimix, each time the pipeline is + * @warning This function should be called automatically by Amplimix, each time the pipeline is * about to be executed. Call it manually only if you know what you're doing. */ virtual void Reset() = 0; @@ -77,45 +85,53 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Interface for Amplimix pipeline nodes that can consume - * audio data from an input buffer. + * @brief Interface for Amplimix pipeline nodes that can consume audio data from an input buffer. + * + * @ingroup mixer */ class AM_API_PUBLIC ConsumerNodeInstance { public: /** - * @brief Consumes audio data from the provider node - * specified with the call of @c ConsumerNodeInstance::Connect(). + * @brief Consumes audio data from the provider node. + * + * The provider node should be specified with the call of @ref Connect `Connect()`. */ virtual void Consume() = 0; /** - * @brief Set the input provider node ID for this node. + * @brief Sets the input provider node ID for this node. * - * @param provider The provider node for this node. + * @param[in] provider The provider node for this node. */ virtual void Connect(AmObjectID provider) = 0; }; /** - * @brief Interface for Amplimix pipeline nodes that can provide - * audio data to an output buffer. + * @brief Interface for Amplimix pipeline nodes that can provide audio data to an output buffer. + * + * @ingroup mixer */ class AM_API_PUBLIC ProviderNodeInstance { public: /** - * @brief Produces audio data ready to be taken as input of - * a consumer node. + * @brief Produces audio data ready to be taken as input from a consumer node. * * @return The output audio data. + * + * @see [AudioBuffer](../../core/AudioBuffer/index.md) */ virtual const AudioBuffer* Provide() = 0; }; /** - * @brief Base class for Amplimix pipeline nodes that can process - * audio data in-place. + * @brief Base class for Amplimix pipeline nodes that can process audio data in-place. + * + * @see [NodeInstance](../NodeInstance/index.md), [ConsumerNodeInstance](../ConsumerNodeInstance/index.md), + * [ProviderNodeInstance](../ProviderNodeInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC ProcessorNodeInstance : public NodeInstance @@ -126,47 +142,47 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief PropertyNodeInstance constructor. * - * @param processOnEmptyBuffer If true, the node will execute the Process() method - * even if the input buffer is @c nullptr. + * @param[in] processOnEmptyBuffer If `true`, the node will execute the @ref Process `Process()` method + * even if the input buffer is `nullptr`. */ ProcessorNodeInstance(bool processOnEmptyBuffer = false); /** - * @brief ProcessorNodeInstance destructor. + * @brief Default destructor. */ ~ProcessorNodeInstance() override = default; /** - * @brief Process input audio data and returns the output audio data. + * @brief Processes input audio data and returns the output audio data. * - * @param input The input audio data to process. + * @param[in] input The input audio data to process. * * @return The output audio data. */ virtual const AudioBuffer* Process(const AudioBuffer* input) = 0; /** - * @copydoc ConsumerNodeInstance::Consume() + * @inherit */ void Consume() final; /** - * @copydoc ConsumerNodeInstance::Connect() + * @inherit */ void Connect(AmObjectID provider) final; /** - * @copydoc ProviderNodeInstance::Provide() + * @inherit */ const AudioBuffer* Provide() final; /** - * @copydoc NodeInstance::Reset() + * @inherit */ void Reset() override; protected: - AmObjectID m_provider; + AmObjectID m_provider; ///< The ID of the input provider node. private: const AudioBuffer* _processingBuffer; @@ -175,9 +191,12 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Base class for Amplimix pipeline nodes that can mix - * audio data from multiple input buffers, and outputs the result - * of the mix. + * @brief Base class for Amplimix pipeline nodes that can mix audio data from multiple input buffers. + * + * @see [NodeInstance](../NodeInstance/index.md), [ConsumerNodeInstance](../ConsumerNodeInstance/index.md), + * [ProviderNodeInstance](../ProviderNodeInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC MixerNodeInstance : public NodeInstance @@ -191,17 +210,17 @@ namespace SparkyStudios::Audio::Amplitude MixerNodeInstance(); /** - * @brief MixerNodeInstance destructor. + * @brief Default destructor. */ ~MixerNodeInstance() override = default; /** - * @copydoc ConsumerNodeInstance::Consume() + * @inherit */ void Consume() final; /** - * @copydoc ConsumerNodeInstance::Connect() + * @inherit * * @note This method appends the given provider to the list of input * provider nodes. If the provider node already exists in the list, it @@ -210,9 +229,9 @@ namespace SparkyStudios::Audio::Amplitude void Connect(AmObjectID provider) final; /** - * @brief Set the input provider nodes for this mixer node. + * @brief Sets the input provider nodes for this mixer node. * - * @param providers The provider nodes for this mixer node. + * @param[in] providers The provider nodes for this mixer node. * * @note This method clears the existing input provider nodes, * and replaces them with the provided ones. @@ -220,17 +239,17 @@ namespace SparkyStudios::Audio::Amplitude void Connect(const std::vector& providers); /** - * @copydoc ProviderNodeInstance::Provide() + * @inherit */ const AudioBuffer* Provide() final; /** - * @copydoc NodeInstance::Reset() + * @inherit */ void Reset() override; protected: - std::vector m_providers; + std::vector m_providers; ///< The IDs of the input provider nodes. private: std::vector _processingBuffers; @@ -239,10 +258,14 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Class used to marks the input of the pipeline. + * @brief Class used to mark the input of the pipeline. * - * This node is automatically added to the pipeline when created. And thus + * @warning This node is automatically added to the pipeline when created. And thus * should not be manually added to the pipeline asset. + * + * @see [ProviderNodeInstance](../ProviderNodeInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC InputNodeInstance final : public NodeInstance @@ -257,24 +280,24 @@ namespace SparkyStudios::Audio::Amplitude InputNodeInstance(); /** - * @brief InputNodeInstance destructor. + * @brief Default destructor. */ ~InputNodeInstance() override = default; /** - * @brief Set the input of the pipeline. + * @brief Sets the input of the pipeline. * - * @param buffer The buffer to set as the input. + * @param[in] buffer The buffer to set as the input. */ void SetInput(AudioBuffer* buffer); /** - * @copydoc ProviderNodeInstance::Provide() + * @inherit */ const AudioBuffer* Provide() override; /** - * @copydoc NodeInstance::Reset() + * @inherit */ void Reset() override; @@ -284,10 +307,14 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Class used to marks the output of the pipeline. + * @brief Class used to mark the output of the pipeline. * - * This node is automatically added to the pipeline when created. And thus + * @warning This node is automatically added to the pipeline when created. And thus * should not be manually added to the pipeline asset. + * + * @see [ConsumerNodeInstance](../ConsumerNodeInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC OutputNodeInstance final : public NodeInstance @@ -302,29 +329,29 @@ namespace SparkyStudios::Audio::Amplitude OutputNodeInstance(); /** - * @brief OutputNodeInstance destructor. + * @brief Default destructor. */ ~OutputNodeInstance() override = default; /** - * @brief Set the output of the pipeline. + * @brief Sets the output of the pipeline. * - * @param buffer The buffer to set as the output. + * @param[in] buffer The buffer to set as the output. */ void SetOutput(AudioBuffer* buffer); /** - * @copydoc ConsumerNodeInstance::Consume() + * @inherit */ void Consume() override; /** - * @copydoc ConsumerNodeInstance::Connect() + * @inherit */ void Connect(AmObjectID provider) override; /** - * @copydoc NodeInstance::Reset() + * @inherit */ void Reset() override; @@ -336,10 +363,13 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Base class for Amplimix pipeline nodes. * - * This class presents the basic structure to create Amplimix - * pipeline nodes. Each @c Node must be derived from this class - * and implement the @c Node::CreateInstance() and - * @c Node::DestroyInstance() methods. + * This class presents the basic structure to create Amplimix pipeline nodes. Each + * `Node` of your pipelines must be derived from this class and implement the @ref CreateInstance `CreateInstance()` + * and @ref DestroyInstance `DestroyInstance()` methods. + * + * @see [NodeInstance](../NodeInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC Node { @@ -347,7 +377,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Node constructor. * - * @param name Name of the node. Should be unique within the pipeline. + * @param[in] name Name of the node. Should be unique within the pipeline. */ Node(AmString name); @@ -359,9 +389,9 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Creates a new instance of the node. * - * @param id Unique identifier for the new instance. - * @param layer The Amplimix layer associated with the new instance. - * @param pipeline The pipeline associated with the new instance. + * @param[in] id Unique identifier for the new instance. + * @param[in] layer The Amplimix layer associated with the new instance. + * @param[in] pipeline The pipeline associated with the new instance. * * @return A new instance of the node. */ @@ -370,7 +400,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Destroys the specified instance of the node. * - * @param instance Pointer to the instance to be destroyed. + * @param[in] instance Pointer to the instance to be destroyed. */ virtual void DestroyInstance(NodeInstance* instance) const = 0; @@ -382,14 +412,14 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new node. * - * @param node The node to add in the registry. + * @param[in] node The node to add in the registry. */ static void Register(Node* node); /** * @brief Unregisters a node. * - * @param node The node to remove from the registry. + * @param[in] node The node to remove from the registry. */ static void Unregister(const Node* node); @@ -397,35 +427,35 @@ namespace SparkyStudios::Audio::Amplitude * @brief Creates a new instance of the the node with the given name * and returns its pointer. The returned pointer should be deleted using Node::Destruct(). * - * @param name The name of the node. + * @param[in] name The name of the node. * - * @return The node with the given name, or NULL if none. + * @return The node with the given name, or `nullptr` if none. */ static NodeInstance* Construct(const AmString& name); /** * @brief Destroys the given node instance. * - * @param name The name of the node. - * @param instance The node instance to destroy. + * @param[in] name The name of the node. + * @param[in] instance The node instance to destroy. */ static void Destruct(const AmString& name, NodeInstance* instance); /** * @brief Locks the nodes registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new nodes after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new nodes after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the nodes registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new nodes after the engine is fully unloaded. */ static void UnlockRegistry(); @@ -440,6 +470,8 @@ namespace SparkyStudios::Audio::Amplitude * @brief Look up a node by name. * * @return The node with the given name, or NULL if none. + * + * @internal */ static Node* Find(const AmString& name); }; diff --git a/include/SparkyStudios/Audio/Amplitude/Mixer/Pipeline.h b/include/SparkyStudios/Audio/Amplitude/Mixer/Pipeline.h index 78fadf08..8367a3be 100644 --- a/include/SparkyStudios/Audio/Amplitude/Mixer/Pipeline.h +++ b/include/SparkyStudios/Audio/Amplitude/Mixer/Pipeline.h @@ -25,26 +25,37 @@ namespace SparkyStudios::Audio::Amplitude { class Pipeline; + /** + * @brief Represents an instance of a pipeline for a specific layer. + * + * A pipeline instance is created for each single layer in the mixer. Each pipeline instance + * manages its own state, and create a set of node instances following the provided configuration. + * + * @ingroup mixer + */ class AM_API_PUBLIC PipelineInstance { friend class Pipeline; public: + /** + * @brief Default constructor. + */ virtual ~PipelineInstance() = default; /** * @brief Executes the pipeline for the given layer. * - * @param in The input buffer to process. This buffer is passed to the input + * @param[in] in The input buffer to process. This buffer is passed to the input * node of the pipeline. - * @param out The output buffer where the output node will fill processed data. + * @param[out] out The output buffer where the output node will fill processed data. */ virtual void Execute(const AudioBuffer& in, AudioBuffer& out) = 0; /** * @brief Resets the internal state for all nodes in the pipeline. * - * This method is called automatically when Amplimix has finished processing a frame + * @warning This method is called automatically when Amplimix has finished processing a frame * for a specific layer. You should not manually call this method, unless you know what * you're doing. */ @@ -53,9 +64,9 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Gets the node with the specified ID. * - * @param id The ID of the node to retrieve. + * @param[in] id The ID of the node to retrieve. * - * @return The node with the specified ID, or @c nullptr if not found. + * @return The node with the specified ID, or `nullptr` if not found. */ [[nodiscard]] virtual NodeInstance* GetNode(AmObjectID id) const = 0; }; @@ -63,17 +74,24 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief A pipeline assembles a set of nodes to process audio data. * - * For each layer in Amplimix, a pipeline is created for that specific layer. + * For each layer in `Amplimix`, a `PipelineInstance` is created for that specific layer. + * + * @see [Amplimix](../Amplimix/index.md), [PipelineInstance](../PipelineInstance/index.md) + * + * @ingroup mixer */ class AM_API_PUBLIC Pipeline : public Asset { public: + /** + * @brief Default destructor. + */ virtual ~Pipeline() = default; /** * @brief Creates a new pipeline instance for the specified layer. * - * @param layer The layer for which to create the pipeline instance. + * @param[in] layer The layer for which to create the pipeline instance. * * @return A new pipeline instance for the specified layer. */ @@ -82,7 +100,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Destroys the specified pipeline instance. * - * @param instance The pipeline instance to destroy. + * @param[in] instance The pipeline instance to destroy. */ virtual void DestroyInstance(PipelineInstance* instance) const = 0; }; diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Attenuation.h b/include/SparkyStudios/Audio/Amplitude/Sound/Attenuation.h index a6d2b91a..220dc931 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Attenuation.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Attenuation.h @@ -36,10 +36,15 @@ namespace SparkyStudios::Audio::Amplitude * * This allows to increase the attenuation according to the shape of * the sound propagation. + * + * @ingroup engine */ class AM_API_PUBLIC AttenuationZone { public: + /** + * @brief Default destructor. + */ virtual ~AttenuationZone() = default; /** @@ -47,9 +52,9 @@ namespace SparkyStudios::Audio::Amplitude * * This method is used only for position based sound sources. * - * @param attenuation The Attenuator object to use for distance attenuation. - * @param soundLocation The location of the sound source. - * @param listener The listener for which compute the attenuation. + * @param[in] attenuation The Attenuator object to use for distance attenuation. + * @param[in] soundLocation The location of the sound source. + * @param[in] listener The listener for which compute the attenuation. * * @return The attenuation factor. */ @@ -60,9 +65,9 @@ namespace SparkyStudios::Audio::Amplitude * * This method is used by position and orientation based sound sources. * - * @param attenuation The Attenuator object to use for distance attenuation. - * @param entity The entity which emits the sound. - * @param listener The listener for which compute the attenuation. + * @param[in] attenuation The Attenuator object to use for distance attenuation. + * @param[in] entity The entity which emits the sound. + * @param[in] listener The listener for which compute the attenuation. * * @return The attenuation factor. */ @@ -70,14 +75,16 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Amplitude Attenuation. + * @brief Amplitude Attenuation Asset. * - * An Attenuation materializes how the sound volume and other distance-based + * An `Attenuation` materializes how the sound volume and other distance-based * parameters are calculated following the distance of the sound source to the listener. * - * The Attenuation is a shared object between sound sources. They are used only - * when the sound need to adjust his volume due to the distance of from the listener, + * The `Attenuation` is a shared object between sound sources. They are used only + * when the sound need to adjust its volume due to the distance of from the listener, * and many other parameters. + * + * @ingroup assets */ class AM_API_PUBLIC Attenuation : public Asset { @@ -85,8 +92,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the gain of the sound from the given distance to the listener. * - * @param soundLocation The location of the sound source. - * @param listener The listener which is hearing the sound. + * @param[in] soundLocation The location of the sound source. + * @param[in] listener The listener which is hearing the sound. * * @return The computed gain value fom the curve. */ @@ -95,8 +102,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the gain of the sound from the given distance to the listener. * - * @param entity The entity which emits the sound. - * @param listener The listener which is hearing the sound. + * @param[in] entity The entity which emits the sound. + * @param[in] listener The listener which is hearing the sound. * * @return The computed gain value fom the curve. */ @@ -137,12 +144,11 @@ namespace SparkyStudios::Audio::Amplitude * at a given frequency band for a sound source located at a specific position * and a listener located at another specific position. * - * @param soundLocation The location of the sound source. - * @param listenerLocation The location of the listener which is hearing the sound. - * @param band The frequency band for which the air absorption effect is evaluated. + * @param[in] soundLocation The location of the sound source. + * @param[in] listenerLocation The location of the listener which is hearing the sound. + * @param[in] band The frequency band for which the air absorption effect is evaluated. * - * @return The air absorption attenuation factor for the given frequency band. - * The returned value is in decibels (dB). + * @return The air absorption attenuation factor in decibels (dB) for the given frequency band. */ [[nodiscard]] virtual AmReal32 EvaluateAirAbsorption( const AmVec3& soundLocation, const AmVec3& listenerLocation, AmUInt32 band) const = 0; diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Collection.h b/include/SparkyStudios/Audio/Amplitude/Sound/Collection.h index 66feb1fc..f746680a 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Collection.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Collection.h @@ -24,11 +24,15 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Amplitude Collection. + * @brief Amplitude Collection Asset. * - * A Collection is a container sound object that group multiple sounds over the same name. Only + * A `Collection` is a container sound object that group multiple sounds over the same name. Only * one sound can be playing at a time in the same collection, and the sound picked for playback - * is chosen by the collection's Scheduler. + * is chosen by the collection's `Scheduler`. + * + * @see [SoundObject](../../engine/SoundObject/index.md) + * + * @ingroup assets */ class AM_API_PUBLIC Collection : public SoundObject @@ -38,7 +42,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns a Sound from this collection from the World scope. * - * @param toSkip The list of Sound IDs to skip fom the selection. + * @param[in] toSkip The list of Sound IDs to skip fom the selection. * * @return The selected Sound. */ @@ -47,8 +51,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns a Sound from this collection from an Entity scope. * - * @param entity The entity from which pick the sound. - * @param toSkip The list of Sound IDs to skip fom the selection. + * @param[in] entity The entity from which pick the sound. + * @param[in] toSkip The list of Sound IDs to skip fom the selection. * * @return The selected Sound. */ @@ -57,7 +61,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Resets the internal state of the scheduler running for the given Entity. * - * @param entity The entity for which reset the scheduler state. + * @param[in] entity The entity for which reset the scheduler state. */ virtual void ResetEntityScopeScheduler(const Entity& entity) = 0; diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Effect.h b/include/SparkyStudios/Audio/Amplitude/Sound/Effect.h index 6f56071d..59ceef01 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Effect.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Effect.h @@ -27,13 +27,17 @@ namespace SparkyStudios::Audio::Amplitude class EffectInstance; /** - * @brief Amplitude Effect. + * @brief Amplitude Effect Asset. * * An effect is a sound filter applied to one or more sound objects * (sounds, collections, or switch containers) during playback. * * Effects are customized using parameters and each parameters can be - * updated at runtime using a @c RTPC. + * updated at runtime using a `Rtpc`. + * + * @see [Rtpc](../Rtpc/index.md), [EffectInstance](../../engine/EffectInstance/index.md) + * + * @ingroup assets */ class AM_API_PUBLIC Effect : public Asset { @@ -53,28 +57,31 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Destroys an instance of this effect. * - * @param instance The effect instance to delete. + * @param[in] instance The effect instance to delete. */ virtual void DestroyInstance(EffectInstance* instance) const = 0; }; /** - * @brief An instance of an Effect asset. + * @brief An instance of an `Effect` asset. + * + * The effect instance is the real place where the filter is applied to only one sound object + * at a time. Each effect instance has its own state, and that state is not shared across sound objects. + * + * @see [Effect](../../assets/Effect/index.md), [FilterInstance](../../dsp/FilterInstance/index.md) * - * The effect instance is the real filter applied to only one sound object - * at a time. It is used to not share the same state between multiple sound - * objects. + * @ingroup engine */ class EffectInstance { public: /** - * @brief Destroys the EffectInstance. + * @brief Default destructor. */ virtual ~EffectInstance() = default; /** - * @brief Get the filter instance wrapped by this effect. + * @brief Gets the filter instance wrapped by this effect. * * @return The filter instance. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Fader.h b/include/SparkyStudios/Audio/Amplitude/Sound/Fader.h index 1d48658b..4f216732 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Fader.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Fader.h @@ -24,8 +24,21 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief A Fader instance. An object of this class will be created each time - * a Fader is requested. + * @brief Enumerates the list of states in a fader. + * + * @ingroup engine + */ + enum eFaderState : AmInt8 + { + eFaderState_Stopped = -1, ///< The fader is stopped + eFaderState_Disabled = 0, ///< The fader is disabled + eFaderState_Active = 1, ///< The fader is active and fading + }; + + /** + * @brief A Fader instance. An object of this class will be created each time a `Fader` is requested. + * + * @ingroup engine */ class AM_API_PUBLIC FaderInstance { @@ -42,19 +55,19 @@ namespace SparkyStudios::Audio::Amplitude { public: /** - * @brief Construct a new Transition curve. + * @brief Constructs a new Transition curve. * - * @param x1 The x coordinate of the second control point. - * @param y1 The y coordinate of the second control point. - * @param x2 The x coordinate of the third control point. - * @param y2 The y coordinate of the third control point. + * @param[in] x1 The x coordinate of the second control point. + * @param[in] y1 The y coordinate of the second control point. + * @param[in] x2 The x coordinate of the third control point. + * @param[in] y2 The y coordinate of the third control point. */ Transition(AmReal32 x1, AmReal32 y1, AmReal32 x2, AmReal32 y2); /** - * @brief Construct a new Transition curve. + * @brief Constructs a new Transition curve. * - * @param controlPoints The control points of the curve. + * @param[in] controlPoints The control points of the curve. */ Transition(const BeizerCurveControlPoints& controlPoints); @@ -62,7 +75,7 @@ namespace SparkyStudios::Audio::Amplitude * @brief Given an animation duration percentage (in the range [0, 1]), * it calculates the animation progression percentage from the configured curve. * - * @param t The animation duration percentage (in the range [0, 1]). + * @param[in] t The animation duration percentage (in the range [0, 1]). * * @return The animation progress percentage (in the range [0, 1]). */ @@ -80,75 +93,78 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Construct a new FaderInstance object. + * @brief Constructs a new FaderInstance object. * * This will initialize the fader instance state to default values. */ FaderInstance(); + /** + * @brief Default destructor. + */ virtual ~FaderInstance() = default; /** * @brief Set up fader. * - * @param from The start value. - * @param to The target value. - * @param duration The duration of transition. + * @param[in] from The start value. + * @param[in] to The target value. + * @param[in] duration The duration of transition. */ void Set(AmReal64 from, AmReal64 to, AmTime duration); /** * @brief Set up fader. * - * @param from The start value. - * @param to The target value. + * @param[in] from The start value. + * @param[in] to The target value. */ void Set(AmReal64 from, AmReal64 to); /** - * @brief Set the duration of the transition. + * @brief Sets the duration of the transition. * - * @param duration The transition duration. + * @param[in] duration The transition duration. */ void SetDuration(AmTime duration); /** - * @brief Get the current fading value. + * @brief Gets the current fading value. * - * To use this method you firstly need to define the fading start time using - * Fader::Start(). + * To use this method you first need to define the fading start time using + * @ref Start `Start()`. * - * @param time The time at which the value should be calculated. + * @param[in] time The time at which the value should be calculated. * * @return The current value. */ virtual AmReal64 GetFromTime(AmTime time); /** - * @brief Get the current fading value. + * @brief Gets the current fading value. * - * @param percentage The percentage of time elapsed. This should be in the range [0, 1]. + * @param[in] percentage The percentage of time elapsed. This should be in the range [0, 1]. * * @return The current value. */ virtual AmReal64 GetFromPercentage(AmReal64 percentage); /** - * @brief Get the state of this Fader. + * @brief Gets the state of this Fader. * * @return The Fader state. */ - [[nodiscard]] AM_INLINE AM_FADER_STATE GetState() const + [[nodiscard]] AM_INLINE eFaderState GetState() const { return m_state; } /** - * @brief Set the state of this Fader. + * @brief Sets the state of this Fader. * - * @param state The state to set. + * @param[in] state The state to set. */ - AM_INLINE void SetState(AM_FADER_STATE state) + AM_INLINE void SetState(eFaderState state) { m_state = state; } @@ -156,7 +172,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Sets the fading start time. * - * @param time The fading start time. + * @param[in] time The fading start time. */ void Start(AmTime time = 0.0); @@ -174,7 +190,7 @@ namespace SparkyStudios::Audio::Amplitude // Time fading will end AmTime m_endTime; // Active flag; 0 means disabled, 1 is active, -1 means was active, but stopped - AM_FADER_STATE m_state; + eFaderState m_state; // The transition function Transition m_curve; }; @@ -184,6 +200,8 @@ namespace SparkyStudios::Audio::Amplitude * * A fader is used to move a value to a specific target value * during an amount of time and according to a fading algorithm. + * + * @ingroup engine */ class AM_API_PUBLIC Fader { @@ -202,18 +220,24 @@ namespace SparkyStudios::Audio::Amplitude */ Fader(); + /** + * @brief Default destructor. + */ virtual ~Fader(); /** * @brief Creates a new instance of the Fader. + * * @return A new instance of the Fader. */ virtual FaderInstance* CreateInstance() = 0; /** - * @brief Destroys an instance of the Fader. The instance should have - * been created with CreateInstance(). - * @param instance The Fader instance to be destroyed. + * @brief Destroys an instance of the Fader. + * + * @note The instance should have been created with CreateInstance(). + * + * @param[in] instance The Fader instance to be destroyed. */ virtual void DestroyInstance(FaderInstance* instance) = 0; @@ -234,50 +258,51 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Registers a new fader. * - * @param fader The Fader to add in the registry. + * @param[in] fader The Fader to add in the registry. */ static void Register(Fader* fader); /** * @brief Unregister a fader. * - * @param fader The Fader to remove from the registry. + * @param[in] fader The Fader to remove from the registry. */ static void Unregister(const Fader* fader); /** - * @brief Creates a new instance of the the Fader with the given name - * and returns its pointer. The returned pointer should be deleted using Fader::Destruct(). + * @brief Creates a new instance of the the fader with the given name and returns its pointer. * - * @param name The name of the Fader. + * @note The returned pointer should be deleted using @ref Destruct `Destruct()`. * - * @return The Fader with the given name, or NULL if none. + * @param[in] name The name of the fader. + * + * @return The fader with the given name, or `nullptr` if none. */ static FaderInstance* Construct(const AmString& name); /** - * @brief Destroys the given Fader instance. + * @brief Destroys the given fader instance. * - * @param name The name of the Fader. - * @param instance The Fader instance to destroy. + * @param[in] name The name of the fader. + * @param[in] instance The fader instance to destroy. */ static void Destruct(const AmString& name, FaderInstance* instance); /** * @brief Locks the faders registry. * - * This function is mainly used for internal purposes. Its - * called before the Engine initialization, to discard the - * registration of new Faders after the engine is fully loaded. + * @warning This function is mainly used for internal purposes. It's + * called before the `Engine` initialization, to discard the registration + * of new fader after the engine is fully loaded. */ static void LockRegistry(); /** * @brief Unlocks the faders registry. * - * This function is mainly used for internal purposes. Its - * called after the Engine deinitialization, to allow the - * registration of new divers after the engine is fully unloaded. + * @warning This function is mainly used for internal purposes. It's + * called after the `Engine` deinitialization, to allow the registration + * of new fader after the engine is fully unloaded. */ static void UnlockRegistry(); @@ -292,6 +317,8 @@ namespace SparkyStudios::Audio::Amplitude * @brief Look up a Fader by name. * * @return The Fader with the given name, or NULL if none. + * + * @internal */ static Fader* Find(const AmString& name); diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Rtpc.h b/include/SparkyStudios/Audio/Amplitude/Sound/Rtpc.h index e1686ab0..9adcd2e5 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Rtpc.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Rtpc.h @@ -30,12 +30,14 @@ namespace SparkyStudios::Audio::Amplitude struct RtpcCompatibleValue; /** - * @brief Amplitude Real-Time Parameter Control. + * @brief Amplitude Real-Time Parameter Control Asset. * * A RTPC is a value that is updated by the game. Any update to the RTPC is * listened by the engine to propagate the changes to other parameters linked to it. * * A Rtpc object is shared between any objects and values linked to it. + * + * @ingroup assets */ class AM_API_PUBLIC Rtpc : public Asset { @@ -45,40 +47,40 @@ namespace SparkyStudios::Audio::Amplitude * * This method is useful only for RTPCs that are using a curve to update their value. * - * @param deltaTime The time elapsed since the last update. + * @param[in] deltaTime The time elapsed since the last update. */ virtual void Update(AmTime deltaTime) = 0; /** - * @brief Get the minimum value of this RTPC. + * @brief Gets the minimum value of this RTPC. * * @return The RTPC minimum value. */ [[nodiscard]] virtual AmReal64 GetMinValue() const = 0; /** - * @brief Get the maximum value of this RTPC. + * @brief Gets the maximum value of this RTPC. * * @return The RTPC maximum value. */ [[nodiscard]] virtual AmReal64 GetMaxValue() const = 0; /** - * @brief Get the current value of this RTPC. + * @brief Gets the current value of this RTPC. * * @return The current RTPC value. */ [[nodiscard]] virtual AmReal64 GetValue() const = 0; /** - * @brief Set the current value of this RTPC. + * @brief Sets the current value of this RTPC. * - * @param value The value to set. + * @param[in] value The value to set. */ virtual void SetValue(AmReal64 value) = 0; /** - * @brief Get the default value of this RTPC. + * @brief Gets the default value of this RTPC. * * @return The default RTPC value. */ @@ -91,26 +93,42 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief A RTPC compatible value is used as a wrapper to hold propertiy values + * @brief A RTPC compatible value is used as a wrapper to hold property values * that can be linked to RTPCs. * * A property value that can be linked to a RTPC can be either a single static value * that never updates, or a curve and an RTPC value that is updated by the game. The * curve is used here as a function that takes the current RTPC value and returns the * parameter value. + * + * @ingroup engine */ struct AM_API_PUBLIC RtpcValue { public: + /** + * @brief Initializes the `RtpcValue` object. + * + * @param[in] value The `RtpcValue` object to initialize. + * @param[in] definition The RtpcCompatibleValue object to initialize from. + * @param[in] staticValue The static value to set. + * + * @internal + */ static void Init(RtpcValue& value, const RtpcCompatibleValue* definition, AmReal32 staticValue); /** - * @brief Creates an unitialized RtpcValue object. + * @brief Creates an uninitialized `RtpcValue` object. * - * An unitialized RtpcValue object cannot be used to update values. + * An uninitialized `RtpcValue` object cannot be used to update values. */ RtpcValue(); + /** + * @brief Creates a copy of the `RtpcValue` object. + * + * @param[in] other The `RtpcValue` object to copy. + */ RtpcValue(const RtpcValue& other); /** @@ -119,24 +137,24 @@ namespace SparkyStudios::Audio::Amplitude ~RtpcValue(); /** - * @brief Creates a RtpcValue object with a static value. + * @brief Creates a `RtpcValue` object with a static value. * - * @param value The static value to set. + * @param[in] value The static value to set. */ void Init(AmReal32 value); /** - * @brief Creates a RtpcValue object with a curve and an RTPC object. + * @brief Creates a `RtpcValue` object with a curve and an RTPC object. * - * @param rtpc The RTPC to link to. - * @param curve The curve to use. + * @param[in] rtpc The RTPC to link to. + * @param[in] curve The curve to use. */ void Init(const Rtpc* rtpc, Curve* curve); /** - * @brief Creates a RtpcValue object from an asset definition. + * @brief Creates a `RtpcValue` object from an asset definition. * - * @param definition The RTPC-compatible value asset definition. + * @param[in] definition The RTPC-compatible value asset definition. */ void Init(const RtpcCompatibleValue* definition); @@ -150,7 +168,8 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks if the RTPC value is static. - * @return @c true if the RTPC value is static, @c false otherwise. + * + * @return `true` if the RTPC value is static, `false` otherwise. */ [[nodiscard]] bool IsStatic() const; diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Sound.h b/include/SparkyStudios/Audio/Amplitude/Sound/Sound.h index 5d721f3f..43ca9ae9 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Sound.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Sound.h @@ -26,13 +26,17 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Amplitude Sound. + * @brief Amplitude Sound Asset. * - * A Sound is the most basic sound object in Amplitude. It can be used to directly play an audio file, - * or can be contained in a @a SwitchContainer or a @a Collection for a fine-grained control. + * A `Sound` is the most basic sound object in Amplitude. It can be used to directly play an audio file, + * or can be contained in a `SwitchContainer` or a `Collection` for a fine-grained control. * - * Effects can be attached to a Sound, which will be applied to all instances of the sound in the EffectProcessor - * of the Amplimix pipeline. + * Effects can be attached to a `Sound`, which will be applied to all instances of the sound in the Amplimix pipeline. + * + * @see [SwitchContainer](../SwitchContainer/index.md), [Collection](../Collection/index.md), + * [SoundObject](../../engine/SoundObject/index.md) + * + * @ingroup assets */ class AM_API_PUBLIC Sound : public SoundObject @@ -43,14 +47,14 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks streaming is enabled for this Sound. * - * @return true if streaming is enabled, false otherwise. + * @return `true` if streaming is enabled, `false` otherwise. */ [[nodiscard]] virtual bool IsStream() const = 0; /** * @brief Checks if looping is enabled for this Sound. * - * @return true if looping is enabled, false otherwise. + * @return `true` if looping is enabled, `false` otherwise. */ [[nodiscard]] virtual bool IsLoop() const = 0; diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/SoundBank.h b/include/SparkyStudios/Audio/Amplitude/Sound/SoundBank.h index 396d4652..e6d16cae 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/SoundBank.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/SoundBank.h @@ -28,44 +28,55 @@ namespace SparkyStudios::Audio::Amplitude class Engine; /** - * @brief Amplitude Sound Bank + * @brief Amplitude Sound Bank Asset. * - * A Sound Bank is a group of Amplitude assets, packed in a single binary. This way allows + * A Sound Bank is a group of Amplitude assets, registered in a single binary. This way allows * you to pack the needed data for your game as you want (ie. sound banks per levels). A sound bank - * need to be loaded by the Engine using @code Engine::LoadSoundBank() @endcode before to play sounds and + * need to be loaded by the Engine using `#!cpp Engine::LoadSoundBank()` before to play sounds and * trigger events inside it. When the sound bank data should be released (ie. changing the level, closing - * the game, etc.), you need to unload the sound bank using @code Engine::UnloadSoundBank() @endcode. + * the game, etc.), you need to unload the sound bank using `#!cpp Engine::UnloadSoundBank()`. + * + * @ingroup assets */ class AM_API_PUBLIC SoundBank { public: + /** + * @brief Creates an uninitialized `SoundBank`. + */ SoundBank(); - explicit SoundBank(const std::string& source); + + /** + * @brief Creates a sound bank from the given source file. + * + * @warning This constructor is for internal usage only. + */ + explicit SoundBank(const AmString& source); /** * @brief Initializes the sound bank by loading all the packed data. * - * @param filename The path to the sound bank file. - * @param engine The engine instance in which load the sound bank. + * @param[in] filename The path to the sound bank file. + * @param[in] engine The engine instance in which load the sound bank. * - * @return true when the operation succeeds, false otherwise. + * @return `true` when the operation succeeds, `false` otherwise. */ bool Initialize(const AmOsString& filename, Engine* engine); /** * @brief Initializes the sound bank by loading all the packed data. * - * @param fileData The sound bank file content. - * @param engine The engine instance in which load the sound bank. + * @param[in] fileData The sound bank file content. + * @param[in] engine The engine instance in which load the sound bank. * - * @return true when the operation succeeds, false otherwise. + * @return `true` when the operation succeeds, `false` otherwise. */ bool InitializeFromMemory(const char* fileData, Engine* engine); /** * @brief Unloads the sound bank from the Engine. * - * @param engine The engine instance from which unload the sound bank. + * @param[in] engine The engine instance from which unload the sound bank. */ void Deinitialize(Engine* engine); @@ -91,7 +102,7 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] const SoundBankDefinition* GetSoundBankDefinition() const; /** - * @brief Get the references counter of this instance. + * @brief Gets the references counter of this instance. * * @return The references counter. */ @@ -100,8 +111,10 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Load the sound files referenced in the sound bank. * - * This method should usually not be called directly. It is called automatically by the Engine with - * the @code Engine::StartLoadSoundFiles() @endcode method. + * @param[in] engine The engine instance from which load the sound files. + * + * @warning This method should not be called directly. It is called automatically by the `Engine` with + * the `#!cpp Engine::StartLoadSoundFiles()` method. */ void LoadSoundFiles(const Engine* engine); diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/SoundObject.h b/include/SparkyStudios/Audio/Amplitude/Sound/SoundObject.h index 2ad7ba44..e1bc1c08 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/SoundObject.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/SoundObject.h @@ -26,11 +26,16 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief The SoundObject class is the base class for all sound objects. + * @brief Base class for Amplitude sound objects. + * + * @ingroup engine */ class AM_API_PUBLIC SoundObject { public: + /** + * @brief Default destructor. + */ virtual ~SoundObject() = default; /** @@ -55,21 +60,21 @@ namespace SparkyStudios::Audio::Amplitude [[nodiscard]] virtual const RtpcValue& GetPriority() const = 0; /** - * @brief Get the Effect object associated with this sound object. + * @brief Gets the Effect object associated with this sound object. * * @return The Effect object. */ [[nodiscard]] virtual const Effect* GetEffect() const = 0; /** - * @brief Get the Attenuation object associated with this sound object. + * @brief Gets the Attenuation object associated with this sound object. * * @return The Attenuation object. */ [[nodiscard]] virtual const Attenuation* GetAttenuation() const = 0; /** - * @brief Return the bus this sound object will play on. + * @brief Returns the bus this sound object will play on. * * @return The bus this sound object will play on. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/Switch.h b/include/SparkyStudios/Audio/Amplitude/Sound/Switch.h index 7a7e599d..b3a20b9a 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/Switch.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/Switch.h @@ -24,6 +24,13 @@ namespace SparkyStudios::Audio::Amplitude { /** * @brief A switch state. + * + * A switch state is a single state that can be applied to a `SwitchContainer` to control which sounds are played. + * Only one state can be active at a time in the same `Switch` asset. + * + * @see [Switch](../../assets/Switch/index.md), [SwitchContainer](../../assets/SwitchContainer/index.md) + * + * @ingroup engine */ struct AM_API_PUBLIC SwitchState { @@ -42,60 +49,85 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Checks whether this switch state is valid. * - * @return @c true if the switch state is valid, @c false otherwise. + * @return `true` if the switch state is valid, `false` otherwise. */ [[nodiscard]] bool Valid() const; + /** + * @brief Compares this switch state with another one for equality. + * + * @param[im] other The other switch state to compare with. + * + * @return `true` if the switch states are equal, `false` otherwise. + */ bool operator==(const SwitchState& other) const; + + /** + * @brief Compares this switch state with another one for inequality. + * + * @param[in] other The other switch state to compare with. + * + * @return `true` if the switch states are not equal, `false` otherwise. + */ bool operator!=(const SwitchState& other) const; }; /** - * @brief Amplitude Switch. + * @brief Amplitude Switch Asset. + * + * A switch is a collection of states which can change the sounds played from a `SwitchContainer`. * - * A switch is a collection of states which can change the sound played from a SwitchContainer. + * For example, you can have a switch named `SurfaceType` which have `wood`, `grass`, `metal` and `water` as states. A + * `SwitchContainer` using this switch can group sounds per switch states, so when a state is active, all the sounds of + * that state are played. Changing the state of a `Switch` will updated ALL the `SwitchContainer` objects that use this `Switch`. * - * For example, you can have a switch named "SurfaceType" which have "wood", "grass", "metal" and "water" as states. A - * SwitchContainer using this switch can group sounds per switch states, so when a state is active, all the sounds of - * that state are played. + * The `Switch` is a shared object between sound sources. They are used only by `SwitchContainer` objects. * - * The Switch is a shared object between sound sources. They are used only by SwitchContainer objects. + * @see [SwitchState](../../engine/SwitchState/index.md), [SwitchContainer](../../assets/SwitchContainer/index.md) + * + * @ingroup assets */ class AM_API_PUBLIC Switch : public Asset { public: /** - * @brief Get the current state of the switch. + * @brief Gets the current state of the switch. * * @return The current state of the switch. */ [[nodiscard]] virtual const SwitchState& GetState() const = 0; /** - * @brief Set the current state of the switch. + * @brief Sets the current state of the switch. + * + * @note Changing the state of a `Switch` will updated ALL the `SwitchContainer` objects that use this `Switch`. * - * @param state The state to apply to the switch. + * @param[in] state The state to apply to the switch. */ virtual void SetState(const SwitchState& state) = 0; /** - * @brief Set the current state of the switch using the state ID. + * @brief Sets the current state of the switch using the state ID. * - * @param id The ID of the state to apply. This ID should exist in the list - * of switch states. + * @note Changing the state of a `Switch` will updated ALL the `SwitchContainer` objects that use this `Switch`. + * + * @param[in] id The ID of the state to apply. This ID should exist in the list + * of registered switch states. */ virtual void SetState(AmObjectID id) = 0; /** - * @brief Set the current state of the switch using the state name. + * @brief Sets the current state of the switch using the state name. + * + * @note Changing the state of a `Switch` will updated ALL the `SwitchContainer` objects that use this `Switch`. * - * @param name The name of the state to apply. This name should exist in the - * list of switch states. + * @param[in] name The name of the state to apply. This name should exist in the + * list of registered switch states. */ virtual void SetState(const AmString& name) = 0; /** - * @brief Get the list of available SwitchStates in this Switch. + * @brief Gets the list of available SwitchStates in this Switch. * * @return The list of available SwitchStates. */ diff --git a/include/SparkyStudios/Audio/Amplitude/Sound/SwitchContainer.h b/include/SparkyStudios/Audio/Amplitude/Sound/SwitchContainer.h index fa6daecd..1be55009 100644 --- a/include/SparkyStudios/Audio/Amplitude/Sound/SwitchContainer.h +++ b/include/SparkyStudios/Audio/Amplitude/Sound/SwitchContainer.h @@ -24,22 +24,26 @@ namespace SparkyStudios::Audio::Amplitude { /** - * @brief Describes a single item within a SwitchContainer. + * @brief Describes a single item within a `SwitchContainer`. + * + * @see [SwitchContainer](../../assets/SwitchContainer/index.md) + * + * @ingroup engine */ struct SwitchContainerItem { /** * @brief The object ID of the item. * - * May be a @a AmSoundID or a @a AmCollectionID. + * May be a `AmSoundID` or a `AmCollectionID`. */ AmObjectID m_id; /** - * @brief Whether to continue playing this item when the SwitchContainer + * @brief Whether to continue playing this item when the `SwitchContainer` * changes its state between one of the values where this item is registered. * - * If this value is set to @c false, each the sound will be stopped and played again + * If this value is set to `false`, each sound will be stopped and played again * from the beginning. */ bool m_continueBetweenStates; @@ -82,11 +86,15 @@ namespace SparkyStudios::Audio::Amplitude }; /** - * @brief Amplitude Switch Container. + * @brief Amplitude Switch Container Asset. * * A switch container is a container sound object where sounds and collections can be registered on * one or multiple switches. Only one switch can be active at a time in a switch container. When a * switch is active, all the sounds and collections that are registered on it will be played. + * + * @see [SoundObject](../../engine/SoundObject/index.md) + * + * @ingroup assets */ class AM_API_PUBLIC SwitchContainer : public SoundObject @@ -103,7 +111,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the fade in Fader for the given sound object ID. * - * @param id The ID of the sound object. + * @param[in] id The ID of the sound object. * * @return The fade in Fader. */ @@ -112,7 +120,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Get the fade out Fader for the given sound object ID. * - * @param id The ID of the sound object. + * @param[in] id The ID of the sound object. * * @return The fade out Fader. */ @@ -121,7 +129,7 @@ namespace SparkyStudios::Audio::Amplitude /** * @brief Returns the list of sound objects referenced in this SwitchContainer for the given state. * - * @param stateId The switch state to get the objects for. + * @param[in] stateId The switch state to get the objects for. * * @return The list of sound object IDs registered to the given state. */ diff --git a/schemas/common.fbs b/schemas/common.fbs index d7d6f63e..1e9922d2 100644 --- a/schemas/common.fbs +++ b/schemas/common.fbs @@ -19,15 +19,15 @@ enum PanningMode: byte { /// 2D stereo (left-right) panning. Does not support HRTF rendering. Stereo = 0, - /// HRTF-based panning using first-order Ambisonics, over a virtual array of + /// HRTF based panning using first-order Ambisonics, over a virtual array of /// 8 loudspeakers arranged in a cube configuration around the listener's head. BinauralLowQuality = 1, - /// HRTF-based panning using second-order Ambisonics, over a virtual array of + /// HRTF based panning using second-order Ambisonics, over a virtual array of /// 12 loudspeakers arranged in a dodecahedral configuration (using faces of the dodecahedron). BinauralMediumQuality = 2, - /// HRTF-based panning using third-order Ambisonics, over a virtual array of + /// HRTF based panning using third-order Ambisonics, over a virtual array of /// 26 loudspeakers arranged in a Lebedev grid. /// See: https://people.sc.fsu.edu/~jburkardt/m_src/sphere_lebedev_rule/sphere_lebedev_rule.html BinauralHighQuality = 3 diff --git a/src/Ambisonics/AmbisonicBinauralizer.h b/src/Ambisonics/AmbisonicBinauralizer.h index 60d50421..643affa7 100644 --- a/src/Ambisonics/AmbisonicBinauralizer.h +++ b/src/Ambisonics/AmbisonicBinauralizer.h @@ -17,7 +17,7 @@ #ifndef _AM_IMPLEMENTATION_AMBISONICS_AMBISONIC_BINAURALIZER_H #define _AM_IMPLEMENTATION_AMBISONICS_AMBISONIC_BINAURALIZER_H -#include +#include #include #include diff --git a/src/Core/Codecs/AMS/Codec.cpp b/src/Core/Codecs/AMS/Codec.cpp index d9823bf3..25d0a687 100644 --- a/src/Core/Codecs/AMS/Codec.cpp +++ b/src/Core/Codecs/AMS/Codec.cpp @@ -281,7 +281,7 @@ namespace SparkyStudios::Audio::Amplitude } } - format.SetAll(sample_rate, num_channels, bits_per_sample, num_samples, num_channels * sizeof(AmInt16), AM_SAMPLE_FORMAT_INT); + format.SetAll(sample_rate, num_channels, bits_per_sample, num_samples, num_channels * sizeof(AmInt16), eAudioSampleFormat_Int16); blockSize = wave_header.head.blockAlign; @@ -616,7 +616,7 @@ namespace SparkyStudios::Audio::Amplitude const AmUInt32 steps = offset / samplesPerBlock; offset = steps * _blockSize; - _file->Seek(sizeof(ADPCMHeader) + offset, eFSO_START); + _file->Seek(sizeof(ADPCMHeader) + offset, eFileSeekOrigin_Start); return true; } @@ -650,7 +650,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt64 AMSCodec::AMSEncoder::Write(AudioBuffer* in, AmUInt64 offset, AmUInt64 length) { - _file->Seek(sizeof(ADPCMHeader) + offset, eFSO_START); + _file->Seek(sizeof(ADPCMHeader) + offset, eFileSeekOrigin_Start); return Encode(_file, m_format, in, length, _samplesPerBlock, _lookAhead, _noiseShaping); } diff --git a/src/Core/Codecs/MP3/Codec.cpp b/src/Core/Codecs/MP3/Codec.cpp index 3f31ce66..6b29d58a 100644 --- a/src/Core/Codecs/MP3/Codec.cpp +++ b/src/Core/Codecs/MP3/Codec.cpp @@ -46,9 +46,9 @@ namespace SparkyStudios::Audio::Amplitude auto* file = static_cast(pUserData); file->Seek( offset, - origin == drmp3_seek_origin_start ? eFSO_START - : origin == drmp3_seek_origin_current ? eFSO_CURRENT - : eFSO_START); + origin == drmp3_seek_origin_start ? eFileSeekOrigin_Start + : origin == drmp3_seek_origin_current ? eFileSeekOrigin_Current + : eFileSeekOrigin_Start); return DRMP3_TRUE; } @@ -87,7 +87,7 @@ namespace SparkyStudios::Audio::Amplitude m_format.SetAll( _mp3.sampleRate, _mp3.channels, 0, framesCount, _mp3.channels * sizeof(AmAudioSample), - AM_SAMPLE_FORMAT_FLOAT // This codec always read frames as float32 values + eAudioSampleFormat_Float32 // This codec always read frames as float32 values ); _initialized = true; diff --git a/src/Core/Codecs/WAV/Codec.cpp b/src/Core/Codecs/WAV/Codec.cpp index 8854c0db..38330776 100644 --- a/src/Core/Codecs/WAV/Codec.cpp +++ b/src/Core/Codecs/WAV/Codec.cpp @@ -46,9 +46,9 @@ namespace SparkyStudios::Audio::Amplitude auto* file = static_cast(pUserData); file->Seek( offset, - origin == drwav_seek_origin_start ? eFSO_START - : origin == drwav_seek_origin_current ? eFSO_CURRENT - : eFSO_START); + origin == drwav_seek_origin_start ? eFileSeekOrigin_Start + : origin == drwav_seek_origin_current ? eFileSeekOrigin_Current + : eFileSeekOrigin_Start); return DRWAV_TRUE; } @@ -86,7 +86,7 @@ namespace SparkyStudios::Audio::Amplitude m_format.SetAll( _wav.sampleRate, _wav.channels, _wav.bitsPerSample, _wav.totalPCMFrameCount, _wav.channels * sizeof(AmAudioSample), - AM_SAMPLE_FORMAT_FLOAT // This codec always read frames as float32 values + eAudioSampleFormat_Float32 // This codec always read frames as float32 values ); _initialized = true; diff --git a/src/Core/Common.cpp b/src/Core/Common.cpp index 723b3325..17cd5ab5 100644 --- a/src/Core/Common.cpp +++ b/src/Core/Common.cpp @@ -32,7 +32,7 @@ namespace SparkyStudios::Audio::Amplitude ampoolfree(MemoryPoolKind::Default, m_basePtr); if (size == 0) - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; m_basePtr = nullptr; m_data = nullptr; @@ -46,14 +46,14 @@ namespace SparkyStudios::Audio::Amplitude #endif if (m_basePtr == nullptr) - return AM_ERROR_OUT_OF_MEMORY; + return eErrorCode_OutOfMemory; m_data = reinterpret_cast(m_basePtr); if (clear) Clear(); - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } void AmAlignedReal32Buffer::Clear() const @@ -120,19 +120,13 @@ namespace SparkyStudios::Audio::Amplitude Release(); } - AmTinyAlignedReal32Buffer::AmTinyAlignedReal32Buffer() - { - AmUInt8Buffer basePtr = &m_actualData[0]; - m_data = reinterpret_cast(reinterpret_cast(basePtr) + (AM_SIMD_ALIGNMENT - 1) & ~(AM_SIMD_ALIGNMENT - 1)); - } - void SoundFormat::SetAll( AmUInt32 sampleRate, AmUInt16 numChannels, AmUInt32 bitsPerSample, AmUInt64 framesCount, AmUInt32 frameSize, - AM_SAMPLE_FORMAT sampleType) + eAudioSampleFormat sampleType) { _sampleRate = sampleRate; _numChannels = numChannels; diff --git a/src/Core/Engine.cpp b/src/Core/Engine.cpp index 0996efe9..7c9d7498 100644 --- a/src/Core/Engine.cpp +++ b/src/Core/Engine.cpp @@ -145,7 +145,7 @@ namespace SparkyStudios::Audio::Amplitude dest->assign(bytes + 1, 0); // Read the file into the buffer - file->Seek(0, eFSO_START); + file->Seek(0, eFileSeekOrigin_Start); const AmUInt32 len = file->Read(reinterpret_cast(&(*dest)[0]), bytes); return len == bytes && len > 0; @@ -156,9 +156,9 @@ namespace SparkyStudios::Audio::Amplitude return config->mixer()->virtual_channels() + config->mixer()->active_channels(); } - // Returns this channel to the free appropriate free list based on whether it's + // Returns this channel to the appropriate free list based on whether it's // backed by a real channel or not. - static void InsertIntoFreeList(EngineInternalState* state, ChannelInternalState* channel) + void InsertIntoFreeList(EngineInternalState* state, ChannelInternalState* channel) { channel->Remove(); channel->Reset(); @@ -299,7 +299,7 @@ namespace SparkyStudios::Audio::Amplitude { const auto GetPluginName = plugin->get_function("PluginName"); const auto GetPluginVersion = plugin->get_function("PluginVersion"); - amLogInfo("LoadPlugin '%s' version: %s", GetPluginName(), GetPluginVersion()); + amLogInfo("Loaded Plugin '%s' Version: %s", GetPluginName(), GetPluginVersion()); } void* handle = plugin->native_handle(); @@ -655,7 +655,7 @@ namespace SparkyStudios::Audio::Amplitude // Create the internal engine state _state = ampoolnew(MemoryPoolKind::Engine, EngineInternalState); - _state->version = &Amplitude::Version(); + _state->version = &Amplitude::GetVersion(); // Load the audio driver if (config->driver()) diff --git a/src/Core/Log.cpp b/src/Core/Log.cpp index e9ccea3d..bb1acc45 100644 --- a/src/Core/Log.cpp +++ b/src/Core/Log.cpp @@ -33,51 +33,51 @@ namespace SparkyStudios::Audio::Amplitude void Logger::Debug(const char* file, int line, const AmString& message) { #ifdef AM_DEBUG - Log(eLML_DEBUG, file, line, message); + Log(eLogMessageLevel_Debug, file, line, message); #endif } void Logger::Info(const char* file, int line, const AmString& message) { - Log(eLML_INFO, file, line, message); + Log(eLogMessageLevel_Info, file, line, message); } void Logger::Warning(const char* file, int line, const AmString& message) { - Log(eLML_WARNING, file, line, message); + Log(eLogMessageLevel_Warning, file, line, message); } void Logger::Error(const char* file, int line, const AmString& message) { - Log(eLML_ERROR, file, line, message); + Log(eLogMessageLevel_Error, file, line, message); } void Logger::Critical(const char* file, int line, const AmString& message) { - Log(eLML_CRITICAL, file, line, message); + Log(eLogMessageLevel_Critical, file, line, message); } ConsoleLogger::ConsoleLogger(bool displayFileAndLine) : m_displayFileAndLine(displayFileAndLine) {} - void ConsoleLogger::Log(LogMessageLevel level, const char* file, int line, const AmString& message) + void ConsoleLogger::Log(eLogMessageLevel level, const char* file, int line, const AmString& message) { switch (level) { - case eLML_DEBUG: + case eLogMessageLevel_Debug: std::cout << "[DEBUG] "; break; - case eLML_INFO: + case eLogMessageLevel_Info: std::cout << "[INFO] "; break; - case eLML_WARNING: + case eLogMessageLevel_Warning: std::cout << "[WARNING] "; break; - case eLML_ERROR: + case eLogMessageLevel_Error: std::cout << "[ERROR] "; break; - case eLML_CRITICAL: + case eLogMessageLevel_Critical: std::cout << "[CRITICAL] "; break; } diff --git a/src/Core/Playback/Bus.cpp b/src/Core/Playback/Bus.cpp index bbdf1701..026633ac 100644 --- a/src/Core/Playback/Bus.cpp +++ b/src/Core/Playback/Bus.cpp @@ -18,6 +18,14 @@ namespace SparkyStudios::Audio::Amplitude { + Bus::Bus() + : _state(nullptr) + {} + + Bus::Bus(BusInternalState* state) + : _state(state) + {} + void Bus::Clear() { _state = nullptr; diff --git a/src/Core/Playback/BusInternalState.cpp b/src/Core/Playback/BusInternalState.cpp index 9ac50e3e..cd986ab1 100644 --- a/src/Core/Playback/BusInternalState.cpp +++ b/src/Core/Playback/BusInternalState.cpp @@ -16,8 +16,8 @@ #include #include -#include #include +#include #include "buses_definition_generated.h" @@ -52,7 +52,8 @@ namespace SparkyStudios::Audio::Amplitude _bus = amEngine->FindBus(definition->id()); if (!_bus.Valid()) { - amLogError("Cannot initialize duck-bus internal state: unable to find a duck-bus with ID " AM_ID_CHAR_FMT ".", definition->id()); + amLogError( + "Cannot initialize duck-bus internal state: unable to find a duck-bus with ID " AM_ID_CHAR_FMT ".", definition->id()); return false; } @@ -185,7 +186,7 @@ namespace SparkyStudios::Audio::Amplitude void BusInternalState::AdvanceFrame(AmTime delta_time, AmReal32 parent_gain) // NOLINT(misc-no-recursion) { - if (_gainFader->GetState() == AM_FADER_STATE_ACTIVE) + if (_gainFader->GetState() == eFaderState_Active) { // Update fading. _userGain = _gainFader->GetFromTime(Engine::GetInstance()->GetTotalTime()); @@ -193,7 +194,7 @@ namespace SparkyStudios::Audio::Amplitude if (_userGain == _targetUserGain) { // Fading is ended, disable fader. - _gainFader->SetState(AM_FADER_STATE_STOPPED); + _gainFader->SetState(eFaderState_Stopped); } } diff --git a/src/Core/Playback/BusInternalState.h b/src/Core/Playback/BusInternalState.h index 72bc5c9a..38393e2d 100644 --- a/src/Core/Playback/BusInternalState.h +++ b/src/Core/Playback/BusInternalState.h @@ -124,7 +124,7 @@ namespace SparkyStudios::Audio::Amplitude { _userGain = user_gain; _targetUserGain = user_gain; - _gainFader->SetState(AM_FADER_STATE_STOPPED); + _gainFader->SetState(eFaderState_Stopped); } // Return the user gain. diff --git a/src/Core/Playback/Channel.cpp b/src/Core/Playback/Channel.cpp index 30de0944..0aa047a4 100644 --- a/src/Core/Playback/Channel.cpp +++ b/src/Core/Playback/Channel.cpp @@ -33,8 +33,6 @@ namespace SparkyStudios::Audio::Amplitude : Channel(state, ++globalStateId) {} - Channel::Channel(const Channel& other) = default; - void Channel::Clear() { _state = nullptr; diff --git a/src/Core/Playback/ChannelInternalState.cpp b/src/Core/Playback/ChannelInternalState.cpp index 1b32b26d..8014685c 100644 --- a/src/Core/Playback/ChannelInternalState.cpp +++ b/src/Core/Playback/ChannelInternalState.cpp @@ -490,7 +490,7 @@ namespace SparkyStudios::Audio::Amplitude continue; FaderInstance* out = _switchContainer->GetFaderOut(item.m_id); - if (out->GetState() == AM_FADER_STATE_STOPPED) + if (out->GetState() == eFaderState_Stopped) continue; const AmReal32 gain = out->GetFromTime(Engine::GetInstance()->GetTotalTime()); @@ -501,7 +501,7 @@ namespace SparkyStudios::Audio::Amplitude if (gain == 0.0f) { - out->SetState(AM_FADER_STATE_STOPPED); + out->SetState(eFaderState_Stopped); // Fading in transition complete. Now we can halt the channel layer _realChannel.Halt(layer); } @@ -523,7 +523,7 @@ namespace SparkyStudios::Audio::Amplitude continue; FaderInstance* in = _switchContainer->GetFaderIn(item.m_id); - if (in->GetState() == AM_FADER_STATE_STOPPED) + if (in->GetState() == eFaderState_Stopped) continue; const AmReal32 gain = in->GetFromTime(Engine::GetInstance()->GetTotalTime()); @@ -533,7 +533,7 @@ namespace SparkyStudios::Audio::Amplitude _realChannel.SetGain(gain, layer); if (_gain - gain <= kEpsilon) - in->SetState(AM_FADER_STATE_STOPPED); + in->SetState(eFaderState_Stopped); } if (!isAtLeastOneFadeInRunning && !isAtLeastOneFadeOutRunning) @@ -547,7 +547,7 @@ namespace SparkyStudios::Audio::Amplitude // Update the fading in animation if necessary if (_channelState == ChannelPlaybackState::FadingIn) { - if (_fader != nullptr && _fader->GetState() == AM_FADER_STATE_ACTIVE) + if (_fader != nullptr && _fader->GetState() == eFaderState_Active) { const AmReal32 gain = _fader->GetFromTime(Engine::GetInstance()->GetTotalTime()); @@ -556,7 +556,7 @@ namespace SparkyStudios::Audio::Amplitude if (_gain - gain <= kEpsilon) { - _fader->SetState(AM_FADER_STATE_STOPPED); + _fader->SetState(eFaderState_Stopped); // Fading in transition complete. Now we mark the channel as playing. _channelState = ChannelPlaybackState::Playing; @@ -576,7 +576,7 @@ namespace SparkyStudios::Audio::Amplitude // Update the fading out animation if necessary if (_channelState == ChannelPlaybackState::FadingOut) { - if (_fader != nullptr && _fader->GetState() == AM_FADER_STATE_ACTIVE) + if (_fader != nullptr && _fader->GetState() == eFaderState_Active) { _gain = _fader->GetFromTime(Engine::GetInstance()->GetTotalTime()); @@ -585,7 +585,7 @@ namespace SparkyStudios::Audio::Amplitude if (_gain == 0.0f) { - _fader->SetState(AM_FADER_STATE_STOPPED); + _fader->SetState(eFaderState_Stopped); // Fading out transition complete. Now we can halt or pause the channel. if (_targetFadeOutState == ChannelPlaybackState::Stopped) diff --git a/src/Core/Version.cpp b/src/Core/Version.cpp index b020bf77..bbbbc57e 100644 --- a/src/Core/Version.cpp +++ b/src/Core/Version.cpp @@ -35,7 +35,7 @@ namespace SparkyStudios::Audio::Amplitude }; // clang-format on - const struct Version& Version() + const struct Version& GetVersion() { return kVersion; } diff --git a/src/Convolution/Convolver.cpp b/src/DSP/Convolver.cpp similarity index 98% rename from src/Convolution/Convolver.cpp rename to src/DSP/Convolver.cpp index f6d2d5b3..8fe1fd1b 100644 --- a/src/Convolution/Convolver.cpp +++ b/src/DSP/Convolver.cpp @@ -15,7 +15,7 @@ // Based on the code from https://github.com/HiFi-LoFi/FFTConvolver // Copyright (c) 2017 HiFi-LoFi, MIT License -#include +#include #include diff --git a/src/Math/FFT.cpp b/src/DSP/FFT.cpp similarity index 97% rename from src/Math/FFT.cpp rename to src/DSP/FFT.cpp index c7b72c8f..383e1842 100644 --- a/src/Math/FFT.cpp +++ b/src/DSP/FFT.cpp @@ -13,7 +13,7 @@ // limitations under the License. #include -#include +#include #include diff --git a/src/DSP/Filter.cpp b/src/DSP/Filter.cpp index 8f6362bf..830723bb 100644 --- a/src/DSP/Filter.cpp +++ b/src/DSP/Filter.cpp @@ -61,7 +61,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 Filter::GetParamType(AmUInt32 index) const { - return Filter::PARAM_FLOAT; + return Filter::kParameterTypeFloat; } AmReal32 Filter::GetParamMax(AmUInt32 index) const @@ -178,7 +178,7 @@ namespace SparkyStudios::Audio::Amplitude m_parameters = nullptr; m_numParams = 0; - return AM_ERROR_OUT_OF_MEMORY; + return eErrorCode_OutOfMemory; } std::memset(m_parameters, 0, m_numParams * sizeof(AmReal32)); diff --git a/src/DSP/Filters/BassBoostFilter.cpp b/src/DSP/Filters/BassBoostFilter.cpp index bc71c1f5..c89796ac 100644 --- a/src/DSP/Filters/BassBoostFilter.cpp +++ b/src/DSP/Filters/BassBoostFilter.cpp @@ -26,10 +26,10 @@ namespace SparkyStudios::Audio::Amplitude AmResult BassBoostFilter::Initialize(AmReal32 aBoost) { if (aBoost < 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; m_boost = aBoost; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 BassBoostFilter::GetParamCount() const @@ -47,7 +47,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 BassBoostFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 BassBoostFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/BiquadResonantFilter.cpp b/src/DSP/Filters/BiquadResonantFilter.cpp index 8bdf056c..68921133 100644 --- a/src/DSP/Filters/BiquadResonantFilter.cpp +++ b/src/DSP/Filters/BiquadResonantFilter.cpp @@ -30,14 +30,14 @@ namespace SparkyStudios::Audio::Amplitude AmResult BiquadResonantFilter::Initialize(TYPE type, AmReal32 frequency, AmReal32 resonance, AmReal32 gain) { if (type >= TYPE_LAST || frequency <= 0 || resonance <= 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _filterType = type; _frequency = frequency; _resonance = resonance; _gain = gain; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmResult BiquadResonantFilter::InitializeLowPass(AmReal32 frequency, AmReal32 q) @@ -109,9 +109,9 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 BiquadResonantFilter::GetParamType(AmUInt32 index) const { if (index == ATTRIBUTE_TYPE) - return PARAM_INT; + return kParameterTypeInt; - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 BiquadResonantFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/DCRemovalFilter.cpp b/src/DSP/Filters/DCRemovalFilter.cpp index 5f175b46..2b0a9ad1 100644 --- a/src/DSP/Filters/DCRemovalFilter.cpp +++ b/src/DSP/Filters/DCRemovalFilter.cpp @@ -26,11 +26,11 @@ namespace SparkyStudios::Audio::Amplitude AmResult DCRemovalFilter::Initialize(AmReal32 length) { if (length <= 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _length = length; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } FilterInstance* DCRemovalFilter::CreateInstance() @@ -45,25 +45,26 @@ namespace SparkyStudios::Audio::Amplitude DCRemovalFilterInstance::DCRemovalFilterInstance(DCRemovalFilter* parent) : FilterInstance(parent) - , _buffer(nullptr) - , _totals(nullptr) + , _buffer() + , _totals() , _bufferLength(0) , _offset(0) { - Initialize(1); + Initialize(DCRemovalFilter::ATTRIBUTE_LAST); + SetParameter(DCRemovalFilter::ATTRIBUTE_LAST, parent->_length); } DCRemovalFilterInstance::~DCRemovalFilterInstance() { - ampoolfree(MemoryPoolKind::Filtering, _buffer); - ampoolfree(MemoryPoolKind::Filtering, _totals); + _buffer.Clear(); + _totals.Clear(); } void DCRemovalFilterInstance::Process(const AudioBuffer& in, AudioBuffer& out, AmUInt64 frames, AmUInt32 sampleRate) { const AmUInt16 channels = in.GetChannelCount(); - if (_buffer == nullptr) + if (_buffer.GetPointer() == nullptr) { InitializeBuffer(channels, sampleRate); } @@ -103,12 +104,9 @@ namespace SparkyStudios::Audio::Amplitude void DCRemovalFilterInstance::InitializeBuffer(AmUInt16 channels, AmUInt32 sampleRate) { - _bufferLength = static_cast(std::ceil(dynamic_cast(m_parent)->_length * sampleRate)); + _bufferLength = static_cast(std::ceil(m_parameters[DCRemovalFilter::ATTRIBUTE_LENGTH] * sampleRate)); - _buffer = static_cast(ampoolmalloc(MemoryPoolKind::Filtering, _bufferLength * channels * sizeof(AmReal32))); - _totals = static_cast(ampoolmalloc(MemoryPoolKind::Filtering, channels * sizeof(AmReal32))); - - std::memset(_buffer, 0, _bufferLength * channels * sizeof(AmReal32)); - std::memset(_totals, 0, channels * sizeof(AmReal32)); + _buffer.Resize(_bufferLength * channels, true); + _totals.Resize(channels, true); } } // namespace SparkyStudios::Audio::Amplitude diff --git a/src/DSP/Filters/DCRemovalFilter.h b/src/DSP/Filters/DCRemovalFilter.h index 70ff8b84..7cc404bd 100644 --- a/src/DSP/Filters/DCRemovalFilter.h +++ b/src/DSP/Filters/DCRemovalFilter.h @@ -37,8 +37,8 @@ namespace SparkyStudios::Audio::Amplitude private: void InitializeBuffer(AmUInt16 channels, AmUInt32 sampleRate); - AmReal32Buffer _buffer; - AmReal32Buffer _totals; + AmAlignedReal32Buffer _buffer; + AmAlignedReal32Buffer _totals; AmUInt64 _bufferLength; AmUInt64 _offset; }; @@ -51,6 +51,7 @@ namespace SparkyStudios::Audio::Amplitude enum ATTRIBUTE { ATTRIBUTE_WET = 0, + ATTRIBUTE_LENGTH = 1, ATTRIBUTE_LAST }; diff --git a/src/DSP/Filters/DelayFilter.cpp b/src/DSP/Filters/DelayFilter.cpp index a7772fbb..4c8a4b7d 100644 --- a/src/DSP/Filters/DelayFilter.cpp +++ b/src/DSP/Filters/DelayFilter.cpp @@ -28,13 +28,13 @@ namespace SparkyStudios::Audio::Amplitude AmResult DelayFilter::Initialize(AmReal32 delay, AmReal32 decay, AmReal32 delayStart) { if (delay <= 0 || decay <= 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _delay = delay; _decay = decay; _delayStart = delayStart; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 DelayFilter::GetParamCount() const @@ -55,9 +55,9 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 DelayFilter::GetParamType(AmUInt32 index) const { if (index == ATTRIBUTE_DELAY_START) - return PARAM_BOOL; + return kParameterTypeBool; - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 DelayFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/EqualizerFilter.cpp b/src/DSP/Filters/EqualizerFilter.cpp index d0e943cd..7c95c181 100644 --- a/src/DSP/Filters/EqualizerFilter.cpp +++ b/src/DSP/Filters/EqualizerFilter.cpp @@ -38,28 +38,28 @@ namespace SparkyStudios::Audio::Amplitude AmReal32 volume8) { if (volume1 < GetParamMin(ATTRIBUTE_BAND_1) || volume1 > GetParamMax(ATTRIBUTE_BAND_1)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume2 < GetParamMin(ATTRIBUTE_BAND_2) || volume2 > GetParamMax(ATTRIBUTE_BAND_2)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume3 < GetParamMin(ATTRIBUTE_BAND_3) || volume3 > GetParamMax(ATTRIBUTE_BAND_3)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume4 < GetParamMin(ATTRIBUTE_BAND_4) || volume4 > GetParamMax(ATTRIBUTE_BAND_4)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume5 < GetParamMin(ATTRIBUTE_BAND_5) || volume5 > GetParamMax(ATTRIBUTE_BAND_5)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume6 < GetParamMin(ATTRIBUTE_BAND_6) || volume6 > GetParamMax(ATTRIBUTE_BAND_6)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume7 < GetParamMin(ATTRIBUTE_BAND_7) || volume7 > GetParamMax(ATTRIBUTE_BAND_7)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; if (volume8 < GetParamMin(ATTRIBUTE_BAND_8) || volume8 > GetParamMax(ATTRIBUTE_BAND_8)) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _volume[ATTRIBUTE_BAND_1 - ATTRIBUTE_BAND_1] = volume1; _volume[ATTRIBUTE_BAND_2 - ATTRIBUTE_BAND_1] = volume2; @@ -70,7 +70,7 @@ namespace SparkyStudios::Audio::Amplitude _volume[ATTRIBUTE_BAND_7 - ATTRIBUTE_BAND_1] = volume7; _volume[ATTRIBUTE_BAND_8 - ATTRIBUTE_BAND_1] = volume8; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 EqualizerFilter::GetParamCount() const @@ -107,7 +107,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 EqualizerFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 EqualizerFilter::GetParamMax(AmUInt32 index) const @@ -159,11 +159,13 @@ namespace SparkyStudios::Audio::Amplitude void EqualizerFilterInstance::ProcessFFTChannel( SplitComplex& fft, AmUInt16 channel, AmUInt64 frames, AmUInt16 channels, AmUInt32 sampleRate) { - Comp2MagPhase(fft, frames / 2); + const auto halfSize = frames / 2; + + Comp2MagPhase(fft, halfSize); - for (AmUInt32 p = 0, l = frames / 2; p < l; p++) + for (AmUInt32 p = 0, l = halfSize; p < l; p++) { - const auto i = static_cast(std::floor(std::sqrt(p / static_cast(frames / 2)) * (frames / 2))); + const auto i = static_cast(std::floor(std::sqrt(p / static_cast(halfSize)) * (halfSize))); AmInt32 p2 = (i / (frames / 16)); AmInt32 p1 = p2 - 1; @@ -181,8 +183,6 @@ namespace SparkyStudios::Audio::Amplitude fft.re()[p] *= CatmullRom(v, m_parameters[p0 + 1], m_parameters[p1 + 1], m_parameters[p2 + 1], m_parameters[p3 + 1]); } - const auto halfSize = frames / 2; - std::memset(fft.re() + halfSize, 0, sizeof(AmReal32) * halfSize); std::memset(fft.im() + halfSize, 0, sizeof(AmReal32) * halfSize); diff --git a/src/DSP/Filters/FFTFilter.cpp b/src/DSP/Filters/FFTFilter.cpp index c0474251..248e43fe 100644 --- a/src/DSP/Filters/FFTFilter.cpp +++ b/src/DSP/Filters/FFTFilter.cpp @@ -13,7 +13,7 @@ // limitations under the License. #include -#include +#include #include @@ -54,6 +54,19 @@ namespace SparkyStudios::Audio::Amplitude FFTFilterInstance::~FFTFilterInstance() { ampoolfree(MemoryPoolKind::Filtering, _temp); + _temp = nullptr; + + if (_sumPhase != nullptr) + { + ampoolfree(MemoryPoolKind::Filtering, _sumPhase); + _sumPhase = nullptr; + } + + if (_lastPhase != nullptr) + { + ampoolfree(MemoryPoolKind::Filtering, _lastPhase); + _lastPhase = nullptr; + } } void FFTFilterInstance::InitializeFFT() @@ -61,6 +74,27 @@ namespace SparkyStudios::Audio::Amplitude _temp = static_cast(ampoolmalloc(MemoryPoolKind::Filtering, STFT_WINDOW_SIZE * sizeof(AmReal32))); } + void FFTFilterInstance::Process(const AudioBuffer& in, AudioBuffer& out, AmUInt64 frames, AmUInt32 sampleRate) + { + if (_sumPhase == nullptr) + { + _sumPhase = static_cast( + ampoolmalloc(MemoryPoolKind::Filtering, STFT_WINDOW_SIZE * in.GetChannelCount() * sizeof(AmReal32))); + + std::memset(_sumPhase, 0, sizeof(AmReal32) * STFT_WINDOW_SIZE * in.GetChannelCount()); + } + + if (_lastPhase == nullptr) + { + _lastPhase = static_cast( + ampoolmalloc(MemoryPoolKind::Filtering, STFT_WINDOW_SIZE * in.GetChannelCount() * sizeof(AmReal32))); + + std::memset(_lastPhase, 0, sizeof(AmReal32) * STFT_WINDOW_SIZE * in.GetChannelCount()); + } + + FilterInstance::Process(in, out, frames, sampleRate); + } + void FFTFilterInstance::ProcessChannel(const AudioBuffer& in, AudioBuffer& out, AmUInt16 channel, AmUInt64 frames, AmUInt32 sampleRate) { const auto& inChannel = in[channel]; @@ -114,7 +148,7 @@ namespace SparkyStudios::Audio::Amplitude const AmReal32 r = fft.re()[s]; const AmReal32 i = fft.im()[s]; - fft.re()[s] = std::sqrt(r * r + i * i); + fft.re()[s] = std::sqrt(r * r + i * i) * 2.0f; fft.im()[s] = std::atan2(i, r); } } @@ -122,7 +156,7 @@ namespace SparkyStudios::Audio::Amplitude void FFTFilterInstance::MagPhase2MagFreq(SplitComplex& fft, AmUInt32 samples, AmUInt32 sampleRate, AmUInt16 channel) { const AmReal32 stepSize = static_cast(samples) / static_cast(sampleRate); - const AmReal32 expect = (stepSize / static_cast(samples)) * 2.0f * static_cast(M_PI); + const AmReal32 expect = (stepSize / static_cast(samples)) * 2.0f * AM_PI32; const AmReal32 freqPerBin = static_cast(sampleRate) / static_cast(samples); for (AmUInt32 s = 0; s < samples; s++) @@ -130,26 +164,28 @@ namespace SparkyStudios::Audio::Amplitude // get true frequency from synthesis arrays const AmReal32 pha = fft.im()[s]; - AmReal32 freq = pha; + // compute phase difference + AmReal32 freq = pha - _lastPhase[s + channel * STFT_WINDOW_SIZE]; + _lastPhase[s + channel * STFT_WINDOW_SIZE] = pha; // subtract expected phase difference freq -= static_cast(s) * expect; // map delta phase into +/- Pi interval - auto qpd = static_cast(std::floor(freq / static_cast(M_PI))); + auto qpd = static_cast(std::floor(freq / AM_PI32)); if (qpd >= 0) qpd += qpd & 1; else qpd -= qpd & 1; - freq -= static_cast(M_PI) * static_cast(qpd); + freq -= AM_PI32 * static_cast(qpd); // get deviation from bin frequency from the +/- Pi interval - freq = static_cast(samples) * freq / (2.0f * static_cast(M_PI)); + freq = samples * freq / (2.0f * AM_PI32); // compute the k-th partials' true frequency - freq = static_cast(s) * freqPerBin + freq * freqPerBin; + freq = s * freqPerBin + freq * freqPerBin; // store magnitude and true frequency in analysis arrays fft.im()[s] = freq; @@ -159,7 +195,7 @@ namespace SparkyStudios::Audio::Amplitude void FFTFilterInstance::MagFreq2MagPhase(SplitComplex& fft, AmUInt32 samples, AmUInt32 sampleRate, AmUInt16 channel) { const AmReal32 stepSize = static_cast(samples) / static_cast(sampleRate); - const AmReal32 expect = (stepSize / static_cast(samples)) * 2.0f * static_cast(M_PI); + const AmReal32 expect = (stepSize / static_cast(samples)) * 2.0f * AM_PI32; const AmReal32 freqPerBin = static_cast(sampleRate) / static_cast(samples); for (AmUInt32 s = 0; s < samples; s++) @@ -176,12 +212,13 @@ namespace SparkyStudios::Audio::Amplitude pha /= freqPerBin; // take osamp into account - pha = (pha / static_cast(samples)) * static_cast(M_PI) * 2.0f; + pha = (pha / static_cast(samples)) * AM_PI32 * 2.0f; // add the overlap phase advance back in pha += static_cast(s) * expect; - fft.im()[s] = pha; + _sumPhase[s + channel * STFT_WINDOW_SIZE] += pha; + fft.im()[s] = _sumPhase[s + channel * STFT_WINDOW_SIZE]; } } diff --git a/src/DSP/Filters/FFTFilter.h b/src/DSP/Filters/FFTFilter.h index 302deb18..c76fed35 100644 --- a/src/DSP/Filters/FFTFilter.h +++ b/src/DSP/Filters/FFTFilter.h @@ -18,7 +18,7 @@ #define _AM_IMPLEMENTATION_DSP_FILTERS_FFT_FILTER_H #include -#include +#include namespace SparkyStudios::Audio::Amplitude { @@ -43,6 +43,7 @@ namespace SparkyStudios::Audio::Amplitude ~FFTFilterInstance() override; protected: + void Process(const AudioBuffer& in, AudioBuffer& out, AmUInt64 frames, AmUInt32 sampleRate) override; void ProcessChannel(const AudioBuffer& in, AudioBuffer& out, AmUInt16 channel, AmUInt64 frames, AmUInt32 sampleRate) override; virtual void ProcessFFTChannel(SplitComplex& fft, AmUInt16 channel, AmUInt64 frames, AmUInt16 channels, AmUInt32 sampleRate); @@ -57,6 +58,8 @@ namespace SparkyStudios::Audio::Amplitude private: AmReal32Buffer _temp = nullptr; + AmReal32Buffer _sumPhase = nullptr; + AmReal32Buffer _lastPhase = nullptr; }; } // namespace SparkyStudios::Audio::Amplitude diff --git a/src/DSP/Filters/FlangerFilter.cpp b/src/DSP/Filters/FlangerFilter.cpp index 6218c066..053cd494 100644 --- a/src/DSP/Filters/FlangerFilter.cpp +++ b/src/DSP/Filters/FlangerFilter.cpp @@ -27,12 +27,12 @@ namespace SparkyStudios::Audio::Amplitude AmResult FlangerFilter::Initialize(AmReal32 delay, AmReal32 frequency) { if (delay <= 0 || frequency <= 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _delay = delay; _frequency = frequency; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 FlangerFilter::GetParamCount() const @@ -52,7 +52,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 FlangerFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 FlangerFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/LofiFilter.cpp b/src/DSP/Filters/LofiFilter.cpp index 55d2379f..1e4c68df 100644 --- a/src/DSP/Filters/LofiFilter.cpp +++ b/src/DSP/Filters/LofiFilter.cpp @@ -28,12 +28,12 @@ namespace SparkyStudios::Audio::Amplitude AmResult LofiFilter::Init(AmReal32 sampleRate, AmReal32 bitDepth) { if (sampleRate <= 0 || bitDepth <= 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _sampleRate = sampleRate; _bitDepth = bitDepth; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 LofiFilter::GetParamCount() const @@ -79,7 +79,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 LofiFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } FilterInstance* LofiFilter::CreateInstance() diff --git a/src/DSP/Filters/MonoPoleFilter.cpp b/src/DSP/Filters/MonoPoleFilter.cpp index 329b38ab..1493958e 100644 --- a/src/DSP/Filters/MonoPoleFilter.cpp +++ b/src/DSP/Filters/MonoPoleFilter.cpp @@ -53,11 +53,11 @@ namespace SparkyStudios::Audio::Amplitude AmResult MonoPoleFilter::Initialize(AmReal32 coefficient) { if (coefficient < 0.0f || coefficient > 1.0f) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _coefficient = AM_CLAMP(coefficient, 0.0f, 1.0f); - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 MonoPoleFilter::GetParamCount() const @@ -77,7 +77,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 MonoPoleFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 MonoPoleFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/RobotizeFilter.cpp b/src/DSP/Filters/RobotizeFilter.cpp index 02a01f37..c222fd0a 100644 --- a/src/DSP/Filters/RobotizeFilter.cpp +++ b/src/DSP/Filters/RobotizeFilter.cpp @@ -30,7 +30,7 @@ namespace SparkyStudios::Audio::Amplitude m_frequency = frequency; m_waveform = waveform; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 RobotizeFilter::GetParamCount() const @@ -50,9 +50,9 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 RobotizeFilter::GetParamType(AmUInt32 index) const { if (index == ATTRIBUTE_WAVEFORM) - return PARAM_INT; + return kParameterTypeInt; - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 RobotizeFilter::GetParamMax(AmUInt32 index) const diff --git a/src/DSP/Filters/WaveShaperFilter.cpp b/src/DSP/Filters/WaveShaperFilter.cpp index c508ca1f..3a9525f1 100644 --- a/src/DSP/Filters/WaveShaperFilter.cpp +++ b/src/DSP/Filters/WaveShaperFilter.cpp @@ -27,10 +27,10 @@ namespace SparkyStudios::Audio::Amplitude AmResult WaveShaperFilter::Init(AmReal32 amount) { if (_amount < -1.0f || _amount > 1.0f) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; _amount = amount; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmUInt32 WaveShaperFilter::GetParamCount() const @@ -49,7 +49,7 @@ namespace SparkyStudios::Audio::Amplitude AmUInt32 WaveShaperFilter::GetParamType(AmUInt32 index) const { - return PARAM_FLOAT; + return kParameterTypeFloat; } AmReal32 WaveShaperFilter::GetParamMax(AmUInt32 index) const diff --git a/src/Math/SplitComplex.cpp b/src/DSP/SplitComplex.cpp similarity index 97% rename from src/Math/SplitComplex.cpp rename to src/DSP/SplitComplex.cpp index d3cf93c8..2b629a98 100644 --- a/src/Math/SplitComplex.cpp +++ b/src/DSP/SplitComplex.cpp @@ -12,7 +12,7 @@ // See the License for the specific language governing permissions and // limitations under the License. -#include +#include namespace SparkyStudios::Audio::Amplitude { diff --git a/src/IO/DiskFile.cpp b/src/IO/DiskFile.cpp index 063fcd18..e78c0e8b 100644 --- a/src/IO/DiskFile.cpp +++ b/src/IO/DiskFile.cpp @@ -24,7 +24,7 @@ namespace SparkyStudios::Audio::Amplitude : m_fileHandle(fp) {} - DiskFile::DiskFile(const std::filesystem::path& fileName, FileOpenMode mode, FileOpenKind kind) + DiskFile::DiskFile(const std::filesystem::path& fileName, eFileOpenMode mode, eFileOpenKind kind) : DiskFile() { Open(fileName, mode, kind); @@ -71,7 +71,7 @@ namespace SparkyStudios::Audio::Amplitude return len; } - void DiskFile::Seek(AmInt64 offset, FileSeekOrigin origin) + void DiskFile::Seek(AmInt64 offset, eFileSeekOrigin origin) { fseek(m_fileHandle, offset, origin); } @@ -91,29 +91,29 @@ namespace SparkyStudios::Audio::Amplitude return m_fileHandle != nullptr; } - AmResult DiskFile::Open(const std::filesystem::path& filePath, FileOpenMode mode, FileOpenKind kind) + AmResult DiskFile::Open(const std::filesystem::path& filePath, eFileOpenMode mode, eFileOpenKind kind) { if (filePath.empty()) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; AmOsString op{}; switch (mode) { - case eFOM_READ: - op = kind == eFOK_TEXT ? AM_OS_STRING("r") : AM_OS_STRING("rb"); + case eFileOpenMode_Read: + op = kind == eFileOpenKind_Text ? AM_OS_STRING("r") : AM_OS_STRING("rb"); break; - case eFOM_WRITE: - op = kind == eFOK_TEXT ? AM_OS_STRING("w") : AM_OS_STRING("wb"); + case eFileOpenMode_Write: + op = kind == eFileOpenKind_Text ? AM_OS_STRING("w") : AM_OS_STRING("wb"); break; - case eFOM_APPEND: - op = kind == eFOK_TEXT ? AM_OS_STRING("a") : AM_OS_STRING("ab"); + case eFileOpenMode_Append: + op = kind == eFileOpenKind_Text ? AM_OS_STRING("a") : AM_OS_STRING("ab"); break; - case eFOM_READWRITE: - op = kind == eFOK_TEXT ? AM_OS_STRING("w+") : AM_OS_STRING("wb+"); + case eFileOpenMode_ReadWrite: + op = kind == eFileOpenKind_Text ? AM_OS_STRING("w+") : AM_OS_STRING("wb+"); break; - case eFOM_READAPPEND: - op = kind == eFOK_TEXT ? AM_OS_STRING("a+") : AM_OS_STRING("ab+"); + case eFileOpenMode_ReadAppend: + op = kind == eFileOpenKind_Text ? AM_OS_STRING("a+") : AM_OS_STRING("ab+"); break; } @@ -124,11 +124,11 @@ namespace SparkyStudios::Audio::Amplitude #endif if (!m_fileHandle) - return AM_ERROR_FILE_NOT_FOUND; + return eErrorCode_FileNotFound; m_filePath = filePath; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } void DiskFile::Close() @@ -139,4 +139,4 @@ namespace SparkyStudios::Audio::Amplitude fclose(m_fileHandle); m_fileHandle = nullptr; } -} \ No newline at end of file +} // namespace SparkyStudios::Audio::Amplitude \ No newline at end of file diff --git a/src/IO/DiskFileSystem.cpp b/src/IO/DiskFileSystem.cpp index 88b45b1f..64f16c4b 100644 --- a/src/IO/DiskFileSystem.cpp +++ b/src/IO/DiskFileSystem.cpp @@ -65,7 +65,7 @@ namespace SparkyStudios::Audio::Amplitude return joined.native(); } - std::shared_ptr DiskFileSystem::OpenFile(const AmOsString& path, FileOpenMode mode) const + std::shared_ptr DiskFileSystem::OpenFile(const AmOsString& path, eFileOpenMode mode) const { auto file = std::shared_ptr(ampoolnew(MemoryPoolKind::IO, DiskFile), am_delete{}); file->Open(ResolvePath(path), mode); diff --git a/src/IO/File.cpp b/src/IO/File.cpp index 87bbc106..7fe7ca37 100644 --- a/src/IO/File.cpp +++ b/src/IO/File.cpp @@ -84,7 +84,7 @@ namespace SparkyStudios::Audio::Amplitude void File::Seek(AmSize offset) { - Seek(offset, eFSO_START); + Seek(offset, eFileSeekOrigin_Start); } AmVoidPtr File::GetPtr() diff --git a/src/IO/MemoryFile.cpp b/src/IO/MemoryFile.cpp index ba0b5e8d..b6c9ff3b 100644 --- a/src/IO/MemoryFile.cpp +++ b/src/IO/MemoryFile.cpp @@ -74,13 +74,13 @@ namespace SparkyStudios::Audio::Amplitude return m_dataSize; } - void MemoryFile::Seek(AmInt64 offset, FileSeekOrigin origin) + void MemoryFile::Seek(AmInt64 offset, eFileSeekOrigin origin) { - if (origin == eFSO_START) + if (origin == eFileSeekOrigin_Start) m_offset = offset; - else if (origin == eFSO_CURRENT) + else if (origin == eFileSeekOrigin_Current) m_offset += offset; - else if (origin == eFSO_END) + else if (origin == eFileSeekOrigin_End) m_offset = m_dataSize + offset; if (m_offset > m_dataSize - 1) @@ -110,7 +110,7 @@ namespace SparkyStudios::Audio::Amplitude AmResult MemoryFile::OpenMem(AmConstUInt8Buffer buffer, AmSize size, bool copy, bool takeOwnership) { if (buffer == nullptr || size == 0) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; Close(); @@ -122,47 +122,47 @@ namespace SparkyStudios::Audio::Amplitude m_dataPtr = static_cast(ampoolmalloc(MemoryPoolKind::IO, size)); if (m_dataPtr == nullptr) - return AM_ERROR_OUT_OF_MEMORY; + return eErrorCode_OutOfMemory; std::memcpy(m_dataPtr, buffer, size); - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } m_dataPtr = const_cast(buffer); m_dataOwned = takeOwnership; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmResult MemoryFile::OpenToMem(const std::filesystem::path& fileName) { if (fileName.empty()) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; Close(); DiskFile df; - if (const AmResult res = df.Open(fileName); res != AM_ERROR_NO_ERROR) + if (const AmResult res = df.Open(fileName); res != eErrorCode_Success) return res; m_dataSize = df.Length(); m_dataPtr = static_cast(ampoolmalloc(MemoryPoolKind::IO, m_dataSize)); if (m_dataPtr == nullptr) - return AM_ERROR_OUT_OF_MEMORY; + return eErrorCode_OutOfMemory; df.Read(m_dataPtr, m_dataSize); m_dataOwned = true; df.Close(); - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } AmResult MemoryFile::OpenFileToMem(File* file) { if (!file) - return AM_ERROR_INVALID_PARAMETER; + return eErrorCode_InvalidParameter; Close(); m_offset = file->Position(); @@ -171,15 +171,15 @@ namespace SparkyStudios::Audio::Amplitude m_dataPtr = static_cast(ampoolmalloc(MemoryPoolKind::IO, m_dataSize)); if (m_dataPtr == nullptr) - return AM_ERROR_OUT_OF_MEMORY; + return eErrorCode_OutOfMemory; - file->Seek(0, eFSO_START); + file->Seek(0, eFileSeekOrigin_Start); file->Read(m_dataPtr, m_dataSize); - file->Seek(m_offset, eFSO_START); + file->Seek(m_offset, eFileSeekOrigin_Start); m_dataOwned = true; - return AM_ERROR_NO_ERROR; + return eErrorCode_Success; } void MemoryFile::Close() diff --git a/src/IO/PackageFileSystem.cpp b/src/IO/PackageFileSystem.cpp index 27af101d..83bca394 100644 --- a/src/IO/PackageFileSystem.cpp +++ b/src/IO/PackageFileSystem.cpp @@ -93,7 +93,7 @@ namespace SparkyStudios::Audio::Amplitude return joined; } - std::shared_ptr PackageFileSystem::OpenFile(const AmOsString& path, FileOpenMode mode) const + std::shared_ptr PackageFileSystem::OpenFile(const AmOsString& path, eFileOpenMode mode) const { if (!_valid) return nullptr; @@ -169,7 +169,7 @@ namespace SparkyStudios::Audio::Amplitude } // Compression Algorithm - pFileSystem->_header.m_CompressionAlgorithm = static_cast(pFileSystem->_packageFile->Read8()); + pFileSystem->_header.m_CompressionAlgorithm = static_cast(pFileSystem->_packageFile->Read8()); // Item Descriptions if (const AmSize itemsCount = pFileSystem->_packageFile->Read64(); itemsCount > 0) diff --git a/src/IO/PackageItemFile.cpp b/src/IO/PackageItemFile.cpp index 1f9e6835..4fb71629 100644 --- a/src/IO/PackageItemFile.cpp +++ b/src/IO/PackageItemFile.cpp @@ -22,7 +22,7 @@ namespace SparkyStudios::Audio::Amplitude , _headerSize(headerSize) { Open(packageFile); - PackageItemFile::Seek(0, eFSO_START); + PackageItemFile::Seek(0, eFileSeekOrigin_Start); } AmOsString PackageItemFile::GetPath() const @@ -52,33 +52,33 @@ namespace SparkyStudios::Audio::Amplitude return _description->m_Size; } - void PackageItemFile::Seek(AmInt64 offset, FileSeekOrigin origin) + void PackageItemFile::Seek(AmInt64 offset, eFileSeekOrigin origin) { - if (origin == eFSO_START && Position() == offset) + if (origin == eFileSeekOrigin_Start && Position() == offset) return; - if (origin == eFSO_END && Position() == (Length() + offset)) + if (origin == eFileSeekOrigin_End && Position() == (Length() + offset)) return; - if (origin == eFSO_CURRENT && offset == 0) + if (origin == eFileSeekOrigin_Current && offset == 0) return; AmInt64 finalOffset = _headerSize + _description->m_Offset; switch (origin) { - case eFSO_START: + case eFileSeekOrigin_Start: finalOffset += offset; break; - case eFSO_END: + case eFileSeekOrigin_End: finalOffset += Length() + offset; break; - case eFSO_CURRENT: + case eFileSeekOrigin_Current: finalOffset += Position() + offset; break; } - DiskFile::Seek(finalOffset, eFSO_START); + DiskFile::Seek(finalOffset, eFileSeekOrigin_Start); } AmSize PackageItemFile::Position() diff --git a/src/Sound/Fader.cpp b/src/Sound/Fader.cpp index bf61f6f9..25e6b12a 100644 --- a/src/Sound/Fader.cpp +++ b/src/Sound/Fader.cpp @@ -17,7 +17,7 @@ namespace SparkyStudios::Audio::Amplitude { - typedef std::map FaderRegistry; + typedef std::map FaderRegistry; typedef FaderRegistry::value_type FaderImpl; static constexpr AmUInt32 kNewtonIterations = 4; @@ -160,7 +160,7 @@ namespace SparkyStudios::Audio::Amplitude { m_from = m_to = m_delta = 0; m_time = m_startTime = m_endTime = 0; - m_state = AM_FADER_STATE_DISABLED; + m_state = eFaderState_Disabled; } void FaderInstance::Set(AmReal64 from, AmReal64 to, AmTime duration) @@ -184,7 +184,7 @@ namespace SparkyStudios::Audio::Amplitude AmReal64 FaderInstance::GetFromTime(AmTime time) { - if (m_state != AM_FADER_STATE_ACTIVE) + if (m_state != eFaderState_Active) return 0.0f; if (m_startTime >= time) @@ -206,7 +206,7 @@ namespace SparkyStudios::Audio::Amplitude { m_startTime = time; m_endTime = m_startTime + m_time; - m_state = AM_FADER_STATE_ACTIVE; + m_state = eFaderState_Active; } static FaderRegistry& faderRegistry() @@ -227,7 +227,7 @@ namespace SparkyStudios::Audio::Amplitude return c; } - Fader::Fader(std::string name) + Fader::Fader(AmString name) : m_name(std::move(name)) { Register(this); @@ -242,7 +242,7 @@ namespace SparkyStudios::Audio::Amplitude Unregister(this); } - const std::string& Fader::GetName() const + const AmString& Fader::GetName() const { return m_name; } @@ -276,7 +276,7 @@ namespace SparkyStudios::Audio::Amplitude } } - Fader* Fader::Find(const std::string& name) + Fader* Fader::Find(const AmString& name) { const FaderRegistry& faders = faderRegistry(); if (const auto& it = faders.find(name); it != faders.end()) @@ -285,7 +285,7 @@ namespace SparkyStudios::Audio::Amplitude return nullptr; } - FaderInstance* Fader::Construct(const std::string& name) + FaderInstance* Fader::Construct(const AmString& name) { Fader* fader = Find(name); if (fader == nullptr) @@ -294,7 +294,7 @@ namespace SparkyStudios::Audio::Amplitude return fader->CreateInstance(); } - void Fader::Destruct(const std::string& name, FaderInstance* instance) + void Fader::Destruct(const AmString& name, FaderInstance* instance) { if (instance == nullptr) return; @@ -316,7 +316,7 @@ namespace SparkyStudios::Audio::Amplitude lockFaders() = false; } - const std::map& Fader::GetRegistry() + const std::map& Fader::GetRegistry() { return faderRegistry(); } diff --git a/src/Utils/Utils.h b/src/Utils/Utils.h index e0ea6f74..940d3b3e 100644 --- a/src/Utils/Utils.h +++ b/src/Utils/Utils.h @@ -18,7 +18,7 @@ #define _AM_IMPLEMENTATION_UTILS_UTILS_H #include -#include +#include #include #if defined(AM_SIMD_INTRINSICS) diff --git a/tools/amac/main.cpp b/tools/amac/main.cpp index 73b8d8c5..67572463 100644 --- a/tools/amac/main.cpp +++ b/tools/amac/main.cpp @@ -100,8 +100,8 @@ static int process(const AmOsString& inFileName, const AmOsString& outFileName, AmInt32 res; DiskFileSystem fs; - const auto inputFile = fs.OpenFile(inFileName, eFOM_READ); - const auto outputFile = fs.OpenFile(outFileName, eFOM_WRITE); + const auto inputFile = fs.OpenFile(inFileName, eFileOpenMode_Read); + const auto outputFile = fs.OpenFile(outFileName, eFileOpenMode_Write); auto* ams_codec = Codec::Find("ams"); auto* wav_codec = Codec::Find("wav"); @@ -176,7 +176,7 @@ static int process(const AmOsString& inFileName, const AmOsString& outFileName, } SoundFormat encodeFormat{}; - encodeFormat.SetAll(sampleRate, numChannels, format.GetBitsPerSample(), numSamples, framesSize, AM_SAMPLE_FORMAT_INT); + encodeFormat.SetAll(sampleRate, numChannels, format.GetBitsPerSample(), numSamples, framesSize, eAudioSampleFormat_Int16); encoder->SetFormat(encodeFormat); if (!encoder->Open(outputFile)) @@ -217,7 +217,7 @@ static int process(const AmOsString& inFileName, const AmOsString& outFileName, 16, // always decode in 16 bits per sample amsFormat.GetFramesCount(), amsFormat.GetNumChannels() * sizeof(AmInt16), // Always decode in 16 bits signed integers - AM_SAMPLE_FORMAT_INT); + eAudioSampleFormat_Int16); encoder->SetFormat(wavFormat); if (!encoder->Open(outputFile)) @@ -254,7 +254,6 @@ static int process(const AmOsString& inFileName, const AmOsString& outFileName, log(stdout, "Operation completed successfully.\n"); } - ams_codec->DestroyDecoder(decoder); wav_codec->DestroyEncoder(encoder); diff --git a/tools/amir/main.cpp b/tools/amir/main.cpp index ff647cd0..a337f6ad 100644 --- a/tools/amir/main.cpp +++ b/tools/amir/main.cpp @@ -321,7 +321,7 @@ int process(const AmOsString& inFileName, const AmOsString& outFileName, const P std::vector vertices; std::vector indices; - DiskFile packageFile(absolute(packagePath), eFOM_WRITE); + DiskFile packageFile(absolute(packagePath), eFileOpenMode_Write); if (state.datasetModel != eHRIRSphereDatasetModel_SOFA) { diff --git a/tools/ampk/main.cpp b/tools/ampk/main.cpp index fc3067ab..e08c4730 100644 --- a/tools/ampk/main.cpp +++ b/tools/ampk/main.cpp @@ -23,7 +23,7 @@ struct ProcessingState { bool verbose = false; - PackageFileCompressionAlgorithm compression = ePCA_None; + ePackageFileCompressionAlgorithm compression = ePackageFileCompressionAlgorithm_None; }; static constexpr AmUInt32 kCurrentVersion = 1; @@ -82,11 +82,11 @@ static int process(const AmOsString& inFileName, const AmOsString& outFileName, } } - DiskFile packageFile(absolute(packagePath), eFOM_WRITE); + DiskFile packageFile(absolute(packagePath), eFileOpenMode_Write); packageFile.Write(reinterpret_cast("AMPK"), 4); packageFile.Write16(kCurrentVersion); - packageFile.Write8(ePCA_None); // TODO: state.compression + packageFile.Write8(ePackageFileCompressionAlgorithm_None); // TODO: state.compression AmSize lastOffset = 0; std::vector buffer; @@ -183,9 +183,10 @@ int main(int argc, char* argv[]) case 'C': case 'c': - state.compression = static_cast(strtol(argv[++i], argv, 10)); + state.compression = static_cast(strtol(argv[++i], argv, 10)); - if (state.compression < ePCA_None || state.compression >= ePCA_Invalid) + if (state.compression < ePackageFileCompressionAlgorithm_None || + state.compression >= ePackageFileCompressionAlgorithm_Invalid) { log(stderr, "\nInvalid compression algorithm!\n"); return EXIT_FAILURE;