orxSoundSystem.h

Go to the documentation of this file.

/* Orx - Portable Game Engine
 *
 * Copyright (c) 2008-2022 Orx-Project
 *
 * This software is provided 'as-is', without any express or implied
 * warranty. In no event will the authors be held liable for any damages
 * arising from the use of this software.
 *
 * Permission is granted to anyone to use this software for any purpose,
 * including commercial applications, and to alter it and redistribute it
 * freely, subject to the following restrictions:
 *
 *    1. The origin of this software must not be misrepresented; you must not
 *    claim that you wrote the original software. If you use this software
 *    in a product, an acknowledgment in the product documentation would be
 *    appreciated but is not required.
 *
 *    2. Altered source versions must be plainly marked as such, and must not be
 *    misrepresented as being the original software.
 *
 *    3. This notice may not be removed or altered from any source
 *    distribution.
 */

#ifndef _orxSOUNDSYSTEM_H_
#define _orxSOUNDSYSTEM_H_

#include "orxInclude.h"
#include "math/orxVector.h"
#include "plugin/orxPluginCore.h"


/***************************************************************************
 * Structure declaration                                                   *
 ***************************************************************************/

typedef struct __orxSOUNDSYSTEM_SOUND_t   orxSOUNDSYSTEM_SOUND;
typedef struct __orxSOUNDSYSTEM_SAMPLE_t  orxSOUNDSYSTEM_SAMPLE;

typedef enum __orxSOUNDSYSTEM_STATUS_t
{
  orxSOUNDSYSTEM_STATUS_PLAY = 0,
  orxSOUNDSYSTEM_STATUS_PAUSE,
  orxSOUNDSYSTEM_STATUS_STOP,

  orxSOUNDSYSTEM_STATUS_NUMBER,

  orxSOUNDSYSTEM_STATUS_NONE = orxENUM_NONE

} orxSOUNDSYSTEM_STATUS;

typedef enum __orxSOUND_FILTER_TYPE_t
{
  orxSOUND_FILTER_TYPE_BIQUAD = 0,
  orxSOUND_FILTER_TYPE_LOW_PASS,
  orxSOUND_FILTER_TYPE_HIGH_PASS,
  orxSOUND_FILTER_TYPE_BAND_PASS,
  orxSOUND_FILTER_TYPE_LOW_SHELF,
  orxSOUND_FILTER_TYPE_HIGH_SHELF,
  orxSOUND_FILTER_TYPE_NOTCH,
  orxSOUND_FILTER_TYPE_PEAKING,
  orxSOUND_FILTER_TYPE_DELAY,
  orxSOUND_FILTER_TYPE_CUSTOM,

  orxSOUND_FILTER_TYPE_NUMBER,

  orxSOUND_FILTER_TYPE_NONE = orxENUM_NONE

} orxSOUND_FILTER_TYPE;

typedef void (orxFASTCALL *orxSOUND_FILTER_FUNCTION)(orxFLOAT *_afSampleListOut, const orxFLOAT *_afSampleListIn, orxU32 _u32SampleCount, orxU32 _u32ChannelCount, orxU32 _u32SampleRate, orxSTRINGID _stNameID, void *_pContext);

typedef struct __orxSOUND_FILTER_DATA_t
{
  orxSOUND_FILTER_TYPE          eType;
  orxSTRINGID                   stNameID;

  union
  {
    struct
    {
      orxFLOAT                  fA0;
      orxFLOAT                  fA1;
      orxFLOAT                  fA2;
      orxFLOAT                  fB0;
      orxFLOAT                  fB1;
      orxFLOAT                  fB2;

    } stBiquad;

    struct
    {
      orxFLOAT                  fFrequency;
      orxU32                    u32Order;

    } stLowPass;

    struct
    {
      orxFLOAT                  fFrequency;
      orxU32                    u32Order;

    } stHighPass;

    struct
    {
      orxFLOAT                  fFrequency;
      orxU32                    u32Order;

    } stBandPass;

    struct
    {
      orxFLOAT                  fFrequency;
      orxFLOAT                  fQ;
      orxFLOAT                  fGain;

    } stLowShelf;

    struct
    {
      orxFLOAT                  fFrequency;
      orxFLOAT                  fQ;
      orxFLOAT                  fGain;

    } stHighShelf;

    struct
    {
      orxFLOAT                  fFrequency;
      orxFLOAT                  fQ;

    } stNotch;

    struct
    {
      orxFLOAT                  fFrequency;
      orxFLOAT                  fQ;
      orxFLOAT                  fGain;

    } stPeaking;

    struct
    {
      orxFLOAT                  fDelay;
      orxFLOAT                  fDecay;

    } stDelay;

    struct
    {
      orxSOUND_FILTER_FUNCTION  pfnCallback;
      void                     *pContext;

    } stCustom;

  };

} orxSOUND_FILTER_DATA;

#define orxSOUNDSYSTEM_KZ_CONFIG_SECTION              "SoundSystem"
#define orxSOUNDSYSTEM_KZ_CONFIG_RATIO                "DimensionRatio"
#define orxSOUNDSYSTEM_KZ_CONFIG_MUTE_IN_BACKGROUND   "MuteInBackground"
#define orxSOUNDSYSTEM_KZ_CONFIG_LISTENERS            "Listeners"


/***************************************************************************
 * Functions directly implemented by orx core
 ***************************************************************************/

extern orxDLLAPI void orxFASTCALL                     orxSoundSystem_Setup();


/***************************************************************************
 * Functions extended by plugins
 ***************************************************************************/

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Init();

extern orxDLLAPI void orxFASTCALL                     orxSoundSystem_Exit();

