orxSound.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 _orxSOUND_H_
#define _orxSOUND_H_


#include "orxInclude.h"
#include "math/orxVector.h"
#include "sound/orxSoundSystem.h"


#define orxSOUND_KZ_RESOURCE_GROUP            "Sound"
#define orxSOUND_KZ_LOCALE_GROUP              "Sound"

#define orxSOUND_KZ_MASTER_BUS                "master"


typedef enum __orxSOUND_STATUS_t
{
  orxSOUND_STATUS_PLAY = 0,
  orxSOUND_STATUS_PAUSE,
  orxSOUND_STATUS_STOP,

  orxSOUND_STATUS_NUMBER,

  orxSOUND_STATUS_NONE = orxENUM_NONE

} orxSOUND_STATUS;


typedef struct __orxSOUND_t                   orxSOUND;
typedef struct __orxSOUND_SAMPLE_t            orxSOUND_SAMPLE;


typedef enum __orxSOUND_EVENT_t
{
  orxSOUND_EVENT_START = 0,                   
  orxSOUND_EVENT_STOP,                        
  orxSOUND_EVENT_ADD,                         
  orxSOUND_EVENT_REMOVE,                      
  orxSOUND_EVENT_PACKET,                      
  orxSOUND_EVENT_RECORDING_START,             
  orxSOUND_EVENT_RECORDING_STOP,              
  orxSOUND_EVENT_RECORDING_PACKET,            
  orxSOUND_EVENT_SET_FILTER_PARAM,            
  orxSOUND_EVENT_NUMBER,

  orxSOUND_EVENT_NONE = orxENUM_NONE

} orxSOUND_EVENT;

typedef struct __orxSOUND_STREAM_INFO_t
{
  const orxSTRING zName;                      
  orxU32          u32SampleRate;              
  orxU32          u32ChannelNumber;           
} orxSOUND_STREAM_INFO;

typedef struct __orxSOUND_STREAM_PACKET_t
{
  orxFLOAT *afSampleList;                     
  orxU32    u32SampleNumber;                  
  orxFLOAT  fTimeStamp;                       
  orxFLOAT  fTime;                            
  orxS32    s32ID;                            
  orxBOOL   bDiscard;                         
  orxBOOL   bLast;                            
} orxSOUND_STREAM_PACKET;

typedef struct __orxSOUND_EVENT_PAYLOAD_t
{
  orxSOUND                   *pstSound;     
  struct
  {
    orxSOUND_STREAM_INFO      stInfo;       
    orxSOUND_STREAM_PACKET    stPacket;     
  } stStream;

  struct
  {
    orxSOUND_FILTER_DATA      stData;       
    orxSTRINGID               stBusID;      
  } stFilter;

} orxSOUND_EVENT_PAYLOAD;


extern orxDLLAPI void orxFASTCALL             orxSound_Setup();

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Init();

extern orxDLLAPI void orxFASTCALL             orxSound_Exit();


extern orxDLLAPI orxSOUND *orxFASTCALL        orxSound_Create();

extern orxDLLAPI orxSOUND *orxFASTCALL        orxSound_CreateFromConfig(const orxSTRING _zConfigID);

