eax4.h

   1 /*                      DirectSound
   2  *
   3  * Copyright 2018 Chris Robinson
   4  *
   5  * This library is free software; you can redistribute it and/or
   6  * modify it under the terms of the GNU Lesser General Public
   7  * License as published by the Free Software Foundation; either
   8  * version 2.1 of the License, or (at your option) any later version.
   9  *
  10  * This library is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13  * Lesser General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU Lesser General Public
  16  * License along with this library; if not, write to the Free Software
  17  * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
  18  */
  19
  20 #ifndef EAX4_H
  21 #define EAX4_H
  22
  23 #ifndef EAXVECTOR_DEFINED
  24 #define EAXVECTOR_DEFINED
  25 typedef struct _EAXVECTOR {
  26     float x, y, z;
  27 } EAXVECTOR;
  28 #endif
  29
  30 /* EAX 4.0 seems to support 4 FXSlots (auxiliary effect slots), while each
  31  * buffer/source supports 2 Active FXSlots (auxiliary sends).
  32  */
  33 #define EAX_MAX_FXSLOTS 4
  34 #define EAX_MAX_ACTIVE_FXSLOTS 2
  35
  36 /* Used by EAXFXSLOT_LOADEFFECT, EAXCONTEXT_PRIMARYFXSLOTID, and EAXSOURCE_ACTIVEFXSLOTID */
  37 DEFINE_GUID(EAX_NULL_GUID, 0x00000000, 0x0000, 0x0000, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00);
  38
  39
  40 DEFINE_GUID(EAXPROPERTYID_EAX40_Context, 0x1d4870ad, 0xdef, 0x43c0, 0xa4, 0xc, 0x52, 0x36, 0x32, 0x29, 0x63, 0x42);
  41 typedef enum {
  42     EAXCONTEXT_NONE = 0,
  43     EAXCONTEXT_ALLPARAMETERS,
  44     EAXCONTEXT_PRIMARYFXSLOTID,
  45     EAXCONTEXT_DISTANCEFACTOR,
  46     EAXCONTEXT_AIRABSORPTIONHF,
  47     EAXCONTEXT_HFREFERENCE,
  48     EAXCONTEXT_LASTERROR /* query only, auto-reset? */
  49 } EAXCONTEXT_PROPERTY;
  50
  51 #define EAXCONTEXT_PARAMETER_IMMEDIATE 0x00000000
  52 #define EAXCONTEXT_PARAMETER_DEFERRED  0x80000000
  53 #define EAXCONTEXT_PARAMETER_COMMITDEFERREDSETTINGS (EAXCONTEXT_NONE | EAXCONTEXT_PARAMETER_IMMEDIATE)
  54
  55 /* EAXCONTEXT_ALLPARAMETERS */
  56 typedef struct _EAXCONTEXTPROPERTIES {
  57     GUID  guidPrimaryFXSlotID;
  58     /* TODO: Does this affect EAX properties only (e.g. initial reverb decay,
  59      * air absorption)? Or is it an alias for DS3D's setting?
  60      */
  61     float flDistanceFactor;
  62     /* NOTE: Not directly supported by OpenAL, but can be applied to each
  63      * source's air absorption factor as:
  64      * air_absorption_factor *= flAirAbsorptionHF / -5.0f
  65      */
  66     float flAirAbsorptionHF;
  67     /* NOTE: Not supported by OpenAL. */
  68     float flHFReference;
  69 } EAXCONTEXTPROPERTIES, *LPEAXCONTEXTPROPERTIES;
  70
  71 /* EAXCONTEXT_LASTERROR */
  72 #define EAX_OK                   0
  73 #define EAXERR_INVALID_OPERATION (-1)
  74 #define EAXERR_INVALID_VALUE     (-2)
  75 #define EAXERR_NO_EFFECT_LOADED  (-3)
  76 #define EAXERR_UNKNOWN_EFFECT    (-4)
  77
  78
  79 /* Also used by EAXSOURCE_ACTIVEFXSLOTID and EAXCONTEXT_PRIMARYFXSLOTID */
  80 DEFINE_GUID(EAXPROPERTYID_EAX40_FXSlot0, 0xc4d79f1e, 0xf1ac, 0x436b, 0xa8, 0x1d, 0xa7, 0x38, 0xe7, 0x04, 0x54, 0x69);
  81 DEFINE_GUID(EAXPROPERTYID_EAX40_FXSlot1, 0x08c00e96, 0x74be, 0x4491, 0x93, 0xaa, 0xe8, 0xad, 0x35, 0xa4, 0x91, 0x17);
  82 DEFINE_GUID(EAXPROPERTYID_EAX40_FXSlot2, 0x1d433b88, 0xf0f6, 0x4637, 0x91, 0x9f, 0x60, 0xe7, 0xe0, 0x6b, 0x5e, 0xdd);
  83 DEFINE_GUID(EAXPROPERTYID_EAX40_FXSlot3, 0xefff08ea, 0xc7d8, 0x44ab, 0x93, 0xad, 0x6d, 0xbd, 0x5f, 0x91, 0x00, 0x64);
  84 typedef enum {
  85     EAXFXSLOT_PARAMETER = 0, /* 0x00...0x40 reserved for effect parameters */
  86     EAXFXSLOT_NONE = 0x10000,
  87     EAXFXSLOT_ALLPARAMETERS,
  88     EAXFXSLOT_LOADEFFECT,
  89     EAXFXSLOT_VOLUME,
  90     EAXFXSLOT_LOCK,
  91     EAXFXSLOT_FLAGS
  92 } EAXFXSLOT_PROPERTY;
  93
  94 #define EAXFXSLOT_PARAMETER_IMMEDIATE 0x00000000
  95 #define EAXFXSLOT_PARAMETER_DEFERRED  0x80000000
  96 #define EAXFXSLOT_PARAMETER_COMMITDEFERREDSETTINGS (EAXFXSLOT_NONE | EAXFXSLOT_PARAMETER_IMMEDIATE)
  97
  98 /* EAXFXSLOT_ALLPARAMETERS */
  99 typedef struct _EAXFXSLOTPROPERTIES {
 100     GUID  guidLoadEffect;
 101     long  lVolume;
 102     long  lLock;
 103     DWORD dwFlags;
 104 } EAXFXSLOTPROPERTIES, *LPEAXFXSLOTPROPERTIES;
 105
 106 /* EAXFXSLOT_LOADEFFECT */
 107 DEFINE_GUID(EAX_REVERB_EFFECT,           0x0cf95c8f, 0xa3cc, 0x4849, 0xb0, 0xb6, 0x83, 0x2e, 0xcc, 0x18, 0x22, 0xdf);
 108 DEFINE_GUID(EAX_AGCCOMPRESSOR_EFFECT,    0xbfb7a01e, 0x7825, 0x4039, 0x92, 0x7f, 0x03, 0xaa, 0xbd, 0xa0, 0xc5, 0x60);
 109 DEFINE_GUID(EAX_AUTOWAH_EFFECT,          0xec3130c0, 0xac7a, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 110 DEFINE_GUID(EAX_CHORUS_EFFECT,           0xde6d6fe0, 0xac79, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 111 DEFINE_GUID(EAX_DISTORTION_EFFECT,       0x975a4ce0, 0xac7e, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 112 DEFINE_GUID(EAX_ECHO_EFFECT,             0x0e9f1bc0, 0xac82, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 113 DEFINE_GUID(EAX_EQUALIZER_EFFECT,        0x65f94ce0, 0x9793, 0x11d3, 0x93, 0x9d, 0x00, 0xc0, 0xf0, 0x2d, 0xd6, 0xf0);
 114 DEFINE_GUID(EAX_FLANGER_EFFECT,          0xa70007c0, 0x07d2, 0x11d3, 0x9b, 0x1e, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 115 DEFINE_GUID(EAX_FREQUENCYSHIFTER_EFFECT, 0xdc3e1880, 0x9212, 0x11d3, 0x93, 0x9d, 0x00, 0xc0, 0xf0, 0x2d, 0xd6, 0xf0);
 116 DEFINE_GUID(EAX_VOCALMORPHER_EFFECT,     0xe41cf10c, 0x3383, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 117 DEFINE_GUID(EAX_PITCHSHIFTER_EFFECT,     0xe7905100, 0xafb2, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 118 DEFINE_GUID(EAX_RINGMODULATOR_EFFECT,    0x0b89fe60, 0xafb5, 0x11d2, 0x88, 0xdd, 0x00, 0xa0, 0x24, 0xd1, 0x3c, 0xe1);
 119
 120 /* EAXFXSLOT_LOCK */
 121 enum {
 122     EAXFXSLOT_UNLOCKED = 0,
 123     EAXFXSLOT_LOCKED   = 1
 124 };
 125
 126 /* EAXFXSLOT_FLAGS */
 127 #define EAXFXSLOTFLAGS_ENVIRONMENT   0x00000001
 128
 129
 130 DEFINE_GUID(EAXPROPERTYID_EAX40_Source, 0x1b86b823, 0x22df, 0x4eae, 0x8b, 0x3c, 0x12, 0x78, 0xce, 0x54, 0x42, 0x27);
 131 typedef enum {
 132     EAXSOURCE_NONE,
 133     EAXSOURCE_ALLPARAMETERS,
 134     EAXSOURCE_OBSTRUCTIONPARAMETERS,
 135     EAXSOURCE_OCCLUSIONPARAMETERS,
 136     EAXSOURCE_EXCLUSIONPARAMETERS,
 137     EAXSOURCE_DIRECT,
 138     EAXSOURCE_DIRECTHF,
 139     EAXSOURCE_ROOM,
 140     EAXSOURCE_ROOMHF,
 141     EAXSOURCE_OBSTRUCTION,
 142     EAXSOURCE_OBSTRUCTIONLFRATIO,
 143     EAXSOURCE_OCCLUSION,
 144     EAXSOURCE_OCCLUSIONLFRATIO,
 145     EAXSOURCE_OCCLUSIONROOMRATIO,
 146     EAXSOURCE_OCCLUSIONDIRECTRATIO,
 147     EAXSOURCE_EXCLUSION,
 148     EAXSOURCE_EXCLUSIONLFRATIO,
 149     EAXSOURCE_OUTSIDEVOLUMEHF,
 150     EAXSOURCE_DOPPLERFACTOR,
 151     EAXSOURCE_ROLLOFFFACTOR,
 152     EAXSOURCE_ROOMROLLOFFFACTOR,
 153     EAXSOURCE_AIRABSORPTIONFACTOR,
 154     EAXSOURCE_FLAGS,
 155     EAXSOURCE_SENDPARAMETERS,
 156     EAXSOURCE_ALLSENDPARAMETERS,
 157     EAXSOURCE_OCCLUSIONSENDPARAMETERS,
 158     EAXSOURCE_EXCLUSIONSENDPARAMETERS,
 159     EAXSOURCE_ACTIVEFXSLOTID,
 160 } EAXSOURCE_PROPERTY;
 161
 162 #define EAXSOURCE_PARAMETER_IMMEDIATE 0x00000000
 163 #define EAXSOURCE_PARAMETER_DEFERRED  0x80000000
 164 #define EAXSOURCE_PARAMETER_COMMITDEFERREDSETTINGS (EAXSOURCE_NONE | EAXSOURCE_PARAMETER_IMMEDIATE)
 165
 166 /* EAXSOURCE_ALLPARAMETERS */
 167 typedef struct _EAXSOURCEPROPERTIES {
 168     long  lDirect;
 169     long  lDirectHF;
 170     /* TODO: Do these act as offets for individual sends? Or overwrite them all
 171      * when set? Or only apply to sends using the context's primary FXSlot?
 172      */
 173     long  lRoom;
 174     long  lRoomHF;
 175     long  lObstruction;
 176     float flObstructionLFRatio;
 177     long  lOcclusion;
 178     float flOcclusionLFRatio;
 179     float flOcclusionRoomRatio;
 180     float flOcclusionDirectRatio;
 181     long  lExclusion;
 182     float flExclusionLFRatio;
 183     long  lOutsideVolumeHF;
 184     float flDopplerFactor;
 185     /* NOTE: Added, not multiplied, with the listener's value. */
 186     float flRolloffFactor;
 187     float flRoomRolloffFactor;
 188     float flAirAbsorptionFactor;
 189     DWORD dwFlags;
 190 } EAXSOURCEPROPERTIES, *LPEAXSOURCEPROPERTIES;
 191
 192 /* EAXSOURCE_OBSTRUCTIONPARAMETERS */
 193 #ifndef EAX_OBSTRUCTIONPROPERTIES_DEFINED
 194 #define EAX_OBSTRUCTIONPROPERTIES_DEFINED
 195 typedef struct _EAXOBSTRUCTIONPROPERTIES {
 196     long  lObstruction;
 197     float flObstructionLFRatio;
 198 } EAXOBSTRUCTIONPROPERTIES, *LPEAXOBSTRUCTIONPROPERTIES;
 199 #endif
 200
 201 /* EAXSOURCE_OCCLUSIONPARAMETERS */
 202 #ifndef EAX_OCCLUSIONPROPERTIES_DEFINED
 203 #define EAX_OCCLUSIONPROPERTIES_DEFINED
 204 typedef struct _EAXOCCLUSIONPROPERTIES {
 205     long  lOcclusion;
 206     float flOcclusionLFRatio;
 207     float flOcclusionRoomRatio;
 208     float flOcclusionDirectRatio;
 209 } EAXOCCLUSIONPROPERTIES, *LPEAXOCCLUSIONPROPERTIES;
 210 #endif
 211
 212 /* EAXSOURCE_EXCLUSIONPARAMETERS */
 213 #ifndef EAX_EXCLUSIONPROPERTIES_DEFINED
 214 #define EAX_EXCLUSIONPROPERTIES_DEFINED
 215 typedef struct _EAXEXCLUSIONPROPERTIES {
 216     long  lExclusion;
 217     float flExclusionLFRatio;
 218 } EAXEXCLUSIONPROPERTIES, *LPEAXEXCLUSIONPROPERTIES;
 219 #endif
 220
 221 /* EAXSOURCE_FLAGS */
 222 #define EAXSOURCEFLAGS_DIRECTHFAUTO 0x00000001
 223 #define EAXSOURCEFLAGS_ROOMAUTO     0x00000002
 224 #define EAXSOURCEFLAGS_ROOMHFAUTO   0x00000004
 225
 226 /* EAXSOURCE_SENDPARAMETERS */
 227 typedef struct _EAXSOURCESENDPROPERTIES {
 228     /* TODO: Check if sources maintain send parameters for each potential
 229      * effect slot, or if this needs to match a currently active effect slot to
 230      * match a send (and gets reset when the active effect slot GUID changes).
 231      * Also need to check how EAX_PrimaryFXSlotID is treated (as itself, or if
 232      * it looks at the context's primary FXSlot).
 233      */
 234     GUID guidReceivingFXSlotID;
 235     long lSend;
 236     long lSendHF;
 237 } EAXSOURCESENDPROPERTIES, *LPEAXSOURCESENDPROPERTIES;
 238
 239 /* EAXSOURCE_ALLSENDPARAMETERS */
 240 typedef struct _EAXSOURCEALLSENDPROPERTIES {
 241     GUID  guidReceivingFXSlotID;
 242     long  lSend;
 243     long  lSendHF;
 244     long  lOcclusion;
 245     float flOcclusionLFRatio;
 246     float flOcclusionRoomRatio;
 247     float flOcclusionDirectRatio;
 248     long  lExclusion;
 249     float flExclusionLFRatio;
 250 } EAXSOURCEALLSENDPROPERTIES, *LPEAXSOURCEALLSENDPROPERTIES;
 251
 252 /* EAXSOURCE_OCCLUSIONSENDPARAMETERS */
 253 typedef struct _EAXSOURCEOCCLUSIONSENDPROPERTIES {
 254     GUID  guidReceivingFXSlotID;
 255     long  lOcclusion;
 256     float flOcclusionLFRatio;
 257     float flOcclusionRoomRatio;
 258     float flOcclusionDirectRatio;
 259 } EAXSOURCEOCCLUSIONSENDPROPERTIES, *LPEAXSOURCEOCCLUSIONSENDPROPERTIES;
 260
 261 /* EAXSOURCE_EXCLUSIONSENDPARAMETERS */
 262 typedef struct _EAXSOURCEEXCLUSIONSENDPROPERTIES {
 263     GUID  guidReceivingFXSlotID;
 264     long  lExclusion;
 265     float flExclusionLFRatio;
 266 } EAXSOURCEEXCLUSIONSENDPROPERTIES, *LPEAXSOURCEEXCLUSIONSENDPROPERTIES;
 267
 268 /* EAXSOURCE_ACTIVEFXSLOTID */
 269 typedef struct _EAXACTIVEFXSLOTS {
 270     GUID guidActiveFXSlots[EAX_MAX_ACTIVE_FXSLOTS];
 271 } EAXACTIVEFXSLOTS, *LPEAXACTIVEFXSLOTS;
 272
 273 DEFINE_GUID(EAX_PrimaryFXSlotID, 0xf317866d, 0x924c, 0x450c, 0x86, 0x1b, 0xe6, 0xda, 0xa2, 0x5e, 0x7c, 0x20);
 274
 275
 276 /* EAX_REVERB_EFFECT properties. */
 277 typedef enum {
 278     EAXREVERB_NONE,
 279     EAXREVERB_ALLPARAMETERS,
 280     EAXREVERB_ENVIRONMENT,
 281     EAXREVERB_ENVIRONMENTSIZE,
 282     EAXREVERB_ENVIRONMENTDIFFUSION,
 283     EAXREVERB_ROOM,
 284     EAXREVERB_ROOMHF,
 285     EAXREVERB_ROOMLF,
 286     EAXREVERB_DECAYTIME,
 287     EAXREVERB_DECAYHFRATIO,
 288     EAXREVERB_DECAYLFRATIO,
 289     EAXREVERB_REFLECTIONS,
 290     EAXREVERB_REFLECTIONSDELAY,
 291     EAXREVERB_REFLECTIONSPAN,
 292     EAXREVERB_REVERB,
 293     EAXREVERB_REVERBDELAY,
 294     EAXREVERB_REVERBPAN,
 295     EAXREVERB_ECHOTIME,
 296     EAXREVERB_ECHODEPTH,
 297     EAXREVERB_MODULATIONTIME,
 298     EAXREVERB_MODULATIONDEPTH,
 299     EAXREVERB_AIRABSORPTIONHF,
 300     EAXREVERB_HFREFERENCE,
 301     EAXREVERB_LFREFERENCE,
 302     EAXREVERB_ROOMROLLOFFFACTOR,
 303     EAXREVERB_FLAGS
 304 } EAXREVERB_PROPERTY;
 305
 306 #define EAXREVERB_IMMEDIATE 0x00000000
 307 #define EAXREVERB_DEFERRED  0x80000000
 308 #define EAXREVERB_COMMITDEFERREDSETTINGS (EAXREVERB_NONE | EAXREVERB_IMMEDIATE)
 309
 310 /* EAXREVERB_ALLPARAMETERS */
 311 typedef struct _EAXREVERBPROPERTIES {
 312     DWORD dwEnvironment;
 313     float flEnvironmentSize;
 314     float flEnvironmentDiffusion;
 315     long  lRoom;
 316     long  lRoomHF;
 317     long  lRoomLF;
 318     float flDecayTime;
 319     float flDecayHFRatio;
 320     float flDecayLFRatio;
 321     long  lReflections;
 322     float flReflectionsDelay;
 323     EAXVECTOR vReflectionsPan;
 324     long  lReverb;
 325     float flReverbDelay;
 326     EAXVECTOR vReverbPan;
 327     float flEchoTime;
 328     float flEchoDepth;
 329     float flModulationTime;
 330     float flModulationDepth;
 331     float flAirAbsorptionHF;
 332     float flHFReference;
 333     float flLFReference;
 334     float flRoomRolloffFactor;
 335     DWORD dwFlags;
 336 } EAXREVERBPROPERTIES, *LPEAXREVERBPROPERTIES;
 337
 338 /* EAXREVERB_FLAGS */
 339 /* These flags determine what properties are modified when the environment size
 340  * is changed.
 341  */
 342 #define EAXREVERBFLAGS_DECAYTIMESCALE        0x00000001
 343 #define EAXREVERBFLAGS_REFLECTIONSSCALE      0x00000002
 344 #define EAXREVERBFLAGS_REFLECTIONSDELAYSCALE 0x00000004
 345 #define EAXREVERBFLAGS_REVERBSCALE           0x00000008
 346 #define EAXREVERBFLAGS_REVERBDELAYSCALE      0x00000010
 347 #define EAXREVERBFLAGS_ECHOTIMESCALE         0x00000040
 348 #define EAXREVERBFLAGS_MODULATIONTIMESCALE   0x00000080
 349 /* This flag limits the high frequency decay according to air absorption */
 350 #define EAXREVERBFLAGS_DECAYHFLIMIT          0x00000020
 351
 352
 353 /* EAX_CHORUS_EFFECT properties */
 354 typedef enum {
 355     EAXCHORUS_NONE,
 356     EAXCHORUS_ALLPARAMETERS,
 357     EAXCHORUS_WAVEFORM,
 358     EAXCHORUS_PHASE,
 359     EAXCHORUS_RATE,
 360     EAXCHORUS_DEPTH,
 361     EAXCHORUS_FEEDBACK,
 362     EAXCHORUS_DELAY
 363 } EAXCHORUS_PROPERTY;
 364
 365 #define EAXCHORUS_IMMEDIATE 0x00000000
 366 #define EAXCHORUS_DEFERRED  0x80000000
 367 #define EAXCHORUS_COMMITDEFERREDSETTINGS (EAXCHORUS_NONE | EAXCHORUS_IMMEDIATE)
 368
 369 /* EAXCHORUS_ALLPARAMETERS */
 370 typedef struct _EAXCHORUSPROPERTIES {
 371     DWORD dwWaveform;
 372     long  lPhase;
 373     float flRate;
 374     float flDepth;
 375     float flFeedback;
 376     float flDelay;
 377 } EAXCHORUSPROPERTIES, *LPEAXCHORUSPROPERTIES;
 378
 379 /* EAXCHORUS_WAVEFORM */
 380 enum {
 381     EAX_CHORUS_SINUSOID,
 382     EAX_CHORUS_TRIANGLE
 383 };
 384
 385
 386 /* TODO: Other effects. */
 387
 388
 389 #endif /* EAX4_H */