libs/faudio/include/FAudioFX.h

   1 /* FAudio - XAudio Reimplementation for FNA
   2  *
   3  * Copyright (c) 2011-2023 Ethan Lee, Luigi Auriemma, and the MonoGame Team
   4  *
   5  * This software is provided 'as-is', without any express or implied warranty.
   6  * In no event will the authors be held liable for any damages arising from
   7  * the use of this software.
   8  *
   9  * Permission is granted to anyone to use this software for any purpose,
  10  * including commercial applications, and to alter it and redistribute it
  11  * freely, subject to the following restrictions:
  12  *
  13  * 1. The origin of this software must not be misrepresented; you must not
  14  * claim that you wrote the original software. If you use this software in a
  15  * product, an acknowledgment in the product documentation would be
  16  * appreciated but is not required.
  17  *
  18  * 2. Altered source versions must be plainly marked as such, and must not be
  19  * misrepresented as being the original software.
  20  *
  21  * 3. This notice may not be removed or altered from any source distribution.
  22  *
  23  * Ethan "flibitijibibo" Lee <flibitijibibo@flibitijibibo.com>
  24  *
  25  */
  26
  27 /* This file has no documentation since the MSDN docs are still perfectly fine:
  28  * https://docs.microsoft.com/en-us/windows/desktop/api/xaudio2fx/
  29  *
  30  * Note, however, that FAudio's Reverb implementation does NOT support the new
  31  * parameters for XAudio 2.9's 7.1 Reverb effect!
  32  */
  33
  34 #ifndef FAUDIOFX_H
  35 #define FAUDIOFX_H
  36
  37 #include "FAudio.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif /* __cplusplus */
  42
  43 /* GUIDs */
  44
  45 extern const FAudioGUID FAudioFX_CLSID_AudioVolumeMeter;
  46 extern const FAudioGUID FAudioFX_CLSID_AudioReverb;
  47
  48 /* Structures */
  49
  50 #pragma pack(push, 1)
  51
  52 typedef struct FAudioFXVolumeMeterLevels
  53 {
  54         float *pPeakLevels;
  55         float *pRMSLevels;
  56         uint32_t ChannelCount;
  57 } FAudioFXVolumeMeterLevels;
  58
  59 typedef struct FAudioFXReverbParameters
  60 {
  61         float WetDryMix;
  62         uint32_t ReflectionsDelay;
  63         uint8_t ReverbDelay;
  64         uint8_t RearDelay;
  65         uint8_t PositionLeft;
  66         uint8_t PositionRight;
  67         uint8_t PositionMatrixLeft;
  68         uint8_t PositionMatrixRight;
  69         uint8_t EarlyDiffusion;
  70         uint8_t LateDiffusion;
  71         uint8_t LowEQGain;
  72         uint8_t LowEQCutoff;
  73         uint8_t HighEQGain;
  74         uint8_t HighEQCutoff;
  75         float RoomFilterFreq;
  76         float RoomFilterMain;
  77         float RoomFilterHF;
  78         float ReflectionsGain;
  79         float ReverbGain;
  80         float DecayTime;
  81         float Density;
  82         float RoomSize;
  83 } FAudioFXReverbParameters;
  84
  85 typedef struct FAudioFXReverbParameters9
  86 {
  87         float WetDryMix;
  88         uint32_t ReflectionsDelay;
  89         uint8_t ReverbDelay;
  90         uint8_t RearDelay;
  91         uint8_t SideDelay;
  92         uint8_t PositionLeft;
  93         uint8_t PositionRight;
  94         uint8_t PositionMatrixLeft;
  95         uint8_t PositionMatrixRight;
  96         uint8_t EarlyDiffusion;
  97         uint8_t LateDiffusion;
  98         uint8_t LowEQGain;
  99         uint8_t LowEQCutoff;
 100         uint8_t HighEQGain;
 101         uint8_t HighEQCutoff;
 102         float RoomFilterFreq;
 103         float RoomFilterMain;
 104         float RoomFilterHF;
 105         float ReflectionsGain;
 106         float ReverbGain;
 107         float DecayTime;
 108         float Density;
 109         float RoomSize;
 110 } FAudioFXReverbParameters9;
 111
 112 typedef struct FAudioFXReverbI3DL2Parameters
 113 {
 114         float WetDryMix;
 115         int32_t Room;
 116         int32_t RoomHF;
 117         float RoomRolloffFactor;
 118         float DecayTime;
 119         float DecayHFRatio;
 120         int32_t Reflections;
 121         float ReflectionsDelay;
 122         int32_t Reverb;
 123         float ReverbDelay;
 124         float Diffusion;
 125         float Density;
 126         float HFReference;
 127 } FAudioFXReverbI3DL2Parameters;
 128
 129 #pragma pack(pop)
 130
 131 /* Constants */
 132
 133 #define FAUDIOFX_DEBUG 1
 134
 135 #define FAUDIOFX_REVERB_MIN_FRAMERATE 20000
 136 #define FAUDIOFX_REVERB_MAX_FRAMERATE 48000
 137
 138 #define FAUDIOFX_REVERB_MIN_WET_DRY_MIX         0.0f
 139 #define FAUDIOFX_REVERB_MIN_REFLECTIONS_DELAY   0
 140 #define FAUDIOFX_REVERB_MIN_REVERB_DELAY        0
 141 #define FAUDIOFX_REVERB_MIN_REAR_DELAY          0
 142 #define FAUDIOFX_REVERB_MIN_7POINT1_SIDE_DELAY  0
 143 #define FAUDIOFX_REVERB_MIN_7POINT1_REAR_DELAY  0
 144 #define FAUDIOFX_REVERB_MIN_POSITION            0
 145 #define FAUDIOFX_REVERB_MIN_DIFFUSION           0
 146 #define FAUDIOFX_REVERB_MIN_LOW_EQ_GAIN         0
 147 #define FAUDIOFX_REVERB_MIN_LOW_EQ_CUTOFF       0
 148 #define FAUDIOFX_REVERB_MIN_HIGH_EQ_GAIN        0
 149 #define FAUDIOFX_REVERB_MIN_HIGH_EQ_CUTOFF      0
 150 #define FAUDIOFX_REVERB_MIN_ROOM_FILTER_FREQ    20.0f
 151 #define FAUDIOFX_REVERB_MIN_ROOM_FILTER_MAIN    -100.0f
 152 #define FAUDIOFX_REVERB_MIN_ROOM_FILTER_HF      -100.0f
 153 #define FAUDIOFX_REVERB_MIN_REFLECTIONS_GAIN    -100.0f
 154 #define FAUDIOFX_REVERB_MIN_REVERB_GAIN         -100.0f
 155 #define FAUDIOFX_REVERB_MIN_DECAY_TIME          0.1f
 156 #define FAUDIOFX_REVERB_MIN_DENSITY             0.0f
 157 #define FAUDIOFX_REVERB_MIN_ROOM_SIZE           0.0f
 158
 159 #define FAUDIOFX_REVERB_MAX_WET_DRY_MIX         100.0f
 160 #define FAUDIOFX_REVERB_MAX_REFLECTIONS_DELAY   300
 161 #define FAUDIOFX_REVERB_MAX_REVERB_DELAY        85
 162 #define FAUDIOFX_REVERB_MAX_REAR_DELAY          5
 163 #define FAUDIOFX_REVERB_MAX_7POINT1_SIDE_DELAY  5
 164 #define FAUDIOFX_REVERB_MAX_7POINT1_REAR_DELAY  20
 165 #define FAUDIOFX_REVERB_MAX_POSITION            30
 166 #define FAUDIOFX_REVERB_MAX_DIFFUSION           15
 167 #define FAUDIOFX_REVERB_MAX_LOW_EQ_GAIN         12
 168 #define FAUDIOFX_REVERB_MAX_LOW_EQ_CUTOFF       9
 169 #define FAUDIOFX_REVERB_MAX_HIGH_EQ_GAIN        8
 170 #define FAUDIOFX_REVERB_MAX_HIGH_EQ_CUTOFF      14
 171 #define FAUDIOFX_REVERB_MAX_ROOM_FILTER_FREQ    20000.0f
 172 #define FAUDIOFX_REVERB_MAX_ROOM_FILTER_MAIN    0.0f
 173 #define FAUDIOFX_REVERB_MAX_ROOM_FILTER_HF      0.0f
 174 #define FAUDIOFX_REVERB_MAX_REFLECTIONS_GAIN    20.0f
 175 #define FAUDIOFX_REVERB_MAX_REVERB_GAIN         20.0f
 176 #define FAUDIOFX_REVERB_MAX_DENSITY             100.0f
 177 #define FAUDIOFX_REVERB_MAX_ROOM_SIZE           100.0f
 178
 179 #define FAUDIOFX_REVERB_DEFAULT_WET_DRY_MIX             100.0f
 180 #define FAUDIOFX_REVERB_DEFAULT_REFLECTIONS_DELAY       5
 181 #define FAUDIOFX_REVERB_DEFAULT_REVERB_DELAY            5
 182 #define FAUDIOFX_REVERB_DEFAULT_REAR_DELAY              5
 183 #define FAUDIOFX_REVERB_DEFAULT_7POINT1_SIDE_DELAY      5
 184 #define FAUDIOFX_REVERB_DEFAULT_7POINT1_REAR_DELAY      20
 185 #define FAUDIOFX_REVERB_DEFAULT_POSITION                6
 186 #define FAUDIOFX_REVERB_DEFAULT_POSITION_MATRIX         27
 187 #define FAUDIOFX_REVERB_DEFAULT_EARLY_DIFFUSION         8
 188 #define FAUDIOFX_REVERB_DEFAULT_LATE_DIFFUSION          8
 189 #define FAUDIOFX_REVERB_DEFAULT_LOW_EQ_GAIN             8
 190 #define FAUDIOFX_REVERB_DEFAULT_LOW_EQ_CUTOFF           4
 191 #define FAUDIOFX_REVERB_DEFAULT_HIGH_EQ_GAIN            8
 192 #define FAUDIOFX_REVERB_DEFAULT_HIGH_EQ_CUTOFF          4
 193 #define FAUDIOFX_REVERB_DEFAULT_ROOM_FILTER_FREQ        5000.0f
 194 #define FAUDIOFX_REVERB_DEFAULT_ROOM_FILTER_MAIN        0.0f
 195 #define FAUDIOFX_REVERB_DEFAULT_ROOM_FILTER_HF          0.0f
 196 #define FAUDIOFX_REVERB_DEFAULT_REFLECTIONS_GAIN        0.0f
 197 #define FAUDIOFX_REVERB_DEFAULT_REVERB_GAIN             0.0f
 198 #define FAUDIOFX_REVERB_DEFAULT_DECAY_TIME              1.0f
 199 #define FAUDIOFX_REVERB_DEFAULT_DENSITY                 100.0f
 200 #define FAUDIOFX_REVERB_DEFAULT_ROOM_SIZE               100.0f
 201
 202 #define FAUDIOFX_I3DL2_PRESET_DEFAULT \
 203         {100,-10000,    0,0.0f, 1.00f,0.50f,-10000,0.020f,-10000,0.040f,100.0f,100.0f,5000.0f}
 204 #define FAUDIOFX_I3DL2_PRESET_GENERIC \
 205         {100, -1000, -100,0.0f, 1.49f,0.83f, -2602,0.007f,   200,0.011f,100.0f,100.0f,5000.0f}
 206 #define FAUDIOFX_I3DL2_PRESET_PADDEDCELL \
 207         {100, -1000,-6000,0.0f, 0.17f,0.10f, -1204,0.001f,   207,0.002f,100.0f,100.0f,5000.0f}
 208 #define FAUDIOFX_I3DL2_PRESET_ROOM \
 209         {100, -1000, -454,0.0f, 0.40f,0.83f, -1646,0.002f,    53,0.003f,100.0f,100.0f,5000.0f}
 210 #define FAUDIOFX_I3DL2_PRESET_BATHROOM \
 211         {100, -1000,-1200,0.0f, 1.49f,0.54f,  -370,0.007f,  1030,0.011f,100.0f, 60.0f,5000.0f}
 212 #define FAUDIOFX_I3DL2_PRESET_LIVINGROOM \
 213         {100, -1000,-6000,0.0f, 0.50f,0.10f, -1376,0.003f, -1104,0.004f,100.0f,100.0f,5000.0f}
 214 #define FAUDIOFX_I3DL2_PRESET_STONEROOM \
 215         {100, -1000, -300,0.0f, 2.31f,0.64f,  -711,0.012f,    83,0.017f,100.0f,100.0f,5000.0f}
 216 #define FAUDIOFX_I3DL2_PRESET_AUDITORIUM \
 217         {100, -1000, -476,0.0f, 4.32f,0.59f,  -789,0.020f,  -289,0.030f,100.0f,100.0f,5000.0f}
 218 #define FAUDIOFX_I3DL2_PRESET_CONCERTHALL \
 219         {100, -1000, -500,0.0f, 3.92f,0.70f, -1230,0.020f,    -2,0.029f,100.0f,100.0f,5000.0f}
 220 #define FAUDIOFX_I3DL2_PRESET_CAVE \
 221         {100, -1000,    0,0.0f, 2.91f,1.30f,  -602,0.015f,  -302,0.022f,100.0f,100.0f,5000.0f}
 222 #define FAUDIOFX_I3DL2_PRESET_ARENA \
 223         {100, -1000, -698,0.0f, 7.24f,0.33f, -1166,0.020f,    16,0.030f,100.0f,100.0f,5000.0f}
 224 #define FAUDIOFX_I3DL2_PRESET_HANGAR \
 225         {100, -1000,-1000,0.0f,10.05f,0.23f,  -602,0.020f,   198,0.030f,100.0f,100.0f,5000.0f}
 226 #define FAUDIOFX_I3DL2_PRESET_CARPETEDHALLWAY \
 227         {100, -1000,-4000,0.0f, 0.30f,0.10f, -1831,0.002f, -1630,0.030f,100.0f,100.0f,5000.0f}
 228 #define FAUDIOFX_I3DL2_PRESET_HALLWAY \
 229         {100, -1000, -300,0.0f, 1.49f,0.59f, -1219,0.007f,   441,0.011f,100.0f,100.0f,5000.0f}
 230 #define FAUDIOFX_I3DL2_PRESET_STONECORRIDOR \
 231         {100, -1000, -237,0.0f, 2.70f,0.79f, -1214,0.013f,   395,0.020f,100.0f,100.0f,5000.0f}
 232 #define FAUDIOFX_I3DL2_PRESET_ALLEY \
 233         {100, -1000, -270,0.0f, 1.49f,0.86f, -1204,0.007f,    -4,0.011f,100.0f,100.0f,5000.0f}
 234 #define FAUDIOFX_I3DL2_PRESET_FOREST \
 235         {100, -1000,-3300,0.0f, 1.49f,0.54f, -2560,0.162f,  -613,0.088f, 79.0f,100.0f,5000.0f}
 236 #define FAUDIOFX_I3DL2_PRESET_CITY \
 237         {100, -1000, -800,0.0f, 1.49f,0.67f, -2273,0.007f, -2217,0.011f, 50.0f,100.0f,5000.0f}
 238 #define FAUDIOFX_I3DL2_PRESET_MOUNTAINS \
 239         {100, -1000,-2500,0.0f, 1.49f,0.21f, -2780,0.300f, -2014,0.100f, 27.0f,100.0f,5000.0f}
 240 #define FAUDIOFX_I3DL2_PRESET_QUARRY \
 241         {100, -1000,-1000,0.0f, 1.49f,0.83f,-10000,0.061f,   500,0.025f,100.0f,100.0f,5000.0f}
 242 #define FAUDIOFX_I3DL2_PRESET_PLAIN \
 243         {100, -1000,-2000,0.0f, 1.49f,0.50f, -2466,0.179f, -2514,0.100f, 21.0f,100.0f,5000.0f}
 244 #define FAUDIOFX_I3DL2_PRESET_PARKINGLOT \
 245         {100, -1000,    0,0.0f, 1.65f,1.50f, -1363,0.008f, -1153,0.012f,100.0f,100.0f,5000.0f}
 246 #define FAUDIOFX_I3DL2_PRESET_SEWERPIPE \
 247         {100, -1000,-1000,0.0f, 2.81f,0.14f,   429,0.014f,   648,0.021f, 80.0f, 60.0f,5000.0f}
 248 #define FAUDIOFX_I3DL2_PRESET_UNDERWATER \
 249         {100, -1000,-4000,0.0f, 1.49f,0.10f,  -449,0.007f,  1700,0.011f,100.0f,100.0f,5000.0f}
 250 #define FAUDIOFX_I3DL2_PRESET_SMALLROOM \
 251         {100, -1000, -600,0.0f, 1.10f,0.83f,  -400,0.005f,   500,0.010f,100.0f,100.0f,5000.0f}
 252 #define FAUDIOFX_I3DL2_PRESET_MEDIUMROOM \
 253         {100, -1000, -600,0.0f, 1.30f,0.83f, -1000,0.010f,  -200,0.020f,100.0f,100.0f,5000.0f}
 254 #define FAUDIOFX_I3DL2_PRESET_LARGEROOM \
 255         {100, -1000, -600,0.0f, 1.50f,0.83f, -1600,0.020f, -1000,0.040f,100.0f,100.0f,5000.0f}
 256 #define FAUDIOFX_I3DL2_PRESET_MEDIUMHALL \
 257         {100, -1000, -600,0.0f, 1.80f,0.70f, -1300,0.015f,  -800,0.030f,100.0f,100.0f,5000.0f}
 258 #define FAUDIOFX_I3DL2_PRESET_LARGEHALL \
 259         {100, -1000, -600,0.0f, 1.80f,0.70f, -2000,0.030f, -1400,0.060f,100.0f,100.0f,5000.0f}
 260 #define FAUDIOFX_I3DL2_PRESET_PLATE \
 261         {100, -1000, -200,0.0f, 1.30f,0.90f,     0,0.002f,     0,0.010f,100.0f, 75.0f,5000.0f}
 262
 263 /* Functions */
 264
 265 FAUDIOAPI uint32_t FAudioCreateVolumeMeter(FAPO** ppApo, uint32_t Flags);
 266 FAUDIOAPI uint32_t FAudioCreateReverb(FAPO** ppApo, uint32_t Flags);
 267 FAUDIOAPI uint32_t FAudioCreateReverb9(FAPO** ppApo, uint32_t Flags);
 268
 269 /* See "extensions/CustomAllocatorEXT.txt" for more information. */
 270 FAUDIOAPI uint32_t FAudioCreateVolumeMeterWithCustomAllocatorEXT(
 271         FAPO** ppApo,
 272         uint32_t Flags,
 273         FAudioMallocFunc customMalloc,
 274         FAudioFreeFunc customFree,
 275         FAudioReallocFunc customRealloc
 276 );
 277 FAUDIOAPI uint32_t FAudioCreateReverbWithCustomAllocatorEXT(
 278         FAPO** ppApo,
 279         uint32_t Flags,
 280         FAudioMallocFunc customMalloc,
 281         FAudioFreeFunc customFree,
 282         FAudioReallocFunc customRealloc
 283 );
 284 FAUDIOAPI uint32_t FAudioCreateReverb9WithCustomAllocatorEXT(
 285         FAPO** ppApo,
 286         uint32_t Flags,
 287         FAudioMallocFunc customMalloc,
 288         FAudioFreeFunc customFree,
 289         FAudioReallocFunc customRealloc
 290 );
 291
 292 FAUDIOAPI void ReverbConvertI3DL2ToNative(
 293         const FAudioFXReverbI3DL2Parameters *pI3DL2,
 294         FAudioFXReverbParameters *pNative
 295 );
 296 FAUDIOAPI void ReverbConvertI3DL2ToNative9(
 297         const FAudioFXReverbI3DL2Parameters *pI3DL2,
 298         FAudioFXReverbParameters9 *pNative,
 299         int32_t sevenDotOneReverb
 300 );
 301
 302 #ifdef __cplusplus
 303 }
 304 #endif /* __cplusplus */
 305
 306 #endif /* FAUDIOFX_H */
 307
 308 /* vim: set noexpandtab shiftwidth=8 tabstop=8: */