extern orxDLLAPI orxSOUND *orxFASTCALL        orxSound_CreateWithEmptyStream(orxU32 _u32ChannelNumber, orxU32 _u32SampleRate, const orxSTRING _zName);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Delete(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_ClearCache();


extern orxDLLAPI orxSOUND_SAMPLE *orxFASTCALL orxSound_CreateSample(orxU32 _u32ChannelNumber, orxU32 _u32FrameNumber, orxU32 _u32SampleRate, const orxSTRING _zName);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_DeleteSample(orxSOUND_SAMPLE *_pstSample);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_GetSampleInfo(const orxSOUND_SAMPLE *_pstSample, orxU32 *_pu32ChannelNumber, orxU32 *_pu32FrameNumber, orxU32 *_pu32SampleRate);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetSampleData(orxSOUND_SAMPLE *_pstSample, const orxFLOAT *_afData, orxU32 _u32SampleNumber);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_LinkSample(orxSOUND *_pstSound, const orxSTRING _zSampleName);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_UnlinkSample(orxSOUND *_pstSound);


extern orxDLLAPI orxBOOL orxFASTCALL          orxSound_IsStream(orxSOUND *_pstSound);


extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Play(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Pause(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Stop(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_AddFilter(orxSOUND *_pstSound, const orxSOUND_FILTER_DATA *_pstFilterData, orxBOOL _bUseCustomParam);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_RemoveLastFilter(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_RemoveAllFilters(orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_AddFilterFromConfig(orxSOUND *_pstSound, const orxSTRING _zFilterConfigID);


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

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_StopRecording();

extern orxDLLAPI orxBOOL orxFASTCALL          orxSound_HasRecordingSupport();


extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetVolume(orxSOUND *_pstSound, orxFLOAT _fVolume);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetPitch(orxSOUND *_pstSound, orxFLOAT _fPitch);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetTime(orxSOUND *_pstSound, orxFLOAT _fTime);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetPosition(orxSOUND *_pstSound, const orxVECTOR *_pvPosition);

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

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetPanning(orxSOUND *_pstSound, orxFLOAT _fPanning, orxBOOL _bMix);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_Loop(orxSOUND *_pstSound, orxBOOL _bLoop);


extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetVolume(const orxSOUND *_pstSound);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetPitch(const orxSOUND *_pstSound);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetTime(const orxSOUND *_pstSound);

extern orxDLLAPI orxVECTOR *orxFASTCALL       orxSound_GetPosition(const orxSOUND *_pstSound, orxVECTOR *_pvPosition);

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

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_GetPanning(const orxSOUND *_pstSound, orxFLOAT *_pfPanning, orxBOOL *_pbMix);

extern orxDLLAPI orxBOOL orxFASTCALL          orxSound_IsLooping(const orxSOUND *_pstSound);


extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetDuration(const orxSOUND *_pstSound);

extern orxDLLAPI orxSOUND_STATUS orxFASTCALL  orxSound_GetStatus(const orxSOUND *_pstSound);

extern orxDLLAPI const orxSTRING orxFASTCALL  orxSound_GetName(const orxSOUND *_pstSound);

extern orxDLLAPI orxSTRINGID orxFASTCALL      orxSound_GetMasterBusID();

extern orxDLLAPI orxSTRINGID orxFASTCALL      orxSound_GetBusID(const orxSOUND *_pstSound);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetBusID(orxSOUND *_pstSound, orxSTRINGID _stBusID);

extern orxDLLAPI orxSOUND *orxFASTCALL        orxSound_GetNext(const orxSOUND *_pstSound, orxSTRINGID _stBusID);

extern orxDLLAPI orxSTRINGID orxFASTCALL      orxSound_GetBusParent(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTRINGID orxFASTCALL      orxSound_GetBusChild(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTRINGID orxFASTCALL      orxSound_GetBusSibling(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetBusParent(orxSTRINGID _stBusID, orxSTRINGID _stParentBusID);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetBusVolume(orxSTRINGID _stBusID);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetBusPitch(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetBusVolume(orxSTRINGID _stBusID, orxFLOAT _fVolume);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_SetBusPitch(orxSTRINGID _stBusID, orxFLOAT _fPitch);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetBusGlobalVolume(orxSTRINGID _stBusID);

extern orxDLLAPI orxFLOAT orxFASTCALL         orxSound_GetBusGlobalPitch(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_AddBusFilter(orxSTRINGID _stBusID, const orxSOUND_FILTER_DATA *_pstFilterData, orxBOOL _bUseCustomParam);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_RemoveLastBusFilter(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_RemoveAllBusFilters(orxSTRINGID _stBusID);

extern orxDLLAPI orxSTATUS orxFASTCALL        orxSound_AddBusFilterFromConfig(orxSTRINGID _stBusID, const orxSTRING _zFilterConfigID);

#endif /*_orxSOUND_H_*/