Audio 1.36 Reference Guide

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

#include <stdint.h>

#include "OVR_Audio_DynamicRoom.h"
#include "OVR_Audio_Propagation.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_AudioMemoryAllocFailure                     = 2018,
   ovrError_AudioUnsupportedFeature                     = 2019, 
   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 36
#define OVR_AUDIO_PATCH_VERSION 0

#ifdef _WIN32
#define OVRA_EXPORT __declspec( dllexport )
#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, 

#if defined(OVR_INTERNAL_CODE)
    ovrAudioSourceFlag_Stereo                      = 0x0200, 
#endif

  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_COUNT
} ovrAudioEnable;


typedefenum
{
    ovrAudioReflectionModel_StaticShoeBox       = 0,    
    ovrAudioReflectionModel_DynamicRoomModeling = 1,    
    ovrAudioReflectionModel_PropagationSystem   = 2,    
    ovrAudioReflectionModel_Automatic           = 3,    


    ovrAudioReflectionModel_COUNT
} ovrAudioReflectionModel;

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, 
    ovrAudioAmbisonicSpeakerLayout_Octahedron          =  1, 
    ovrAudioAmbisonicSpeakerLayout_Cube                =  2, 
    ovrAudioAmbisonicSpeakerLayout_Icosahedron         =  3, 
    ovrAudioAmbisonicSpeakerLayout_Dodecahedron        =  4, 
    ovrAudioAmbisonicSpeakerLayout_20PointElectron     =  5, 
    ovrAudioAmbisonicSpeakerLayout_SphericalHarmonics  = -1, 
    ovrAudioAmbisonicSpeakerLayout_Mono                = -2  
} 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 ovrResult ovrAudio_InitializeContext( ovrAudioContext Context, 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_SetUnitScale( ovrAudioContext Context, float UnitScale );

OVRA_EXPORT ovrResult ovrAudio_GetUnitScale(ovrAudioContext Context, float *UnitScale);

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_SetAudioReverbSendLevel(ovrAudioContext Context,
int Sound,
float Level);

OVRA_EXPORT ovrResult ovrAudio_GetAudioReverbSendLevel(ovrAudioContext Context,
int Sound,
float* pLevel);

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_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_GetAudioSourceOverallGain( ovrAudioContext Context,
int Sound,
float* Gain );

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_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_SetSharedReverbWetLevel(ovrAudioContext Context, 
constfloat Level);

OVRA_EXPORT ovrResult ovrAudio_GetSharedReverbWetLevel(ovrAudioContext Context,
float *Level);

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);

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_SetReflectionModel(ovrAudioContext Context, ovrAudioReflectionModel Model);


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);

// Propagation is only supported on Windows
// All methods below will return ovrError_AudioUnsupportedFeature on other platforms

/***********************************************************************************/
/* Geometry API */
OVRA_EXPORT ovrResult ovrAudio_SetPropagationQuality(ovrAudioContext context, float quality);
OVRA_EXPORT ovrResult ovrAudio_SetPropagationThreadAffinity(ovrAudioContext context, uint64_t cpuMask);
OVRA_EXPORT ovrResult ovrAudio_CreateAudioGeometry(ovrAudioContext context, ovrAudioGeometry* geometry);
OVRA_EXPORT ovrResult ovrAudio_DestroyAudioGeometry(ovrAudioGeometry geometry);

OVRA_EXPORT ovrResult ovrAudio_AudioGeometryUploadMesh(ovrAudioGeometry geometry, const ovrAudioMesh* mesh/*, const ovrAudioMeshSimplificationParameters* simplification*/);
OVRA_EXPORT ovrResult ovrAudio_AudioGeometryUploadMeshArrays(ovrAudioGeometry geometry,
constvoid* vertices, size_t verticesByteOffset, size_t vertexCount, size_t vertexStride, ovrAudioScalarType vertexType,
constvoid* indices, size_t indicesByteOffset, size_t indexCount, ovrAudioScalarType indexType,
const ovrAudioMeshGroup* groups, size_t groupCount/*, const ovrAudioMeshSimplificationParameters* simplification*/);

OVRA_EXPORT ovrResult ovrAudio_AudioGeometrySetTransform(ovrAudioGeometry geometry, constfloat matrix4x4[16]);
OVRA_EXPORT ovrResult ovrAudio_AudioGeometryGetTransform(const ovrAudioGeometry geometry, float matrix4x4[16]);

OVRA_EXPORT ovrResult ovrAudio_AudioGeometryWriteMeshFile(const ovrAudioGeometry geometry, constchar *filePath);
OVRA_EXPORT ovrResult ovrAudio_AudioGeometryReadMeshFile(ovrAudioGeometry geometry, constchar *filePath);

OVRA_EXPORT ovrResult ovrAudio_AudioGeometryWriteMeshFileObj(const ovrAudioGeometry geometry, constchar *filePath);

/***********************************************************************************/
/* Material API */

OVRA_EXPORT ovrResult ovrAudio_CreateAudioMaterial(ovrAudioContext context, ovrAudioMaterial* material);
OVRA_EXPORT ovrResult ovrAudio_DestroyAudioMaterial(ovrAudioMaterial material);

OVRA_EXPORT ovrResult ovrAudio_AudioMaterialSetFrequency(ovrAudioMaterial material, ovrAudioMaterialProperty property, float frequency, float value);
OVRA_EXPORT ovrResult ovrAudio_AudioMaterialGetFrequency(const ovrAudioMaterial material, ovrAudioMaterialProperty property, float frequency, float* value);
OVRA_EXPORT ovrResult ovrAudio_AudioMaterialReset(ovrAudioMaterial material, ovrAudioMaterialProperty property);

/***********************************************************************************/
/* Serialization API */

OVRA_EXPORT ovrResult ovrAudio_AudioGeometryWriteMeshData(const ovrAudioGeometry geometry, const ovrAudioSerializer* serializer);
OVRA_EXPORT ovrResult ovrAudio_AudioGeometryReadMeshData(ovrAudioGeometry geometry, const ovrAudioSerializer* serializer);

#ifdef __cplusplus
}
#endif

#endif // OVR_Audio_h