extern orxDLLAPI orxSOUNDSYSTEM_SAMPLE *orxFASTCALL   orxSoundSystem_CreateSample(orxU32 _u32ChannelNumber, orxU32 _u32FrameNumber, orxU32 _u32SampleRate);

extern orxDLLAPI orxSOUNDSYSTEM_SAMPLE *orxFASTCALL   orxSoundSystem_LoadSample(const orxSTRING _zFilename);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_DeleteSample(orxSOUNDSYSTEM_SAMPLE *_pstSample);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_GetSampleInfo(const orxSOUNDSYSTEM_SAMPLE *_pstSample, orxU32 *_pu32ChannelNumber, orxU32 *_pu32FrameNumber, orxU32 *_pu32SampleRate);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetSampleData(orxSOUNDSYSTEM_SAMPLE *_pstSample, const orxFLOAT *_afData, orxU32 _u32SampleNumber);

extern orxDLLAPI orxSOUNDSYSTEM_SOUND *orxFASTCALL    orxSoundSystem_CreateFromSample(orxHANDLE _hUserData, const orxSOUNDSYSTEM_SAMPLE *_pstSample);

extern orxDLLAPI orxSOUNDSYSTEM_SOUND *orxFASTCALL    orxSoundSystem_CreateStream(orxHANDLE _hUserData, orxU32 _u32ChannelNumber, orxU32 _u32SampleRate);

extern orxDLLAPI orxSOUNDSYSTEM_SOUND *orxFASTCALL    orxSoundSystem_LoadStream(orxHANDLE _hUserData, const orxSTRING _zFilename);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Delete(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Play(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Pause(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Stop(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_AddFilter(orxSOUNDSYSTEM_SOUND *_pstSound, const orxSOUND_FILTER_DATA *_pstFilterData, orxBOOL _bUseCustomParam);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_RemoveLastFilter(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_RemoveAllFilters(orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxHANDLE orxFASTCALL                orxSoundSystem_CreateBus(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_DeleteBus(orxHANDLE _hBus);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetBus(orxSOUNDSYSTEM_SOUND *_pstSound, orxHANDLE _hBus);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetBusParent(orxHANDLE _hBus, orxHANDLE _hParentBus);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_AddBusFilter(orxHANDLE _hBus, const orxSOUND_FILTER_DATA *_pstFilterData, orxBOOL _bUseCustomParam);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_RemoveLastBusFilter(orxHANDLE _hBus);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_RemoveAllBusFilters(orxHANDLE _hBus);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_StartRecording(const orxCHAR *_zName, orxBOOL _bWriteToFile, orxU32 _u32SampleRate, orxU32 _u32ChannelNumber);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_StopRecording();

extern orxDLLAPI orxBOOL orxFASTCALL                  orxSoundSystem_HasRecordingSupport();

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetVolume(orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT _fVolume);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetPitch(orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT _fPitch);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetTime(orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT _fTime);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetPosition(orxSOUNDSYSTEM_SOUND *_pstSound, const orxVECTOR *_pvPosition);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetSpatialization(orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT _fMinDistance, orxFLOAT _fMaxDistance, orxFLOAT _fMinGain, orxFLOAT _fMaxGain, orxFLOAT _fRollOff);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetPanning(orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT _fPanning, orxBOOL _bMix);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_Loop(orxSOUNDSYSTEM_SOUND *_pstSound, orxBOOL _bLoop);

extern orxDLLAPI orxFLOAT orxFASTCALL                 orxSoundSystem_GetVolume(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxFLOAT orxFASTCALL                 orxSoundSystem_GetPitch(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxFLOAT orxFASTCALL                 orxSoundSystem_GetTime(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxVECTOR *orxFASTCALL               orxSoundSystem_GetPosition(const orxSOUNDSYSTEM_SOUND *_pstSound, orxVECTOR *_pvPosition);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_GetSpatialization(const orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT *_pfMinDistance, orxFLOAT *_pfMaxDistance, orxFLOAT *_pfMinGain, orxFLOAT *_pfMaxGain, orxFLOAT *_pfRollOff);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_GetPanning(const orxSOUNDSYSTEM_SOUND *_pstSound, orxFLOAT *_pfPanning, orxBOOL *_pbMix);

extern orxDLLAPI orxBOOL orxFASTCALL                  orxSoundSystem_IsLooping(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxFLOAT orxFASTCALL                 orxSoundSystem_GetDuration(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSOUNDSYSTEM_STATUS orxFASTCALL    orxSoundSystem_GetStatus(const orxSOUNDSYSTEM_SOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetGlobalVolume(orxFLOAT _fGlobalVolume);

extern orxDLLAPI orxFLOAT orxFASTCALL                 orxSoundSystem_GetGlobalVolume();

extern orxDLLAPI orxU32 orxFASTCALL                   orxSoundSystem_GetListenerCount();

extern orxDLLAPI void orxFASTCALL                     orxSoundSystem_EnableListener(orxU32 _u32ListenerIndex, orxBOOL _bEnable);

extern orxDLLAPI orxBOOL orxFASTCALL                  orxSoundSystem_IsListenerEnabled(orxU32 _u32ListenerIndex);

extern orxDLLAPI orxSTATUS orxFASTCALL                orxSoundSystem_SetListenerPosition(orxU32 _u32Index, const orxVECTOR *_pvPosition);

extern orxDLLAPI orxVECTOR *orxFASTCALL               orxSoundSystem_GetListenerPosition(orxU32 _u32Index, orxVECTOR *_pvPosition);

#endif /* _orxSOUNDSYSTEM_H_ */