feat: Added natural air absorption in attenuation models.

Signed-off-by: Axel Nana <[email protected]>

include/SparkyStudios/Audio/Amplitude/Core/Common/Constants.h

@@ -23,94 +23,159 @@ namespace SparkyStudios::Audio::Amplitude
 {
     /**
      * @brief Invalid Amplitude object ID.
+     *
+     * @ingroup core
      */
     constexpr AmObjectID kAmInvalidObjectId = 0;
 
     /**
      * @brief Specifies the value of the "master" bus ID.
+     *
+     * @ingroup core
      */
     constexpr AmBusID kAmMasterBusId = 1;
 
     /**
      * @brief The number of milliseconds in one second.
+     *
+     * @ingroup core
      */
     constexpr AmTime kAmSecond = 1000.0;
 
     /**
      * @brief Minimum value where values lower than this are considered to be 0.
+     *
+     * @ingroup core
      */
     constexpr AmReal32 kEpsilon = 1e-6f;
 
     /**
      * @brief The minimum fade duration in milliseconds.
+     *
+     * @ingroup core
      */
     constexpr AmTime kMinFadeDuration = 10.0;
 
     /**
      * @brief The number of bits to shift when processing audio data with floating point values.
+     *
+     * @ingroup core
      */
     constexpr AmInt32 kAmFixedPointBits = 15;
 
+    /**
+     * @brief The unit value for a 32-bit fixed-point audio sample..
+     *
+     * @ingroup core
+     */
     constexpr AmInt32 kAmFixedPointUnit = (1 << kAmFixedPointBits);
 
+    /**
+     * @brief Used to mask the bits when processing audio data with fixed-point values.
+     *
+     * @ingroup core
+     */
     constexpr AmInt32 kAmFixedPointMask = (kAmFixedPointBits - 1);
 
     /**
      * @brief The maximum number of frames that can be processed at once.
+     *
+     * @ingroup core
      */
     constexpr AmUInt64 kAmMaxSupportedFrameCount = 16384;
 
     /**
      * @brief The maximum supported ambisonic order.
+     *
+     * @ingroup core
      */
     constexpr AmUInt32 kAmMaxSupportedAmbisonicOrder = 3;
 
     /**
      * @brief The number of surfaces in a room.
      *
-     * @note Only cube-shaped rooms are supported.
+     * @warning Only cube-shaped rooms are supported.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmRoomSurfaceCount = 6;
 
     /**
      * @brief The number of channels in a mono audio source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmMonoChannelCount = 1;
 
     /**
      * @brief The number of channels in a stereo audio source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmStereoChannelCount = 2;
 
     /**
      * @brief The number of channels in a 5.1 surround audio source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAm51SurroundChannelCount = 6;
 
     /**
      * @brief The number of channels in a 7.1 surround audio source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAm71SurroundChannelCount = 8;
 
     /**
      * @brief The number of channels in first-order ambisonic source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmFirstOrderAmbisonicChannelCount = 4;
 
     /**
      * @brief The number of channels in second-order ambisonic source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmSecondOrderAmbisonicChannelCount = 9;
 
     /**
      * @brief The number of channels in third-order ambisonic source.
+     *
+     * @ingroup core
      */
     constexpr AmSize kAmThirdOrderAmbisonicChannelCount = 16;
 
     /**
      * @brief The maximum supported channel count for an ambisonic source.
+     *
+     * @ingroup core
      */
     constexpr AmUInt32 kAmMaxSupportedChannelCount = (kAmMaxSupportedAmbisonicOrder + 1) * (kAmMaxSupportedAmbisonicOrder + 1);
+
+    /**
+     * @brief The number of air absorption bands for attenuation models.
+     *
+     * @ingroup core
+     */
+    constexpr AmUInt32 kAmAirAbsorptionBandCount = 3;
+
+    /**
+     * @brief The low cutoff frequencies for air absorption models.
+     *
+     * @ingroup core
+     */
+    constexpr AmReal32 kLowCutoffFrequencies[kAmAirAbsorptionBandCount] = { 0.0f, 800.0f, 8000.0f };
+
+    /**
+     * @brief The high cutoff frequencies for air absorption models.
+     *
+     * @ingroup core
+     */
+    constexpr AmReal32 kHighCutoffFrequencies[kAmAirAbsorptionBandCount] = { 800.0f, 8000.0f, 22000.0f };
 } // namespace SparkyStudios::Audio::Amplitude
 
 #endif // _AM_CORE_COMMON_CONSTANTS_H

include/SparkyStudios/Audio/Amplitude/Sound/Attenuation.h

@@ -122,6 +122,30 @@ namespace SparkyStudios::Audio::Amplitude
          * @return The maximum sound attenuation distance.
          */
         [[nodiscard]] virtual AmReal64 GetMaxDistance() const = 0;
+
+        /**
+         * @brief Returns whether air absorption is enabled for this Attenuation.
+         *
+         * @return `true` if air absorption is enabled, `false` otherwise.
+         */
+        [[nodiscard]] virtual bool IsAirAbsorptionEnabled() const = 0;
+
+        /**
+         * @brief Evaluates the air absorption effect for a specific frequency band.
+         *
+         * This method calculates the attenuation factor due to air absorption
+         * 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.
+         *
+         * @return The air absorption attenuation factor for the given frequency band.
+         * The returned value is in decibels (dB).
+         */
+        [[nodiscard]] virtual AmReal32 EvaluateAirAbsorption(
+            const AmVec3& soundLocation, const AmVec3& listenerLocation, AmUInt32 band) const = 0;
     };
 } // namespace SparkyStudios::Audio::Amplitude
 

schemas/attenuation_definition.fbs

@@ -26,6 +26,16 @@ table AttenuationShapeDefinition {
   max_attenuation_factor:float;
 }
 
+/// Schema for air absorption model configuration.
+table AttenuationAirAbsorptionDefinition {
+  /// Whether the attenuation model supports air absorption.
+  enabled:bool = true;
+
+  /// The absorption coefficients to use when generating the 3-band EQ values.
+  /// This array should have exactly 3 values if set.
+  coefficients:[float];
+}
+
 /// The attenuation definition.
 table AttenuationDefinition {
   /// The attenuation object ID.
@@ -42,6 +52,9 @@ table AttenuationDefinition {
 
   /// The curve that the attenuation will use to know the sound gain according to the distance from the listener.
   gain_curve:CurveDefinition;
+
+  /// The air absorption model for this attenuation.
+  air_absorption:AttenuationAirAbsorptionDefinition;
 }
 
 root_type AttenuationDefinition;