Audio 1.24 Reference Guide

/********************************************************************************/
#ifndef OVR_Audio_h
#define OVR_Audio_h

#include "OVR_Audio_DynamicRoom.h"
#include <stdint.h>

#ifdef __cplusplus
extern"C" {
#endif

#ifndef OVR_RESULT_DEFINED
#define OVR_RESULT_DEFINED
typedef int32_t ovrResult;
#endif

#ifndef OVR_SUCCESS_DEFINED
#define OVR_SUCCESS_DEFINED
#define ovrSuccess 0
#endif

typedefenum
{
   ovrError_AudioUnknown                                = 2000, 
   ovrError_AudioInvalidParam                           = 2001, 
   ovrError_AudioBadSampleRate                          = 2002, 
   ovrError_AudioMissingDLL                             = 2003, 
   ovrError_AudioBadAlignment                           = 2004, 
   ovrError_AudioUninitialized                          = 2005, 
   ovrError_AudioHRTFInitFailure                        = 2006, 
   ovrError_AudioBadVersion                             = 2007, 
   ovrError_AudioSymbolNotFound                         = 2008, 
   ovrError_SharedReverbDisabled                        = 2009, 
   ovrError_AudioNoAvailableAmbisonicInstance           = 2017,
   ovrError_AudioInternalEnd                            = 2099, 
} ovrAudioError;

#ifndef OVR_CAPI_h
typedefstruct ovrPosef_ ovrPosef;
typedefstruct ovrPoseStatef_ ovrPoseStatef;
#endif

#define OVR_AUDIO_MAJOR_VERSION 1
#define OVR_AUDIO_MINOR_VERSION 18
#define OVR_AUDIO_PATCH_VERSION 0

#ifdef _WIN32
#ifdef OVR_AUDIO_DLL
#define OVRA_EXPORT __declspec( dllexport )
#else
#define OVRA_EXPORT 
#endif
#define FUNC_NAME __FUNCTION__
#elif defined(__ANDROID__)
#define OVRA_EXPORT __attribute__((visibility("default")))
#define FUNC_NAME __func__
#elif defined __APPLE__ 
#define OVRA_EXPORT 
#define FUNC_NAME __func__
#elif defined __linux__
#define OVRA_EXPORT __attribute__((visibility("default")))
#define FUNC_NAME __func__
#else
#error not implemented
#endif

typedefenum
{
  ovrAudioSourceFlag_None                          = 0x0000,

  ovrAudioSourceFlag_WideBand_HINT                 = 0x0010, 
  ovrAudioSourceFlag_NarrowBand_HINT               = 0x0020, 
  ovrAudioSourceFlag_BassCompensation_DEPRECATED   = 0x0040, 
  ovrAudioSourceFlag_DirectTimeOfArrival           = 0x0080, 

  ovrAudioSourceFlag_ReflectionsDisabled           = 0x0100, 

  ovrAudioSourceFlag_DisableResampling_RESERVED    = 0x8000, 

} ovrAudioSourceFlag;

typedefenum
{
  ovrAudioSourceAttenuationMode_None          = 0,      
  ovrAudioSourceAttenuationMode_Fixed         = 1,      
  ovrAudioSourceAttenuationMode_InverseSquare = 2,      

  ovrAudioSourceAttenuationMode_COUNT

} ovrAudioSourceAttenuationMode;

typedefenum
{
    ovrAudioEnable_None                     = 0,   
    ovrAudioEnable_SimpleRoomModeling       = 2,   
    ovrAudioEnable_LateReverberation        = 3,   
    ovrAudioEnable_RandomizeReverb          = 4,   
    ovrAudioEnable_PerSourceReverb          = 5,   

    ovrAudioEnable_COUNT
} ovrAudioEnable;

typedefenum
{

  ovrAudioHRTFInterpolationMethod_Nearest,
  ovrAudioHRTFInterpolationMethod_SimpleTimeDomain,
  ovrAudioHRTFInterpolationMethod_MinPhaseTimeDomain,
  ovrAudioHRTFInterpolationMethod_PhaseTruncation,
  ovrAudioHRTFInterpolationMethod_PhaseLerp,

  ovrAudioHRTFInterpolationMethod_COUNT

} ovrAudioHRTFInterpolationMethod;

typedefenum
{
  ovrAudioSpatializationStatus_None      = 0x00,  
  ovrAudioSpatializationStatus_Finished  = 0x01,  
  ovrAudioSpatializationStatus_Working   = 0x02,  

} ovrAudioSpatializationStatus;

typedefenum
{
    ovrAudioHeadphones_None           = -1,  
    ovrAudioHeadphones_Rift           = 0,   
    ovrAudioHeadphones_Rift_INTERNAL0 = 1,   
    ovrAudioHeadphones_Rift_INTERNAL1 = 2,   
    ovrAudioHeadphones_Rift_INTERNAL2 = 3,   
    ovrAudioHeadphones_Rift_INTERNAL3 = 4,   
    ovrAudioHeadphones_Rift_INTERNAL4 = 5,   

    ovrAudioHeadphones_Custom         = 10,  

    ovrAudioHeadphones_COUNT
} ovrAudioHeadphones;

typedefenum
{
    ovrAudioPerformanceCounter_Spatialization            = 0,  
    ovrAudioPerformanceCounter_SharedReverb              = 1,  
    ovrAudioPerformanceCounter_HeadphoneCorrection       = 2,  

    ovrAudioPerformanceCounter_COUNT
} ovrAudioPerformanceCounter;


typedefenum
{
    ovrAudioAmbisonicFormat_FuMa, 
    ovrAudioAmbisonicFormat_AmbiX 
} ovrAudioAmbisonicFormat;


typedefenum
{
    ovrAudioAmbisonicSpeakerLayout_FrontOnly           =  0, // A single virtual speaker in-front of listener
    ovrAudioAmbisonicSpeakerLayout_Octahedron          =  1, // 6 virtual speakers
    ovrAudioAmbisonicSpeakerLayout_Cube                =  2, // 8 virtual speakers
    ovrAudioAmbisonicSpeakerLayout_Icosahedron         =  3, // 12 virtual speakers
    ovrAudioAmbisonicSpeakerLayout_Dodecahedron        =  4, // 20 virtual speakers
    ovrAudioAmbisonicSpeakerLayout_20PointElectron     =  5, // 20 virtual speakers more evenly distributed over sphere
    ovrAudioAmbisonicSpeakerLayout_SphericalHarmonics  = -1, // (default) Uses a spherical harmonic representation of HRTF instead of virtual speakers
    ovrAudioAmbisonicSpeakerLayout_Mono                = -2  // Plays the W (omni) channel through left and right with no spatialization
} ovrAudioAmbisonicSpeakerLayout;


typedefstruct ovrAudioSource_   ovrAudioSource;
typedefstruct ovrAudioContext_ *ovrAudioContext;
typedefstruct ovrAudioAmbisonicStream_ *ovrAudioAmbisonicStream;
typedefvoid *ovrAudioSpectrumAnalyzer;

inline ovrResult ovrAudio_Initialize(void) { return ovrSuccess; }

inlinevoid ovrAudio_Shutdown(void) {}

OVRA_EXPORT constchar *ovrAudio_GetVersion( int *Major, int *Minor, int *Patch );

OVRA_EXPORT float * ovrAudio_AllocSamples( int NumSamples );

OVRA_EXPORT void ovrAudio_FreeSamples( float *Samples );

OVRA_EXPORT ovrResult ovrAudio_GetTransformFromPose( const ovrPosef *Pose, 
float *Vx, float *Vy, float *Vz,
float *Pos );

typedefstruct _ovrAudioContextConfig
{
  uint32_t   acc_Size;              
  uint32_t   acc_MaxNumSources;     
  uint32_t   acc_SampleRate;        
  uint32_t   acc_BufferLength;      
} ovrAudioContextConfiguration;

OVRA_EXPORT ovrResult ovrAudio_CreateContext( ovrAudioContext *pContext,
const ovrAudioContextConfiguration *pConfig );

OVRA_EXPORT void ovrAudio_DestroyContext( ovrAudioContext Context );

OVRA_EXPORT ovrResult ovrAudio_Enable( ovrAudioContext Context, 
                                  ovrAudioEnable What, 
int Enable );

OVRA_EXPORT ovrResult ovrAudio_IsEnabled( ovrAudioContext Context, 
                                          ovrAudioEnable What, 
int* pEnabled );

OVRA_EXPORT ovrResult ovrAudio_SetHRTFInterpolationMethod( ovrAudioContext Context, 
                                                             ovrAudioHRTFInterpolationMethod InterpolationMethod );

OVRA_EXPORT ovrResult ovrAudio_GetHRTFInterpolationMethod( ovrAudioContext Context, 
                                                            ovrAudioHRTFInterpolationMethod* pInterpolationMethod );

typedefstruct _ovrAudioBoxRoomParameters
{
   uint32_t       brp_Size;                              
float          brp_ReflectLeft, brp_ReflectRight;     
float          brp_ReflectUp, brp_ReflectDown;        
float          brp_ReflectBehind, brp_ReflectFront;   
float          brp_Width, brp_Height, brp_Depth;      
} ovrAudioBoxRoomParameters;

OVRA_EXPORT ovrResult ovrAudio_SetSimpleBoxRoomParameters( ovrAudioContext Context, 
const ovrAudioBoxRoomParameters *Parameters );

OVRA_EXPORT ovrResult ovrAudio_GetSimpleBoxRoomParameters( ovrAudioContext Context, 
                                                            ovrAudioBoxRoomParameters *Parameters );


OVRA_EXPORT ovrResult ovrAudio_SetListenerVectors(  ovrAudioContext Context,
float PositionX, float PositionY, float PositionZ,
float ForwardX, float ForwardY, float ForwardZ,
float UpX, float UpY, float UpZ );

OVRA_EXPORT ovrResult ovrAudio_GetListenerVectors(  ovrAudioContext Context,
float* pPositionX, float* pPositionY, float* pPositionZ,
float* pForwardX, float* pForwardY, float* pForwardZ,
float* pUpX, float* pUpY, float* pUpZ );

OVRA_EXPORT ovrResult ovrAudio_SetListenerPoseStatef( ovrAudioContext Context, 
const ovrPoseStatef *PoseState );

// Note: there is no ovrAudio_GetListenerPoseStatef() since the pose data is not cached internally.
// Use ovrAudio_GetListenerVectors() instead to get the listener's position and orientation info.

OVRA_EXPORT ovrResult ovrAudio_ResetAudioSource( ovrAudioContext Context, int Sound );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourcePos( ovrAudioContext Context, 
int Sound, 
float X, float Y, float Z );

OVRA_EXPORT ovrResult ovrAudio_GetAudioSourcePos( ovrAudioContext Context, 
int Sound, 
float* pX, float* pY, float* pZ );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourceRange( ovrAudioContext Context, 
int Sound, 
float RangeMin, float RangeMax );

OVRA_EXPORT ovrResult ovrAudio_GetAudioSourceRange( ovrAudioContext Context, 
int Sound, 
float* pRangeMin, float* pRangeMax );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourceRadius( ovrAudioContext Context, 
int Sound, 
float Radius );

OVRA_EXPORT ovrResult ovrAudio_GetAudioSourceRadius( ovrAudioContext Context, 
int Sound, 
float* pRadius );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourceFlags( ovrAudioContext Context, 
int Sound, 
                                                    uint32_t Flags );

OVRA_EXPORT ovrResult ovrAudio_GetAudioSourceFlags( ovrAudioContext Context, 
int Sound, 
                                                    uint32_t* pFlags );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourceDirectionRESERVED( ovrAudioContext Context, 
int Sound, 
float VX, float VY, float VZ, 
float Angle );

OVRA_EXPORT ovrResult ovrAudio_SetAudioSourceAttenuationMode( ovrAudioContext Context, 
int Sound, 
                                                              ovrAudioSourceAttenuationMode Mode, 
float FixedScale );

OVRA_EXPORT ovrResult ovrAudio_GetAudioSourceAttenuationMode( ovrAudioContext Context, 
int Sound, 
                                                              ovrAudioSourceAttenuationMode* pMode, 
float* pFixedScale );

OVRA_EXPORT ovrResult ovrAudio_SpatializeMonoSourceInterleaved( ovrAudioContext Context, 
int Sound, 
                                                          uint32_t *OutStatus, 
float *Dst, constfloat *Src );

OVRA_EXPORT ovrResult ovrAudio_SpatializeMonoSourceLR( ovrAudioContext Context, 
int Sound, 
                                                 uint32_t *OutStatus, 
float *DstLeft, float *DstRight, 
constfloat *Src );

OVRA_EXPORT ovrResult ovrAudio_SetHeadphoneModel( ovrAudioContext Context, 
                                            ovrAudioHeadphones Model,
constfloat *ImpulseResponse, int NumSamples );

OVRA_EXPORT ovrResult ovrAudio_GetHeadphoneModel( ovrAudioContext Context, 
                                            ovrAudioHeadphones* pModel,
constfloat** pImpulseResponse, int* pNumSamples );

OVRA_EXPORT ovrResult ovrAudio_ApplyHeadphoneCorrection( ovrAudioContext Context, 
float *OutLeft, float *OutRight,
constfloat *InLeft, constfloat *InRight,
int NumSamples );

OVRA_EXPORT ovrResult ovrAudio_MixInSharedReverbLR( ovrAudioContext Context, 
                                                    uint32_t *OutStatus, 
float *DstLeft, float *DstRight );


OVRA_EXPORT ovrResult ovrAudio_MixInSharedReverbInterleaved( ovrAudioContext Context,
                                                             uint32_t* OutStatus, 
float* DstInterleaved );


OVRA_EXPORT ovrResult ovrAudio_SetSharedReverbRange( ovrAudioContext Context,
float RangeMin, float RangeMax );

OVRA_EXPORT ovrResult ovrAudio_GetSharedReverbRange( ovrAudioContext Context,
float* pRangeMin, float* pRangeMax );

OVRA_EXPORT ovrResult ovrAudio_SetHeadRadius( ovrAudioContext Context, 
float HeadRadius );

OVRA_EXPORT ovrResult ovrAudio_GetHeadRadius( ovrAudioContext Context,
float *HeadRadius);

typedefstruct _ovrAudioPrivateAPI ovrAudioPrivateAPI;

OVRA_EXPORT ovrResult ovrAudio_GetPrivateAPI( ovrAudioContext Context, ovrAudioPrivateAPI *Dst );

OVRA_EXPORT ovrResult ovrAudio_GetPerformanceCounter( ovrAudioContext Context, 
                                                      ovrAudioPerformanceCounter Counter, 
                                                      int64_t *Count, 
double *TimeMicroSeconds );

OVRA_EXPORT ovrResult ovrAudio_ResetPerformanceCounter( ovrAudioContext Context, 
                                                        ovrAudioPerformanceCounter Counter );

OVRA_EXPORT ovrResult ovrAudio_ProcessQuadBinaural(constfloat *ForwardLR, constfloat *RightLR, constfloat *BackLR, constfloat *LeftLR,
float LookDirectionX, float LookDirectionY, float LookDirectionZ, 
int NumSamples, float *Dst);

OVRA_EXPORT ovrResult ovrAudio_CreateAmbisonicStream(   ovrAudioContext Context,
int SampleRate, 
int AudioBufferLength, 
                                                        ovrAudioAmbisonicFormat format, 
int ambisonicOrder, 
                                                        ovrAudioAmbisonicStream* pAmbisonicStream);

OVRA_EXPORT ovrResult ovrAudio_ResetAmbisonicStream(ovrAudioAmbisonicStream AmbisonicStream);

OVRA_EXPORT ovrResult ovrAudio_DestroyAmbisonicStream(ovrAudioAmbisonicStream AmbisonicStream);

OVRA_EXPORT ovrResult ovrAudio_SetAmbisonicSpeakerLayout(ovrAudioAmbisonicStream AmbisonicStream, ovrAudioAmbisonicSpeakerLayout Layout);

OVRA_EXPORT ovrResult ovrAudio_GetAmbisonicSpeakerLayout(ovrAudioAmbisonicStream AmbisonicStream, ovrAudioAmbisonicSpeakerLayout* Layout);

OVRA_EXPORT ovrResult ovrAudio_MonoToAmbisonic(constfloat* InMono, float DirectionX, float DirectionY, float DirectionZ, ovrAudioAmbisonicFormat Format, int AmbisonicOrder, float* OutAmbisonic, int NumSamples);

OVRA_EXPORT ovrResult ovrAudio_RenderAmbisonicSpeakerFeed(constfloat* InAmbisonics, float DirectionX, float DirectionY, float DirectionZ, ovrAudioAmbisonicFormat Format, int AmbisonicOrder, float* SpeakerFeed, int NumSamples);

OVRA_EXPORT ovrResult ovrAudio_ProcessAmbisonicStreamInterleaved(ovrAudioContext Context, ovrAudioAmbisonicStream AmbisonicStream, constfloat *Src, float *Dst, int NumSamples);

OVRA_EXPORT ovrResult ovrAudio_SetAmbisonicOrientation(ovrAudioAmbisonicStream AmbisonicStream,
float LookDirectionX, float LookDirectionY, float LookDirectionZ,
float UpDirectionX, float UpDirectionY, float UpDirectionZ);

OVRA_EXPORT ovrResult ovrAudio_GetAmbisonicOrientation(ovrAudioAmbisonicStream AmbisonicStream,
float* pLookDirectionX, float* pLookDirectionY, float* pLookDirectionZ,
float* pUpDirectionX, float* pUpDirectionY, float* pUpDirectionZ);


OVRA_EXPORT ovrResult ovrAudio_SetProfilerEnabled(ovrAudioContext Context, int Enabled);
OVRA_EXPORT ovrResult ovrAudio_SetProfilerPort(ovrAudioContext, int Port);

OVRA_EXPORT ovrResult ovrAudio_CreateSpectrumAnalyzer(int ChannelCount, int WindowLength, int Overlap, ovrAudioSpectrumAnalyzer* pSpectrumAnalyzer);
OVRA_EXPORT ovrResult ovrAudio_DestroySpectrumAnalyzer(ovrAudioSpectrumAnalyzer SpectrumAnalyzer);
OVRA_EXPORT ovrResult ovrAudio_ResetSpectrumAnalyzer(ovrAudioSpectrumAnalyzer SpectrumAnalyzer);
OVRA_EXPORT ovrResult ovrAudio_SpectrumAnalyzerProcessBufferInterleaved(ovrAudioSpectrumAnalyzer SpectrumAnalyzer, constfloat* Buffer, int LengthFrames);
OVRA_EXPORT ovrResult ovrAudio_SpectrumAnalyzerGetSpectrumInterleaved(ovrAudioSpectrumAnalyzer SpectrumAnalyzer, float* Spectrum);
OVRA_EXPORT ovrResult ovrAudio_SpectrumAnalyzerCalculateAmbisonicCoefficients(ovrAudioSpectrumAnalyzer SpectrumAnalyzer, float DirectionX, float DirectionY, float DirectionZ, float* Coefs);
OVRA_EXPORT ovrResult ovrAudio_SpectrumAnalyzerGetSpectrumAmbisonic(ovrAudioSpectrumAnalyzer SpectrumAnalyzer, constfloat* Coefs, float* Spectrum);

OVRA_EXPORT ovrResult ovrAudio_AssignRaycastCallback(ovrAudioContext Context, OVRA_RAYCAST_CALLBACK Callback, void* pctx);

OVRA_EXPORT ovrResult ovrAudio_SetDynamicRoomRaysPerSecond(ovrAudioContext Context, int RaysPerSecond);



OVRA_EXPORT ovrResult ovrAudio_SetDynamicRoomInterpSpeed(ovrAudioContext Context, float InterpSpeed);

OVRA_EXPORT ovrResult ovrAudio_SetDynamicRoomMaxWallDistance(ovrAudioContext Context, float MaxWallDistance);

OVRA_EXPORT ovrResult ovrAudio_SetDynamicRoomRaysRayCacheSize(ovrAudioContext Context, int RayCacheSize);

OVRA_EXPORT ovrResult ovrAudio_UpdateRoomModel(ovrAudioContext Context, float WetLevel);

OVRA_EXPORT ovrResult ovrAudio_GetRoomDimensions(ovrAudioContext Context, float RoomDimensions[], float ReflectionsCoefs[], ovrAudioVector3f* Position);

OVRA_EXPORT ovrResult ovrAudio_GetRaycastHits(ovrAudioContext Context, ovrAudioVector3f Points[], ovrAudioVector3f Normals[], int Length);


#ifdef __cplusplus
}
#endif

#endif // OVR_Audio_h