SLAB Render API. More...

#include <srapi.h>

Public Member Functions
SRAPI Construction
	CSRAPI ()
	allocates a CSRAPI object

	~CSRAPI ()
	allocates a CSRAPI object

Render Functions
SLABError	RenderStart (SCRender scRender=SC::RenderSpatial, bool bAutoStop=true, bool bAsync=true)
	starts rendering

SLABError	RenderChange (SCRender scRender)
	changes the current Render Plugin

SLABError	RenderStop ()
	stops rendering

SLABError	RenderBatch (char pBatchDirIn, char pBatchDirOut, char *pScriptFile)
	batch renders a directory of wave files

SLABError	RenderEventPrepare (SCRender scRender, int nCh=2, int nDevice=0, int *nChMap=NULL, int nLen=0)
	prepares RenderEvent() for event-triggered playback

SLABError	RenderEvent ()
	plays pre-rendered sound data from memory

Desc **	RenderEnum ()
	enumerates Render Plugins

SCRender	RenderID (char *pName)
	returns the Render ID corresponding to a renderer's name

void	SetNotify (CBNOTIFY pcbNotify)
	sets the notification callback function

Source Functions
int	SrcGetID ()
	returns the next available sound source ID

SLABError	SrcAlloc (int nSrc)
	allocates a sound source

SLABError	SrcStream (int nSrc, int nStreamIn, int nChannel=0)
	attaches a stream to a sound source

bool	SrcFree ()
	frees all allocated sound sources

bool	SrcRadius (int nSrc, double dRadius=SC::SrcRadius(), double dSpread=SC::SrcSpread(), double dDistance0dB=SC::SrcDistance0dB())
	sets the radius of a sound source

bool	SrcLocate (int nSrc, double x=0.0, double y=0.0, double z=0.0)
	sets the location of a sound source

bool	SrcLoc (int nSrc, Pos scPos, double v)
	sets the location of a sound source using one coordinate

bool	SrcLocatePolar (int nSrc, double az, double el, double r)
	sets the location of a sound source relative to the origin

bool	SrcLocateLLH (int nSrc, double lat, double lon, double height)
	sets the location of a sound source in lat/long/height coords

bool	SrcLocateRel (int nSrc, double az, double el, double r)
	sets the location of a sound source relative to listener

bool	SrcLocatePan (int nSrc, float fPan)
	sets the location of a panned sound source

bool	SrcGain (int nSrc, double dDB)
	sets the gain of a sound source in dB

bool	SrcGainScalar (int nSrc, float fScalar=0.0)
	sets the gain of a sound source using a linear scalar

bool	SrcMute (int nSrc, bool bMute=false)
	mutes or unmutes a sound source

bool	SrcReplay (int nSrc, float fSeconds)
	sets the replay time of the sound source in seconds (Spatial2)

bool	SrcReplaySkip (int nSrc)
	enters replay skip silence mode (Spatial2)

bool	SrcEnable (int nSrc, bool bEnable=false)
	enables or disables rendering of a sound source

bool	SrcRefEnable (int nSrc, SCRvb scRvb=SC::RvbAll, bool bEnable=false)
	enables or disables a sound source's reflection

bool	SrcRefOffset (int nSrc, SCRvb scRvb=SC::RvbAll, bool bRefOffset=false, double x=0.0, double y=0.0, double z=0.0)
	enables or disables reflection offsets

bool	SrcMixGain (int nSrc, int nBegin, int nEnd, float *fGains, int nAux=-1)
	sets "Mixer" gains

bool	SrcMixAux (int nSrc, int nAux, bool bEnable, double dSet1, double dSet2)
	sets "Mixer" aux send parameters

StreamIn Functions
int	SiGetID ()
	returns the next available StreamIn ID not allocated or mapped

SLABError	SiAllocFile (int nStreamIn, char *pFilename, bool bLoop=true, bool bMemory=false, long lIndex=0, int nDelayLineLength=SC::DefDelayIn)
	allocates a wave file StreamIn

SLABError	SiAllocMemory (int nStreamIn, float *pBuffer, long lSamples, long lFs=SC::DefSampleRate, bool bLoop=true, int nDelayLineLength=SC::DefDelayIn)
	allocates a memory sample buffer StreamIn

SLABError	SiAllocUrl (int nStreamIn, const char pUrl, const char pDir, bool bLoop=false, int nPreBuf=SC::DefUrlPreBuf, long lDownBytes=SC::DefUrlBuf, long lReadBytes=SC::DefUrlBuf, int nDelayLineLength=SC::DefDelayIn)
	allocates a URL StreamIn

SLABError	SiAllocGen (int nStreamIn, char *pDir=NULL, int nDelayLineLength=SC::DefDelayIn)
	allocates a signal generator StreamIn

SLABError	SiAllocUser (int nStreamIn, int nSamples, int nCh, float *pBufPtr, HANDLE pEventSwap, int nDelayLineLength=SC::DefDelayIn)
	allocates a user StreamIn

SLABError	SiAllocASIO (int nStreamIn, int nCh=1, int *nChMap=NULL, int nLen=0, int nDelayLineLength=SC::DefDelayIn)
	allocates an ASIO device StreamIn

SLABError	SiAllocWave (int nSrc, int nDelayLineLength=SC::DefDelayIn)
	allocates a Waveform-Audio device StreamIn

SLABError	SiAllocSubmix (int nStreamIn, CSSIList *pSSIList, int nDelayLineLength=SC::DefDelayIn)
	allocates a submix StreamIn

SLABError	SiAllocDISRadio (int nStreamIn, int nPort, char *strID, int nPreBuf=SC::DisPreBuf, int nDelayLineLength=SC::DefDelayIn)
	allocates a DIS radio StreamIn

SLABError	SiAllocDISFreq (int nStreamIn, unsigned long long ullFreq, int nDelayLineLength=SC::DefDelayIn)
	allocates a DIS frequency StreamIn

SLABError	SiAllocDISRadios (int nNum, int nPort, int nPreBuf=SC::DisPreBuf)
	allocates multiple DIS radios for SiAllocDISFreq()

SLABError	SiAlloc_RT_DIS_Radio (int nStreamIn, int UDP_port, int output_sfreq, unsigned int min_latency_ms, int nDelayLineLength=SC::DefDelayIn)
	allocates a Real-Time DIS Radio Receiver StreamIn

void	SiFree (int nStreamIn)
	frees an individual StreamIn

void	SiFreeAll ()
	frees all StreamIns

CSSI *	SiStreamIn (int nStreamIn)
	returns a slabwire StreamIn (CSSI) pointer

Si StreamIn Support Functions (see also slabwire CSSI)
StreamType	SiType (int nStreamIn)
	returns stream type, see CSSI::SSInStreamType()

char *	SiTypeName (int nStreamIn)
	returns stream type name, see streams.h StreamStrings

bool	SiDone (int nStreamIn)
	returns true is stream done, e.g., one-shot wavefile playback finished

bool	SiPause (int nStreamIn)
	pause stream, see CSSI::SSInPause()

bool	SiPaused (int nStreamIn)
	returns true if stream paused, see CSSI::SSInPaused()

bool	SiPlay (int nStreamIn)
	play stream, see CSSI::SSInPlay()

bool	SiRewind (int nStreamIn)
	rewind stream, see CSSI::SSInRewind()

bool	SiAlias (int nStreamIn, bool bAlias)
	allows resample aliasing, see CSSI::DelayAlias()

bool	SiAmp (int nStreamIn, float fAmplitude)
	sets stream scalar amplitude

int	SiGetDelayLength (int nStreamIn)
	get delay line length in samples

float	SiGetAmp (int nStreamIn)
	gets stream scalar amplitude

bool	SiEnvPulse (int nStreamIn, float fDuration, float fFade, float fPeriod, bool bOneShot=false, float fAmpMin=0.0f, bool bEnvelopeLoopReset=true)
	sets stream pulse envelope parameters

float	SiGetEnvDuration (int nStreamIn)
	gets pulse duration in seconds

float	SiGetEnvFade (int nStreamIn)
	gets pulse fade in/out times in seconds

float	SiGetEnvPeriod (int nStreamIn)
	gets pulse period in seconds

bool	SiGetEnvOneShot (int nStreamIn)
	gets pulse one-shot flag

float	SiGetEnvAmpMin (int nStreamIn)
	gets pulse minimum scalar amplitude

bool	SiGetEnvRewind (int nStreamIn)
	gets pulse rewind waveforms on loop flag

bool	SiEnvUnity (int nStreamIn)
	replaces stream amplitude envelope with a unity gain scalar

bool	SiGetEnvUnity (int nStreamIn)
	gets envelope unity flag

SiGen Support Functions (see also slabwire CSIGen)
GMap *	SiGenEnum (int nStreamIn)
	enumerates signal generator plugins, see CSIGen::GenEnum()

GDesc *	SiGenDesc (int nStreamIn)
	returns a gplugin description struct, see CGPlugIn::GetDesc()

bool	SiGenSelect (int nStreamIn, char *pName)
	selects a signal generator plugin, see CSIGen::GenSelect()

bool	SiGenSet (int nStreamIn, int nParam, float fValue, bool bApply=false)
	sets gplugin parameter value, see CGPlugIn::Set()

bool	SiGenApply (int nStreamIn)
	informs gplugin one or more parameters set, see CGPlugIn::Apply()

bool	SiGenStart (int nStreamIn)
	starts gplugin sample generation, see CGPlugIn::Start()

bool	SiGenStop (int nStreamIn)
	stops gplugin sample generation (generates zeroes), see CGPlugIn::Stop()

GPList *	SiGenPList (int nStreamIn)
	returns gplugin parameter list, see CGPlugIn::GetPList()

SiDis Support Functions (see also slabwire CSIDISRadio/CSIDISFreq)
bool	SiDisSetID (int nStreamIn, const char *strID)
	sets the radio ID of a DIS radio stream

char *	SiDisGetID (int nStreamIn)
	returns the DIS radio ID of a DIS radio stream

unsigned long long	SiDisGetFreq (int nStreamIn)
	returns the DIS radio frequency in Hertz

int	SiDisGetPort (int nStreamIn)
	returns the DIS radio stream UDP port number of a DIS radio stream

bool	SiDisSetFreq (int nStreamIn, unsigned long long ullFreq)
	sets the radio frequency in Hertz of a DIS frequency stream

bool	SiDisSolo (int nStreamIn, const char *strID, bool bSolo)
	soloes a DIS radio in a DIS frequency stream

char *	SiDisGetSoloID (int nStreamIn)
	returns a radio ID if a radio is soloed in a DIS frequency stream

RT_DIS Support Functions
bool	Si_RT_DIS_Radio_Set_UDP_Receiver_Port (int nStreamIn, int UDP_port)
	sets the RT_DIS UDP receiver port

int	Si_RT_DIS_Radio_Get_UDP_Receiver_Port (int nStreamIn)
	gets the RT_DIS UDP receiver port

bool	Si_RT_DIS_Radio_Add_Frequency (int nStreamIn, unsigned __int64 radio_frequency_Hz, double gain)
	adds a DIS radio frequency to a Real-Time DIS Radio Receiver

bool	Si_RT_DIS_Radio_Remove_Frequency (int nStreamIn, unsigned __int64 radio_frequency_Hz)
	removes a DIS radio frequency from a Real-Time DIS Radio Receiver

bool	Si_RT_DIS_Radio_Remove_All_Frequencies (int nStreamIn)
	removes all DIS radio frequencies from a Real-Time DIS Radio Receiver

bool	Si_RT_DIS_Radio_Set_Gain (int nStreamIn, unsigned __int64 radio_frequency_Hz, double gain_dB)
	sets the gain(dB) of a DIS radio_frequency(Hz)

double	Si_RT_DIS_Radio_Get_Gain (int nStreamIn, unsigned __int64 radio_frequency_Hz)
	gets the gain(dB) of a DIS radio_frequency(Hz)

bool	Si_RT_DIS_Radio_Block_ID (int nStreamIn, int exercise, int site, int application, int entity, int radio)
	blocks (mutes) a radio ID in an RT_DIS stream

bool	Si_RT_DIS_Radio_Unblock_ID (int nStreamIn, int exercise, int site, int application, int entity, int radio)
	unblocks (unmutes) a radio ID in an RT_DIS stream

bool	Si_RT_DIS_Radio_Unblock_All (int nStreamIn)
	unblocks (unmutes) all blocked radio IDs in an RT_DIS stream

Environment Functions
void	EnvPlanes (double xp=SC::RoomDim()/2.0, double xn=-SC::RoomDim()/2.0, double yp=SC::RoomDim()/2.0, double yn=-SC::RoomDim()/2.0, double zp=SC::RoomDim() -SC::LstHeight(), double zn=-SC::LstHeight())
	sets the locations of the room planes

void	EnvPlane (SCRvb scRvb, double distance)
	sets the location of a room plane

bool	EnvMaterial (SCRvb scRvb, SCMat scMat=SC::MatNone)
	sets the plane material for a given plane

double	EnvBound (Pos scPos, double v)
	places a position coordinate inside room

double	EnvBoundX (double x)
	places x coordinate inside room

double	EnvBoundY (double y)
	places y coordinate inside room

double	EnvBoundZ (double z)
	places z coordinate inside room

double	EnvBoundR (double az, double el, double r)
	places polar range coordinate inside room

void	EnvLLHOrigin (double lat, double lon, double height)
	sets the LLH origin for converting to local slab3d/ENU coordinates

Listener Functions
bool	LstHRTFLoad (int nHRTF, const char *pName)
	loads an HRTF database

void	LstHRTFFree (int nHRTF)
	frees a loaded HRTF database

bool	LstHRTF (int nHRTF=-1, int nSrc=-1)
	selects an HRTF database

bool	LstHRTFHeader (int nHRTF, HRTFHeader *header)
	retrieves HRTF database header information

void	LstPosition (double x=0.0, double y=0.0, double z=0.0, double yaw=0.0, double pitch=0.0, double roll=0.0)
	positions the listener

void	LstPositionLLH (double lat=0.0, double lon=0.0, double height=0.0, double yaw=0.0, double pitch=0.0, double roll=0.0)
	positions the listener using LLH coordinates

void	LstPosOwnshipLLH (double ownLat, double ownLon, double ownHeight, double ownYaw, double ownPitch, double ownRoll, double lstX, double lstY, double lstZ, double lstYaw, double lstPitch, double lstRoll)
	positions the listener using ownship LLH and ownship-relative 6DOF head

void	LstPosOwnship (double ownX=0.0, double ownY=0.0, double ownZ=0.0, double ownYaw=0.0, double ownPitch=0.0, double ownRoll=0.0, double lstX=0.0, double lstY=0.0, double lstZ=0.0, double lstYaw=0.0, double lstPitch=0.0, double lstRoll=0.0)
	positions the listener using ownship XYZ and ownship-relative 6DOF head

void	LstPos (Pos scPos, double v)
	positions the listener using one coordinate

void	LstSensorPos (double x, double y, double z, double yaw, double pitch, double roll)
	positions the listener using a sensor position

void	LstSensorOffset (double x=0.0, double y=0.0, double z=SC::SensorOffsetM())
	sets tracker sensor offsets

Output Functions
SLABError	OutASIO (int nDevice=0, int nCh=2, int *nChMap=NULL, int nLen=0, bool bSplit=false)
	specifies ASIO as the device interface for sound output

SLABError	OutDirectSound (int nCh=2, int nOut=DS_BUFSIZE_OUT, int nWrite=DS_BUFSIZE_WRITE, bool bSplit=false)
	specifies DirectSound as the device interface for sound output

SLABError	OutWave (int nCh=2, bool bSplit=false)
	specifies Waveform-Audio as the device interface for sound output

SLABError	OutFile (char *pFilename, bool bMemory=false, int nCh=2, bool bSplit=false)
	specifies a wave file as the destination of sound output

bool	OutFree ()
	frees all sound output

SLABError	WaitSuspend ()
	waits on process suspend

SLABError	WaitSwap ()
	waits on an ASIO double-buffer swap

char *	GetASIOName (int nDevice)
	returns an ASIO device driver name

int	GetASIOInfo (int nDriver, ASIOInfo *pAsioInfo)
	fills an ASIOInfo struct for a given device

unsigned long	GetUnderflows ()
	returns the number of sound output underflows

unsigned long	GetClips ()
	returns the number of sample output clips

Callback Functions
SLABError	CallRate (double dUpdateRate=120.0)
	sets the Callback, Modifier, and Script update rate

unsigned int	CallPeriod ()
	returns the callback period in samples

double	CallTrueRate ()
	returns the true callback update rate in Hz

void	Callback (bool(pCallback)(void pData), void *pData=NULL)
	specifies a user callback routine

Modifier Functions
void	ModEnable (bool bEnable)
	enables or disables Modifier processing

void	ModSrcLocate (int nSrc, double dX, double dY, double dZ, double dRateX, double dRateY, double dRateZ)
	adds a SrcLocate() Modifier

void	ModSrcLocatePolar (int nSrc, double dAz, double dEl, double dR, double dRateAz, double dRateEl, double dRateR)
	adds a SrcLocatePolar() Modifier

void	ModSrcGainScalar (int nSrc, float *pfTable, int nLength, double dTime, bool bLoop)
	adds a SrcGainScalar() Modifier

bool	ModSiAllocFile (int nStreamID, char *pFilename, bool bLoop, bool bMemory, long lStart, double dPause)
	adds a SiAllocFile() Modifier

bool	ModStart (SCMod scMod, int nSrc)
	starts a Modifier

bool	ModStop (SCMod scMod, int nSrc)
	stops a Modifier

bool	ModRate (SCMod scMod, int nSrc, double dRateX, double dRateY, double dRateZ)
	adjusts a Modifier's rate of change

bool	ModRemove (SCMod scMod, int nSrc=-1)
	removes a Modifier

Scenefile and Script Functions
bool	SceneSave (char *pFilename)
	saves an XML scenefile (.scn)

bool	SceneOpen (char *pFilename)
	opens an XML scenefile (.scn)

void	ScriptEnable (bool bEnable)
	enables or disables script list processing

void	ScriptCallback (bool(pCallback)(void pData, int nArg, float f0, float f1, float f2, float f3), void *pData=NULL)
	specifies a slabscript callback routine

bool	ScriptOpen (char *pFilename, bool bScriptThread=false)
	opens an XML slabscript file (.sls)

void	ScriptFree ()
	frees script memory

unsigned int	ScriptMisses ()
	returns script thread update misses

Miscellaneous Functions
bool	SetSampleRate (long lSampleRate=SC::DefSampleRate)
	sets the render and output sample rate

void	SetResampler (bool bOversample=true, bool bArbitrary=true)
	sets resampler parameters

bool	SetSmoothTime (double dSmoothTime=SC::SmoothTime())
	sets the time constant of the parameter smoothing filter

bool	SetFIRTaps (int nFIRTaps=128, int nFIRTapsRef=32)
	sets the number of FIR taps for HRIR filtering

void	SetDelayOut (int nDelay=0)
	sets the sound output delay in frames

void	SetLevelTimes (float fAttack=0.137f, float fRelease=0.137f)
	sets the level meter attack and release time constants (Spatial2)

void	SetSkipSilence (float fLevel=0.050f, float fTime=0.500f, float fFadeIn=0.068f)
	sets the replay skip silence parameters (Spatial2)

void	SetNSOffset (double dB=-24.0)
	sets the non-spatial gain offset in dB

bool	SetDefaults ()
	sets several acoustic scene parameters to their default values

void	Reset ()
	resets SRAPI state

bool	SetSharedMemory (float *pFloats)
	Copies an array of 32 floats to shared memory.

bool	GetSharedMemory (float *pFloats)
	Gets an array of 32 floats from shared memory.

void	LLHToSlab3d (CoordLLH &llh, CoordLinear &xyz)
	convert LLH to slab3d x,y,z using pre-specified LLH origin

Error Functions
char *	ErrorString ()
	returns the current SRAPI error string

char *	ErrorStack ()
	returns the SRAPI error strack

void	ErrorClear ()
	clears the current SRAPI error

bool	ErrorState ()
	returns the SRAPI error state

SLABError	Error ()
	returns the current SRAPI error code

Log Functions
void	LogName (char *pLogName)
	sets the log filename

void	LogEntry (char *pLogEntry)
	logs a user message

void	LogTime ()
	logs the current system time

Update Functions (App and Render Plugin API)
void	SetHint (unsigned long ul)
	set hint

unsigned long	GetHint ()
	get hint

void	HintClear ()
	clear hint

void	SetTick (bool bTickUp)
	selects frame or tick parameter updating

void	Tick ()
	updates DSP parameters if using tick parameter updating

bool	Updated ()
	checks if SRAPI scene parameters have been updated

void	UpdateClear ()
	clears update state

void	UpdateSet ()
	sets update state

void	UpdateWaitReset ()
	resets the update done event

bool	UpdateWait ()
	waits for an update to be complete

void	SetUpdateWaitMode (bool bUpdateWaitMode=false)
	sets UpdateWait mode where some functions can wait on DSP update

void	Recalc ()
	recalculates the scene

void	Lock ()
	locks scene access

void	Unlock ()
	unlocks scene access

Query Functions (App and Render Plugin API)
bool	GetSrcAlloc (int nSrc)
	returns true if sound source allocated

int	GetSrcStreamID (int nSrc)
	gets the sound source's StreamID

double	GetSrcLoc (int nSrc, Pos scPos)
	gets a source location coordinate

double	GetSrcAz (int nSrc)
	returns the listener-relative source azimuth in radians, -pi to pi

double	GetSrcEl (int nSrc)
	returns the listener-relative source elevation in radians

double	GetSrcRange (int nSrc)
	returns the listener-relative source range in meters

int	GetSrcLocType (int nSrc)
	returns true if source is a listener-relative source

CoordPolar *	GetSrcPolar (int nSrc)
	returns the polar coordinates of source

double	GetSrcGain (int nSrc)
	gets the dB gain of the requested source

float	GetSrcGainScalar (int nSrc)
	gets the linear gain scalar of the requested source

bool	GetSrcMute (int nSrc)
	gets the mute state of the requested source

double	GetSrcRadius (int nSrc)
	gets the radius of the requested source

double	GetSrcSpread (int nSrc)
	gets the spreading loss of the requested source

double	GetSrcDistance0dB (int nSrc)
	gets the spreading loss 0dB reference of the requested source

bool	GetSrcEnable (int nSrc)
	gets enable state of source

bool	GetSrcRefEnable (int nSrc, SCRvb scRvb)
	gets enable state of reflection

float	GetSrcMixGain (int nSrc, int nIndex, int nAux=-1)
	gets the Mixer render plugin source gain or aux return gain

bool	GetSrcMixAuxEn (int nSrc, int nAux)
	gets the Mixer render plugin aux channel enable state

double	GetSrcMixAuxSet (int nSrc, int nAux, int nSet)
	gets the Mixer render plugin aux channel setting

float	GetSrcReplay (int n)
	gets the replay time in samples (Spatial2)

float	GetSrcLevel (int n)
	gets the source level meter value (Spatial2)

int	GetSrcNum ()
	returns the number of sound sources

double	GetEnvSndSpd ()
	returns the speed of sound

double	GetEnvPlane (SCRvb scRvb)
	gets the location of a room plane

SCMat	GetEnvMaterial (SCRvb scRvb)
	returns the material type of a surface

StMatCoeffs *	GetEnvMatCoeffs (SCRvb scRvb, long fs)
	returns material filter coefficients

bool	GetEnvBoundMove ()
	true if bound function changed coordinate

double	GetLstPos (Pos scPos)
	returns a listener position coordinate

double	GetOwnPos (Pos scPos)
	returns an ownship position coordinate

void	GetOwnSrcHBearing (int n, CoordPolar &polar)
	GetOwnSrcHBearing() - get ownship-relative source bearing for ownship in plane parallel to horizontal plane.

void	GetOwnSrcBearing (int n, CoordPolar &polar)
	GetOwnSrcBearing() - get ownship-relative source bearing.

bool	GetHRTFAllocated (int nHRTF)
	returns true if HRTF allocated

int	GetRenderID ()
	returns current Render ID

bool	GetRenderTime ()
	returns true if rendering

bool	GetUpdateWaitMode ()
	returns UpdateWait mode where some functions can wait on DSP update

double	GetSmoothTime ()
	returns the DSP parameter smoothing filter time constant

long	GetSampleRate ()
	returns the sample rate

int	GetFIRTaps ()
	returns the number of direct path HRIR FIR taps

int	GetFrameSize ()
	returns the frame size in samples

int	GetDelayOut ()
	returns the audio output delay in frames

int	GetDelayOutMax ()
	returns the maximum audio output delay in frames

int	GetOutCh ()
	returns the number of output channels

float	GetLevelAttack ()
	returns the level meter attack gain

float	GetLevelRelease ()
	returns the level meter release gain

float	GetSkipLevel ()
	returns the skip silence sound level threshold

int	GetSkipTime ()
	returns the skip silence time threshold

int	GetSkipFadeIn ()
	returns the skip silence fade in time

float	GetNSScalar ()
	gets the non-spatial offset linear gain scalar

double	GetNSOffset ()
	gets the non-spatial offset in dB

char *	GetExeDir ()
	gets the executable directory

double	GetPerf ()
	returns a performance counter time stamp

long	GetCPU ()
	returns CPU use (averaged over 10 calls)

Plugin Variable Functions (App and Render Plugin API)
void	SetPIVar (int nIndex, float fValue)
	sets a user plugin variable

void	SetPIVarRange (int nIndex, float *pValues, int nCount)
	sets a range of user plugin variables

bool	SetPIStatus (unsigned long lStatus, bool bBlock=false)
	sets the user plugin status variable

void	SetPIStatusReset ()
	resets the user plugin status variable

bool	PIVarUpdated ()
	checks if a plugin variable has been updated

void	PIVarUpdateClear ()
	clears the plugin variable updated flag

float	GetPIVar (int nIndex)
	gets the specified plugin variable

unsigned long	GetPIStatus ()
	gets the plugin status variable

unsigned long	GetPIStatusCmd ()
	gets the plugin status variable command

unsigned long	GetPIStatusArg ()
	gets the plugin status variable argument

Image Functions (Render Plugin API)
void	ResetImages ()
	resets the sound image list

void	NextImage ()
	advances to the next sound image

void	NextSource ()
	advances to the next sound source

bool	GiEmpty ()
	gets the image list empty flag

float	GiIn (float fIndex)
	gets a sample from a sound image's input delay line

float	GiIn (int nIndex)
	gets a sample from a sound image's input delay line

float	GiDelayLength ()
	gets a sound image's input delay line length

bool	GiEnabled ()
	gets the sound image enabled flag

int	GiSrcLocType ()
	gets the SrcLocate type

float	GiGain ()
	gets the scalar gain of the sound image

float	GiGainL ()
	gets the left scalar pan gain of the sound image

float	GiGainR ()
	gets the right scalar pan gain of the sound image

double	GiRadius ()
	returns the sound source radius

double	GiSpread ()
	returns the sound source spread

double	GiDistance0dB ()
	returns the sound source spread 0dB reference

double	GiX ()
	gets the x-coordinate of the sound image

double	GiY ()
	gets the y-coordinate of the sound image

double	GiZ ()
	gets the z-coordinate of the sound image

double	GiAz ()
	gets the listener-relative azimuth of the sound image

double	GiEl ()
	gets the listener-relative elevation of the sound image

double	GiRange ()
	gets the image-listener range

float	GiReplay ()
	returns the sound source replay time in samples

int	GiFIRn ()
	gets the number of FIR taps

void	GiHRTF (float fGain, float pfHRIRL, float pfHRIRR, float pfITDL, float pfITDR)
	gets the HRIR and ITD for the image

void	GiHRTF (double dAz, double dEl, int nFIRPts, float fGain, float pfHRIRL, float pfHRIRR, float pfITDL, float pfITDR)
	gets an az,el HRIR and ITD from the image HRTF

SCRvb	GiRefID ()
	gets the reflection ID of the image

ImageStruct *	GiStruct ()
	gets the image struct pointer

void *	GiData ()
	gets the plugin image data pointer

void	SiData (void *pData)
	sets the plugin image data pointer

Static Public Member Functions
slab3d Installation
static bool	SetLinks ()
	creates a slab3d Start Menu folder

DM (DIS Manager) Functions (see also slabwire CDISManager)
static int	DMGetRadioNum ()
	returns the number of DIS network radios

static CSIDISRadio *	DMGetRadio (int i)
	returns the slabwire radio pointer of a DIS network radio

static char *	DMGetRadioID (int i)
	returns the ID of a DIS network radio

static unsigned long long	DMGetRadioFreq (int i)
	returns the frequency of a DIS network radio

static bool	DMGetRadioPooled (int i)
	returns the frequency pool status of a DIS network radio

static int	DMGetFreqNum ()
	returns the number of unique DIS frequencies

static unsigned long long	DMGetFreq (int i)
	returns a DIS frequency from the unique frequency list

Sample Output Functions (Render Plugin API)
bool	OutSample (float fSample, int nOut=0)
	outputs a sample to the output buffer

void	OutPad (int nOut=0)
	zeros-out remaining channels in the output buffer

bool	MsgHandler (UINT msg, WPARAM wParam, LPARAM lParam)
	outputs a sample to the output buffer

HRESULT	XmlApiElement (CXML *pxml)
	outputs a sample to the output buffer

bool	XmlApi (IStream *stream)
	outputs a sample to the output buffer

SLABError	OutAdd (CSSO *pSSO, bool bSplit)
	outputs a sample to the output buffer

SLABError	ErrorHandle (SLABError)
	outputs a sample to the output buffer

DSPError	ProcStop ()
	outputs a sample to the output buffer

bool	InitPlugIns ()
	outputs a sample to the output buffer

void	RPlugInEnumDLL ()
	outputs a sample to the output buffer

bool	ModUpdate ()
	outputs a sample to the output buffer

ModStruct *	ModAdd (SCMod scMod)
	outputs a sample to the output buffer

void	ModFree (ModStruct *pMod)
	outputs a sample to the output buffer

ModStruct *	ModDelete (ModStruct pMod, ModStruct pModPre)
	outputs a sample to the output buffer

void	SetOutCh (int nChannels=2)
	outputs a sample to the output buffer

int	GetSampleBits ()
	outputs a sample to the output buffer

ImageSrc *	ImageAlloc (int nSrcID)
	outputs a sample to the output buffer

void	ImageStream (ImageSrc pSrc, int nStreamID, CSSI pSSI, int nCh)
	outputs a sample to the output buffer

void	ImageListFree ()
	outputs a sample to the output buffer

void	ImageInit (ImageStruct *pImage, SCRvb refID, int nFIRPts)
	outputs a sample to the output buffer

void	ImageInitSrc (ImageSrc pSrc, int nSrcID, CHRTF pHRTF)
	outputs a sample to the output buffer

void	ImageInitRef (ImageRef pRef, ImageSrc pSrc)
	outputs a sample to the output buffer

void	ImageModel (ImageRef *pRef)
	outputs a sample to the output buffer

void	F3DP (ImageStruct *pImage, double dListenerC[3], double dListenerFLT[][3])
	outputs a sample to the output buffer

bool	DetachStreamIn (ImageSrc *pSrc, int nStreamID, int nCh)
	outputs a sample to the output buffer

SLABError	SiReplace (int n, CSSI *pSSI)
	outputs a sample to the output buffer

ImageStruct *	GetNextImage ()
	outputs a sample to the output buffer

ImageSrc *	GetNextSource ()
	outputs a sample to the output buffer

bool	CallbackInternal ()
	outputs a sample to the output buffer

static bool __cdecl	CallbackStatic (void *pParam)
	outputs a sample to the output buffer

Detailed Description

The CSRAPI class encapsulates the SLAB Render API. SRAPI is used to allocate sound sources and sample streams, select output, control rendering, handle errors, and specify acoustic scene parameters.

Between RenderStart and RenderStop, SRAPI is rendering. Functions that cannot be called while rendering are termed static-state functions. If a static-state functions is called while rendering, an error results. See the Remarks section of the function documentation to determine if a function is a static-state function.

Typically, SRAPI is used by application developers. But, it is also the primary API used by Render Plugin developers. A pointer to the CSRAPI object is passed to the plugin via CRPlugIn::Init().

Application and Render Plugin functions:

Update Functions
Query Functions
Plugin Variable Functions

Render Plugin functions:

Image Functions
Sample Output Functions

The Update Functions manage the conversion of SRAPI scene parameters to reflection image locations and listener-relative geometric quantities.

The Query Functions are for querying SRAPI scene parameters. These parameters are set using the SLAB Render API or are fixed constants (e.g., speed of sound). Render Plugins can also query reflection image locations and listener-relative geometric quantities.

The Image Functions provide access to image-specific scene parameters. In use, the plugin renders each sound image by iterating through the list of all sound images.

See also: slabdefs.h, slabmath.h

Header: srapi.h
Library: srapi

Constructor & Destructor Documentation

◆ CSRAPI()

CSRAPI::CSRAPI ( )

The CSRAPI() constructor is used to allocate a CSRAPI object. At construction, the executable directory is searched for render plugins (r*.dll). The default render plugins (SCRender) are built into the SRAPI library.

Note: The Error Functions can be used to check for errors during construction. If an error occurs, the CSRAPI object should be deleted. Do NOT call SRAPI functions in a constructor error condition! Many SRAPI functions assume proper construction.

See also: Error Functions

◆ ~CSRAPI()

CSRAPI::~CSRAPI ( )

The CSRAPI() constructor is used to allocate a CSRAPI object. At construction, the executable directory is searched for render plugins (r*.dll). The default render plugins (SCRender) are built into the SRAPI library.

Note: The Error Functions can be used to check for errors during construction. If an error occurs, the CSRAPI object should be deleted. Do NOT call SRAPI functions in a constructor error condition! Many SRAPI functions assume proper construction.

See also: Error Functions

Member Function Documentation

◆ SetLinks()

static bool CSRAPI::SetLinks ( )

static

The SetLinks() function creates a slab3d Start Menu folder. This is typically performed by SLABScape following a slab3d installation. This function assumes it is being called by an application in the slab3d bin\ directory.

Returns: true = success, false = failure

◆ RenderStart()

SLABError CSRAPI::RenderStart	(	SCRender	scRender = `SC::RenderSpatial`,
		bool	bAutoStop = `true`,
		bool	bAsync = `true`
	)

The RenderStart() function initiates rendering. nID specifies either a pre-existing Render ID (e.g., RenderSpatial, RenderDiotic (see SCRender constants)) or an ID returned by RenderEnum(). Renderers are encapsulated in Render Plugins and can be developed by the SRAPI user.

The bAutoStop parameter enables the AutoStop feature. When AutoStop is enabled, rendering stops when all sound stream input has ended (e.g., if four one-shot wave files are playing, rendering stops when the last file completes). When rendering stops, the user's application is notified via the SetNotify() callback. If AutoStop is disabled, the input delay lines are filled with zeros once sound input ends and rendering continues until explicitly stopped with RenderStop(). This may be desirable for "event-driven" sounds, i.e., sounds synchronized with virtual environment events via StreamIn rewind.

The pre-defined Render Plugin IDs:

RenderSpatial: The Spatial renderer is the default renderer and renders most scene parameters.

RenderDichotic: Dichotic supports diotic, left-monotic, and right-monotic auditory display. The display type for each source is determined from the source's Y-axis location: + = left-monotic, 0.0 = diotic, and - = right-monotic. Dichotic ignores the Listener, Environment, and DSP API parameters. It also ignores the source parameters specified by SrcRadius() and SrcRefEnable().

RenderDiotic: Diotic renders a diotic auditory display. All sources are panned equally to the listener's left and right ears. Diotic renders the same set of scene parameters as Dichotic.

RenderMonoticL: Left-Monotic renders a left-monotic auditory display. All sources are panned to the listener's left ear. Left-Monotic renders the same set of scene parameters as Dichotic.

RenderMonoticR: Right-Monotic renders a right-monotic auditory display. All sources are panned to the listener's right ear. Right-Monotic renders the same set of scene parameters as Dichotic.

Warning: Do NOT use infinite length sound sources (e.g., looping wave files) with synchronous rendering (bAsync = false)!

Returns: SLABError

Remarks: static-state function

See also: RenderStop(), RenderChange()

Parameters

scRender	specifies the type of rendering to perform
bAutoStop	if true, when input ends, stop rendering
bAsync	if true, return immediately, don't wait for rendering to complete

◆ RenderChange()

SLABError CSRAPI::RenderChange ( SCRender scRender )

The RenderChange() function changes the current Render Plugin. nID specifies either a pre-existing Render ID (e.g., RenderSpatial, RenderDiotic) or an ID returned by RenderEnum(). Renderers are encapsulated in Render Plugins and can be developed by the SRAPI user. This function is useful for A-B'ing different rendering algorithms.

Returns: SLABError

See also: RenderStart()

Parameters

scRender render plugin ID

◆ RenderStop()

SLABError CSRAPI::RenderStop ( )

The RenderStop() function stops rendering begun with RenderStart(). If the sound output type was set to memory, the sound data in memory is written to a file during RenderStop().

See also: RenderStart()

◆ RenderBatch()

SLABError CSRAPI::RenderBatch	(	char *	pBatchDirIn,
		char *	pBatchDirOut,
		char *	pScriptFile
	)

The RenderBatch() function batch renders a directory of wave files. Each file found, replaces StreamIn 0.

◆ RenderEventPrepare()

SLABError CSRAPI::RenderEventPrepare	(	SCRender	scRender,
		int	nCh = `2`,
		int	nDevice = `0`,
		int *	nChMap = `NULL`,
		int	nLen = `0`
	)

The RenderEventPrepare() function prepares RenderEvent() for low-latency event-triggered playback. This function starts an ASIO device and begins outputting zeros. Meanwhile, all of the current sources are rendered to memory. When an event occurs (e.g., a button press), the user calls RenderEvent(). During the next ASIO callback, the pre-rendered memory data will be copied to the ASIO output buffer. This results in the lowest possible latency between an external event and sound playback (given the sampling rate, sound device ASIO latency, and ASIO buffer size).

Returns: SLABError

See also: RenderEvent(), RenderStart(), Render Functions

Parameters

scRender	Render ID
nCh	Number of output channels
nDevice	ASIO device
nChMap	ASIO channel map
nLen	ASIO channel map length

◆ RenderEvent()

SLABError CSRAPI::RenderEvent ( )

The RenderEvent() function plays pre-rendered sound data from memory. See RenderEventPrepare() for how to prepare the pre-rendered memory. RenderEventPrepare() and RenderEvent() form a pair similar to RenderStart() and RenderStop(). RenderEvent() waits for sound playback to complete before returning.

Returns: SLABError

See also: RenderEventPrepare(), Render Functions

◆ RenderEnum()

Desc ** CSRAPI::RenderEnum ( )

inline

The RenderEnum() function enumerates render plugins by returning an array of plugin description struct pointers. When CSRAPI is allocated, all plugins found in the slab3d_dir\bin\rplugin directory are loaded into memory and all of the plugin descriptions are placed in an array. The user can iterate through this array to query information about the available renderers. The description list is terminated by a NULL Desc* array entry. Do NOT free the description structs.

Returns: array of Desc pointers corresponding to the available renderers

See also: Render Functions

◆ RenderID()

SCRender CSRAPI::RenderID ( char * pName )

The RenderID() function returns the Render ID corresponding to a Render Plugin's name. The name is case-sensitive.

Returns: integer ID >= 0 if name found, -1 if name not found or SRAPI in an error state

See also: Render Functions

Parameters

pName case-sensitive name of Render Plugin

◆ SetNotify()

void CSRAPI::SetNotify ( CBNOTIFY pcbNotify )

The SetNotify() function sets the notification callback function used by SRAPI to notify the user of render-time events.

SC::NotifyDspDone
The DSP stopped processing. A render-time error occurred or all playback completed (RenderStart() AutoStop). Check error state to determine which.

SC::NotifyStreamDone
A StreamIn completed (e.g., one-shot wave file). The first callback parameter specifies the stream ID.

Returns: none

See also: Error Functions, RenderStart()

Parameters

pcbNotify address of user callback routine

◆ SrcGetID()

int CSRAPI::SrcGetID ( )

SrcGetID() returns the next available sound source ID.

Returns: -1 if all IDs taken

◆ SrcAlloc()

SLABError CSRAPI::SrcAlloc ( int nSrc )

SrcAlloc() allocates a sound source. The type of sound source depends on the render plugin used. For example, a sound source is a virtual environment emitter for the Spatial render plugin and a mixer channel strip for the Mixer render plugin.

The sound samples associated with a sound source are termed a StreamIn, being they are streamed into the renderer. StreamIns are allocated with the SiAlloc functions and are attached to sound sources via SrcStream().

nSrc can be any integer from 0 to SC::MaxSrc. This is simply a lookup index, so these need not be sequential. Sources do consume CPU, however, so only allocate the number of sources needed. StreamIns, on the other hand, only consume CPU when attached to sound sources. StreamIns can also be dynamically allocated, whereas sources cannot. The number of sources must remain constant while rendering. The mapping between sources and StreamIns can be changed at any time.

Remarks: static-state function

See also: SrcStream(), GetSrcAlloc(), SiAlloc Functions

Parameters

nSrc	sound source ID

◆ SrcStream()

SLABError CSRAPI::SrcStream	(	int	nSrc,
		int	nStreamIn,
		int	nChannel = `0`
	)

SrcStream() attaches a stream to a sound source. Streams can be attached, detached, and reassigned at any time. If the stream associated with a given StreamIn ID changes, all sources that reference that stream will be updated to use the new stream. If a stream is manipulated with an Si* StreamIn function, it will impact all sources using that stream (e.g., rewinding a multi-channel file would rewind all sources attached to that file).

nStreamIn can refer to a stream that has not yet been allocated. When that stream is allocated, it will automatically be attached to the waiting sound source.

To detach a stream from a sound source, set nStreamIn to -1.

Note: Continuous streams, like sound device input, need to remain attached to a sound source while rendering in order to service the continuous stream of input buffers.

See also: SiAlloc Functions

Parameters

nSrc	sound source ID
nStreamIn	StreamIn ID
nChannel	StreamIn channel

◆ SrcFree()

bool CSRAPI::SrcFree ( )

The SrcFree() function frees all allocated sound sources. If this function is called while rendering, nothing will be freed and the function will return false.

Returns: true = success, false = can't free while rendering

Remarks: static-state function

◆ SrcRadius()

bool CSRAPI::SrcRadius	(	int	nSrc,
		double	dRadius = `SC::SrcRadius()`,
		double	dSpread = `SC::SrcSpread()`,
		double	dDistance0dB = `SC::SrcDistance0dB()`
	)

The SrcRadius() function sets the radius of the sound source. It can also be used to set the 0 dB distance and a "spread" exponent. Together, the parameters dRadius, dDistance0dB, and dSpread define the spherical spreading loss curve, i.e., the gain behavior of a sound source as a function of source-listener distance.

A slab3d sound source is modeled as a cylindrical piston (e.g., a speaker cone) in order to determine its spreading loss. The source spread exponent dSpread affects the rate at which the spreading gain decreases as the source-listener range increases. The default value is 1.0. Although a spread exponent other than 1.0 does not have a physical interpretation, a value higher than 1.0 can be used to exaggerate the spherical spreading effect. A spread exponent of 0.0 disables spherical spreading loss.

Spherical spreading loss is defined by the following formula:

GainScalar = (1 + ((Range-Distance0dB) / dRadius)^2)^(-dSpread/2)

If (Range-Distance0dB) < 0, the quantity is set to 0 and the gain to 0 dB.
By setting dRadius = dINTERAURALm/2 (default), dSpread = 1 (default), and dDistance0dB to 0 (not default, default is dINTERAURALm/2), this equation can be made to approximate 1/Range point source behavior. If the radius of the head is set as the 0db reference, the 1/Range formula becomes:

[a] (dINTERAURALm/2)/Range

With the substitutions above, the slab3d formula becomes:

[b] (dINTERAURALm/2) / ( (dINTERAURALm/2)^2 + Range^2 )^(1/2)

When Range >> (dINTERAURALm/2), [b] approximates [a].

Note: Hint = SHSrcRadius

See also: spread.m slabtool

Parameters

nSrc	sound source ID
dRadius	source radius (meters)
dSpread	source spread exponent (see formula)
dDistance0dB	distance from head 0dB reference (see formula)

◆ SrcLocate()

bool CSRAPI::SrcLocate	(	int	nSrc,
		double	x = `0.0`,
		double	y = `0.0`,
		double	z = `0.0`
	)

The SrcLocate() function locates a sound source in world coordinates.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

Note: Hint = SHSrcLocate

See also: Source Functions

Parameters

nSrc	sound source ID
x	x-axis coordinate (meters)
y	y-axis coordinate (meters)
z	z-axis coordinate (meters)

◆ SrcLoc()

bool CSRAPI::SrcLoc	(	int	nSrc,
		Pos	scPos,
		double	v
	)

The SrcLoc() function is a variation of the SrcLocate() function but only sets one position coordinate.

Note: Hint = SHSrcLocate

See also: SrcLocate()

Parameters

nSrc	sound source ID
scPos	coordinate ID
v	coordinate value (meters)

◆ SrcLocatePolar()

bool CSRAPI::SrcLocatePolar	(	int	nSrc,
		double	az,
		double	el,
		double	r
	)

The SrcLocatePolar() function locates a sound source in origin-relative polar world coordinates.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

Note: Hint = SHSrcLocate

See also: Source Functions

Parameters

nSrc	sound source ID
az	azimuth coordinate (radians)
el	elevation coordinate (radians)
r	range coordinate (meters)

◆ SrcLocateLLH()

bool CSRAPI::SrcLocateLLH	(	int	nSrc,
		double	lat,
		double	lon,
		double	height
	)

The SrcLocateLLH() function locates a sound source using latitude, longitude, and height coordinates. These coordinates will be mapped to slab3d x,y,z coordinates using EnvLLHOrigin().

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index.

Note: Hint = SHSrcLocate

See also: Source Functions, EnvLLHOrigin(), LstPositionLLH()

Parameters

nSrc	sound source ID
lat	latitude (degrees, +90N to -90S)
lon	longitude (degrees, -180W to +180E)
height	height (meters)

◆ SrcLocateRel()

bool CSRAPI::SrcLocateRel	(	int	nSrc,
		double	az,
		double	el,
		double	r
	)

The SrcLocateRel() function locates a sound source relative to the listener. The location is specified in polar coordinates. Relative sources are anechoic.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

Note: Hint = SHSrcLocate

See also: Source Functions

Parameters

nSrc	sound source ID
az	azimuth coordinate (radians)
el	elevation coordinate (radians)
r	range coordinate (meters)

◆ SrcLocatePan()

bool CSRAPI::SrcLocatePan	(	int	nSrc,
		float	fPan
	)

The SrcLocatePan() function locates a sound source using left and right gain values. Panned sources are anechoic. Propagation delay and HRTF processing is disabled.

Note: Hint = SHSrcLocate

See also: Source Functions

Parameters

nSrc	sound source ID
fPan	fully left 0.0, fully right 1.0, diotic 0.5

◆ SrcGain()

bool CSRAPI::SrcGain	(	int	nSrc,
		double	dDB
	)

The SrcGain() function specifies the gain applied to sound source samples. This gain value is analogous to a source volume control. Its implementation is Render Plugin specific.

Remarks: Source gain is one of two API gain parameters. The stream-in amplitude specified by SiAmp() is applied between the stream-in object and the input delay line. Source gain is applied after the input delay line, inside the Render Plugin. SiAmp() is useful for setting inputs to a similar level so that SrcGain() values have a similar end result, i.e., like trim pots on a mixer before the faders. E.g., one might lower signal generator amplitude using SiAmp() when using generators with wave files since wave files, in general, aren't as loud.

Note: Hint = SHSrcGain

See also: SrcGainScalar(), SrcMute(), GetSrcGain(), Source Functions

Parameters

nSrc	sound source ID
dDB	gain, dB

◆ SrcGainScalar()

bool CSRAPI::SrcGainScalar	(	int	nSrc,
		float	fScalar = `0.0`
	)

The SrcGainScalar() function specifies the gain applied to sound source samples. This gain value is analogous to a source volume control.

Note: Hint = SHSrcGain

See also: SrcGain(), SrcMute(), Source Functions

Parameters

nSrc	sound source ID
fScalar	linear scalar gain

◆ SrcMute()

bool CSRAPI::SrcMute	(	int	nSrc,
		bool	bMute = `false`
	)

The SrcMute() function mutes or unmutes the source gain.

Note: Internally, mute is applied using a source gain scalar. Thus, rendering is still performed. Depending on the application, it might be preferable to disable the sound source and reflections. Disabling prevents rendering. An advantage of SrcMute() is that the direct path and reflections are muted with one function call and the enable state is left unchanged.; Hint = SHSrcGain

See also: SrcGain(), Source Functions

Parameters

nSrc	sound source ID
bMute	true = mute, false = unmute

◆ SrcReplay()

bool CSRAPI::SrcReplay	(	int	nSrc,
		float	fSeconds
	)

The SrcReplay() function sets the replay time of the sound source in samples. This time is added to the propagation delay in the Spatial2 renderer. Thus, using large delay lines, the delay line can also serve as a replay buffer.

See also: SrcReplaySkip(), Source Functions

Parameters

nSrc	sound source ID
fSeconds	replay time, seconds

◆ SrcReplaySkip()

bool CSRAPI::SrcReplaySkip ( int nSrc )

The SrcReplaySkip() function enters replay skip silence mode to catch up to now.

See also: SrcReplay(), SetSkipSilence(), Source Functions

Parameters

nSrc	sound source ID

◆ SrcEnable()

bool CSRAPI::SrcEnable	(	int	nSrc,
		bool	bEnable = `false`
	)

The SrcEnable() function enables or disables a sound source. SrcEnable() is similar to a mixer's mute button. When a source is disabled, it is no longer rendered, thus decreasing CPU load. When using reflections, SrcEnable() only impacts the direct path. SrcRefEnable() can be used to enable and disable reflections.

See also: SrcRefEnable(), Source Functions

Parameters

nSrc	sound source ID
bEnable	if true, the source is enabled, if false, the source is disabled

◆ SrcRefEnable()

bool CSRAPI::SrcRefEnable	(	int	nSrc,
		SCRvb	scRvb = `SC::RvbAll`,
		bool	bEnable = `false`
	)

The SrcRefEnable() function enables or disables a sound source reflection. When a reflection is disabled, it is no longer processed, decreasing CPU load.

See also: SrcEnable(), Source Functions

Parameters

nSrc	sound source ID
scRvb	reflection identifier (see slabdefs.h)
bEnable	if true, the reflection is enabled, if false, the reflection is disabled

◆ SrcRefOffset()

bool CSRAPI::SrcRefOffset	(	int	nSrc,
		SCRvb	scRvb = `SC::RvbAll`,
		bool	bRefOffset = `false`,
		double	x = `0.0`,
		double	y = `0.0`,
		double	z = `0.0`
	)

The SrcRefOffset() function enables or disables reflection offsets. The offsets will be added to the computed reflection image location.

Note: Hint = SHSrcLocate

See also: SrcRefEnable(), Source Functions

Parameters

nSrc	sound source ID
scRvb	reflection identifier (see slabdefs.h)
bRefOffset	if true, reflection offsets are enabled, if false, reflection offsets are disabled
x	x offset amount
y	y offset amount
z	z offset amount

◆ SrcMixGain()

bool CSRAPI::SrcMixGain	(	int	nSrc,
		int	nBegin,
		int	nEnd,
		float *	fGains,
		int	nAux = `-1`
	)

The SrcMixGain() function sets the "Mixer" render plugin gains. These scalar gains adjust the source level for each output. The standard source gain (e.g., SrcGain()) is used as a master gain setting applied prior to the source output gains and the aux sends (see below). SrcEnable() enables and disables all mixer processing for the source.

If nAux is 0 or 1, SrcMixGain() sets the aux return parameters. The aux sends return an HRTF L,R pair. The left return will be mixed into even-numbered outputs 0,2,4,... and the right return will be mixed into odd-numbered outputs 1,3,5,....

See also: SrcMixAux()

Parameters

nSrc	sound source ID
nBegin	beginning gain index
nEnd	ending gain index
fGains	scalar output gains
nAux	-1 = sound source, 0,1 = aux return

◆ SrcMixAux()

bool CSRAPI::SrcMixAux	(	int	nSrc,
		int	nAux,
		bool	bEnable,
		double	dSet1,
		double	dSet2
	)

The SrcMixAux() function sets the "Mixer" render plugin aux send parameters. There are two aux sends per source, each consisting of an independent HRTF processor. These should be used only as needed because they consume a fair amount of computational resources. Additional parameters used by the aux sends include the HRTF database and FIR taps settings.

dSet1 = azimuth in radians dSet2 = elevation in radians

See also: SrcMixGain()

Parameters

nSrc	sound source ID
nAux	aux send, 0 or 1
bEnable	enable or disable aux send
dSet1	aux setting 1
dSet2	aux setting 2

◆ SiGetID()

int CSRAPI::SiGetID ( )

SiGetID() returns the next available StreamIn ID not allocated or mapped.

Returns: -1 if all IDs taken

◆ SiAllocFile()

SLABError CSRAPI::SiAllocFile	(	int	nStreamIn,
		char *	pFilename,
		bool	bLoop = `true`,
		bool	bMemory = `false`,
		long	lIndex = `0`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocFile() allocates a wave file StreamIn.

If bLoop is true, the wave file plays continuously, looping back to the beginning when it reaches the end. If bLoop is false, one-shot playback is selected. In this mode, playback stops at the end of the wave file. See the SetNotify() function for notifications that are available for one-shot playback.

If bMemory is true, the entire wave file is read into memory before it is rendered. This option can be useful if disk access is causing sound output underflows. However, it should only be used with relatively small wave files (depends on available RAM). This option creates a StreamInMemory sample stream instead of a StreamInFile. lIndex is ignored.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream(), SiStreamIn()

Parameters

nStreamIn	StreamIn ID
pFilename	file to play
bLoop	if true, loop file
bMemory	if true, load entire file into memory
lIndex	sample start index
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocMemory()

SLABError CSRAPI::SiAllocMemory	(	int	nStreamIn,
		float *	pBuffer,
		long	lSamples,
		long	lFs = `SC::DefSampleRate`,
		bool	bLoop = `true`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocMemory() allocates a memory sample buffer StreamIn.

pBuffer should be allocated as follows: pBuffer = (float*) GlobalAllocPtr( GMEM_MOVEABLE | GMEM_SHARE, lSamples * sizeof(float) ); pBuffer will be freed by SRAPI.

If bLoop is true, the buffer plays continuously, looping back to the beginning when it reaches the end. If bLoop is false, one-shot playback is selected. In this mode, playback stops at the end of the buffer. See the SetNotify() function for notifications that are available for one-shot playback.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream(), SiStreamIn()

Parameters

nStreamIn	StreamIn ID
pBuffer	1-channel sample buffer
lSamples	number of samples in buffer
lFs	sample rate in samples/s
bLoop	if true, loop buffer
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocUrl()

SLABError CSRAPI::SiAllocUrl	(	int	nStreamIn,
		const char *	pUrl,
		const char *	pDir,
		bool	bLoop = `false`,
		int	nPreBuf = `SC::DefUrlPreBuf`,
		long	lDownBytes = `SC::DefUrlBuf`,
		long	lReadBytes = `SC::DefUrlBuf`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocUrl() allocates a URL StreamIn. URL addresses are of the form "http://target.wav" and are specified via the pUrl parameter. The files are downloaded to the directory specified by pDir. The remote file is rendered while it is being downloaded, so smooth playback is dependent upon pre-buffering (nPreBuf) and the buffer sizes (lDownBytes, lReadBytes). The maximum download buffer size (lDownBytes) is 8192 bytes. Experimentation will most likely be required to find the best parameters for a given format and connection speed. While pre-buffering, a URL StreamIn streams silence.

If bLoop is true, the wave file plays continuously, looping back to the beginning when it reaches the end. If bLoop is false, one-shot playback is selected. In this mode, playback stops at the end of the wave file. See the SetNotify() function for notifications that are available for one-shot playback.

The supported file types are:

format: PCM, float
bit width: 8-bit and 16-bit PCM, 32-bit float
sample rate: arbitrary
channels: arbitrary

The local version of the remote file will not be identical to the remote file. It will have the same format and sample data, but other RIFF file data will be discarded.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

Note: If the remote file has been streamed before, it might stream from the cache rather than from the remote site.; The remote files are saved using their WAV filename. Thus, playing multiple WAV files with the same name is not supported.

See also: SrcStream()

Parameters

nStreamIn	StreamIn ID
pUrl	"http://target.wav"-style address
pDir	local download dir
bLoop	loop wave file
nPreBuf	number of buffers to download before playback
lDownBytes	size of download buffer in bytes
lReadBytes	size of read buffer in bytes
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocGen()

SLABError CSRAPI::SiAllocGen	(	int	nStreamIn,
		char *	pDir = `NULL`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocGen() allocates a signal generator StreamIn. The signal generator type can be selected with the SiGenSelect() function. If pDir is NULL, the executable directory is searched for generator plugins (g*.dll).

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream(), SiGen*() Functions

Parameters

nStreamIn	StreamIn ID
pDir	generator plugin dir
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocUser()

SLABError CSRAPI::SiAllocUser	(	int	nStreamIn,
		int	nSamples,
		int	nCh,
		float **	pBufPtr,
		HANDLE *	pEventSwap,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocUser() allocates a user StreamIn. A "user" StreamIn is a StreamIn whose samples are provided by the user while rendering. A double-buffer mechanism is employed where the user fills the write buffer while the playback buffer is rendered. When the playback buffer completes, the buffers are swapped; the current write buffer becomes a playback buffer and the previous playback buffer becomes the new write buffer. When this occurs, an event is set to indicate the user's buffer base address variable has been updated and is ready for writing.

The buffer swap event is allocated by SRAPI and returned in pEventSwap. It should be caught using WaitForSingleObject() with a timeout value larger than the buffer size. If another event is signaled before the write buffer is filled, an underflow occurs. This can be detected by calling WaitForSingleObject() with a timeout interval of 0. The buffer swap event is automatically reset once a waiting thread is released.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream()

Parameters

nStreamIn	StreamIn ID
nSamples	number of samples in buffer
nCh	number of channels in buffer
pBufPtr	current double-buffer base address
pEventSwap	event set when buffers swapped
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocASIO()

SLABError CSRAPI::SiAllocASIO	(	int	nStreamIn,
		int	nCh = `1`,
		int *	nChMap = `NULL`,
		int	nLen = `0`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocASIO() allocates a sound device using the ASIO interface. A channel map can be provided that maps ASIO channels to SiAllocASIO() channels. Use the slab3d application SLABSound to view the ASIO channels available. nCh specifies the number of ASIO input channels to open. The ASIO device is selected using OutASIO().

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

Note: OutASIO() must be called before SiAllocASIO().

See also: SrcStream(), OutASIO(), GetASIOName(), GetASIOInfo()

Parameters

nStreamIn	StreamIn ID
nCh	number of input channels
nChMap	channel map
nLen	channel map length
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocWave()

SLABError CSRAPI::SiAllocWave	(	int	nSrc,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocWave() allocates a sound device using the Waveform-Audio interface. The device opened is set by the Windows Wave Mapper. The Windows Wave Mapper device is set using the Sounds and Audio Device control panel applet.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream()

Parameters

nSrc	StreamIn ID
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocSubmix()

SLABError CSRAPI::SiAllocSubmix	(	int	nStreamIn,
		CSSIList *	pSSIList,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocSubmix() creates a StreamIn that is a mix of multiple StreamIns. This function requires the use of slabwire to create the sample stream input (SSI) list. The mix stream and the submix streams are freed via SiFreeAll(). This StreamIn type should not be reallocated or freed via SiFree().

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream(), SiFreeAll()

Parameters

nStreamIn	StreamIn ID
pSSIList	slabwire SSI (sample stream input) list
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocDISRadio()

SLABError CSRAPI::SiAllocDISRadio	(	int	nStreamIn,
		int	nPort,
		char *	strID,
		int	nPreBuf = `SC::DisPreBuf`,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocDISRadio() listens on port nPort for a DIS radio connection.

nPort is the port on which to listen for DIS connections. The first DIS StreamIn allocated during app execution sets the port for all DIS StreamIns.

strID is the ID of the DIS radio this StreamIn will listen to. To init without ID, use "". DIS Manager can be used to query available IDs. Use "auto" to have a radio automatically assigned when one becomes available.

nPreBuf specifies the number of zeroes to pre-buffer in the DIS buffer.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

Warning: Do not use DIS with non-real-time sound output alone. Samples are provided as fast as they are requested. Thus, for faster than real-time processing to wave file output, the file will grow very large very quickly.

See also: SrcStream(), SiAllocDISFreq(), DM (DIS Manager) functions, SiDisSetID(), SiDisGetID(), SiDisGetFreq(), SiDisGetPort()

Parameters

nStreamIn	StreamIn ID
nPort	DIS listening port (e.g., 3000)
strID	radio ID (e.g., "100.104.1.1")
nPreBuf	pre-buffered zeroes, default = 10ms
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocDISFreq()

SLABError CSRAPI::SiAllocDISFreq	(	int	nStreamIn,
		unsigned long long	ullFreq,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAllocDISFreq() mixes all DIS radios at the specified frequency. It is analogous to a local radio tuned to a particular frequency. The remote radios must be allocated beforehand with SiAllocDISRadios(). Set ullFreq to 0 if frequency not know at alloc.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

See also: SrcStream(), SiAllocDISRadios(), SiAllocDISRadio(), DM (DIS Manager) functions, SiDisSetFreq(), SiDisGetFreq(), SiDisSolo()

Parameters

nStreamIn	StreamIn ID
ullFreq	DIS frequency
nDelayLineLength	length of stream's input delay line in ms

◆ SiAllocDISRadios()

SLABError CSRAPI::SiAllocDISRadios	(	int	nNum,
		int	nPort,
		int	nPreBuf = `SC::DisPreBuf`
	)

SiAllocDISRadios() allocates multiple DIS radios for SiAllocDISFreq(). The parameters are the same as SiAllocDISRadio(). IDs are automatically assigned as radios appear on the DIS network. These radios can only be freed via SiFreeAll().

Warning: Do not use DIS with non-real-time sound output alone. Samples are provided as fast as they are requested. Thus, for faster than real-time processing to wave file output, the file will grow very large very quickly.

See also: SiAllocDISFreq(), SiFreeAll(), DM (DIS Manager) functions

Parameters

nNum	number of DIS radios to allocate
nPort	DIS listening port (e.g., 3000)
nPreBuf	pre-buffered zeroes, default = 10ms

◆ SiAlloc_RT_DIS_Radio()

SLABError CSRAPI::SiAlloc_RT_DIS_Radio	(	int	nStreamIn,
		int	UDP_port,
		int	output_sfreq,
		unsigned int	min_latency_ms,
		int	nDelayLineLength = `SC::DefDelayIn`
	)

SiAlloc_RT_DIS_Radio() allocates a Real-Time DIS Radio Receiver StreamIn. A Real-Time DIS Radio Receiver Streamin can be used to receive all DIS radios on any combination of DIS radio frequencies. All transmitting DIS radios, which match the active frequency list are mixed together and then rendered as one SRAPI source. Frequencies can be added and removed during the life of the StreamIn. And each individual frequency's Gain can be set and queried individually.

The nDelayLineLength parameter sets the stream input delay line length used to model time delay effects such as source-to-listener sound propagation delay and ITD.

Parameters

nStreamIn	StreamIn ID
UDP_port	UDP receive port
output_sfreq	frequency in Hz which this source will produce
min_latency_ms	minimum latency (added when a transmission starts/restarts)
nDelayLineLength	length of stream's input delay line in ms

◆ SiFree()

void CSRAPI::SiFree ( int nStreamIn )

SiFree() frees an individual StreamIn. If sources are attached to the StreamIn, they are detached but the mapping to the StreamIn ID and channel remain. If the StreamIn ID is reallocated, the sources will automatically reattach. To disable this functionality, use SrcStream( nSrcID, -1 ).

See also: SiFreeAll(), SiAlloc*() Functions

Parameters

nStreamIn StreamIn ID

◆ SiFreeAll()

void CSRAPI::SiFreeAll ( )

SiFreeAll() frees all StreamIns.

Note: This function is the only way to free the StreamIns used by SiAllocSubmix() and SiAllocDISRadios().

See also: SiFree(), SiAlloc*() Functions

◆ SiStreamIn()

CSSI * CSRAPI::SiStreamIn ( int nStreamIn )

SiStreamIn() returns a slabwire StreamIn (CSSI) pointer. This function allows users to access features not available via the Si*() wrapper functions.

Parameters

nStreamIn StreamIn ID

◆ SiDisSetID()

bool CSRAPI::SiDisSetID	(	int	nStreamIn,
		const char *	strID
	)

The SiDisSetID() function sets the radio ID of a DIS radio stream. The available DIS network radio IDs can be queried using DIS Manager.

Returns: false if radio ID already mapped to a DIS radio stream

See also: SiDisGetID(), DM (DIS Manager) functions

Parameters

nStreamIn	StreamIn ID
strID	radio ID string (see SiDisGetID())

◆ SiDisGetID()

char * CSRAPI::SiDisGetID ( int nStreamIn )

The SiDisGetID() function returns the DIS radio ID of a DIS radio stream. A DIS radio ID is composed of four 16-bit unsigned ints concatenated into a string "%d.%d.%d.%d" (site, host, entity, radio):

Entity ID = [ Site | Host | Entity ] Radio ID = [ Entity ID | Radio ]

Reference: IEEE Std 1278.1-1995, 4.5.7, pgs.49-52, 5.3.8, pgs.112-118

Returns: radio ID

See also: SiDisSetID(), SiDisGetFreq(), DM (DIS Manager) functions

Parameters

nStreamIn StreamIn ID

◆ SiDisGetFreq()

unsigned long long CSRAPI::SiDisGetFreq ( int nStreamIn )

The SiDisGetFreq() function returns the DIS radio frequency in Hertz for DIS radio and DIS frequency streams.

Returns: DIS radio frequency in Hertz

See also: SiDisGetID(), SiDisSetFreq(), DM (DIS Manager) functions

Parameters

nStreamIn StreamIn ID

◆ SiDisGetPort()

int CSRAPI::SiDisGetPort ( int nStreamIn )

The SiDisGetPort() function returns the UDP port number of a DIS radio stream (DIS frequency streams not supported).

Returns: UDP port number

See also: SiDisGetID()

Parameters

nStreamIn StreamIn ID

◆ SiDisSetFreq()

bool CSRAPI::SiDisSetFreq	(	int	nStreamIn,
		unsigned long long	ullFreq
	)

The SiDisSetFreq() function sets the radio frequency in Hertz of a DIS frequency stream.

Returns: false if nStreamIn invalid

See also: SiDisGetFreq(), DM (DIS Manager) functions

Parameters

nStreamIn	StreamIn ID
ullFreq	radio frequency in Hertz

◆ SiDisSolo()

bool CSRAPI::SiDisSolo	(	int	nStreamIn,
		const char *	strID,
		bool	bSolo
	)

The SiDisSolo() function soloes a DIS radio in a DIS frequency stream. When a radio is soloed, it is muted in all other frequency streams.

Returns: false if radio ID not found in frequency pool

See also: SiDisSetFreq(), DM (DIS Manager) functions

Parameters

nStreamIn	StreamIn ID
strID	DIS radio ID (see SiDisGetID())
bSolo	true = solo radio, false = unsolo

◆ SiDisGetSoloID()

char * CSRAPI::SiDisGetSoloID ( int nStreamIn )

SiDisGetSoloID() returns a radio ID if a radio is soloed in a DIS frequency stream. If a radio is not soloed, NULL is returned.

Returns: radio ID or NULL

See also: SiDisSolo(), DM (DIS Manager) functions

Parameters

nStreamIn StreamIn ID

◆ DMGetRadioNum()

static int CSRAPI::DMGetRadioNum ( )

static

The DMGetRadioNum() function returns the number of DIS network radios.

Note: If only RT_DIS used, this function supports RT_DIS.

Returns: number of DIS network radios

See also: DMGetFreqNum(), SiDis functions, DM functions

◆ DMGetRadio()

static CSIDISRadio * CSRAPI::DMGetRadio ( int i )

static

The DMGetRadio() function returns the slabwire radio pointer of a DIS network radio. Valid indices are 0 to DMGetRadioNum()-1. If this pointer is non-NULL, the remote DIS radio is mapped to an SRAPI DIS radio object.

Returns: slabwire radio pointer

See also: DMGetRadioNum(), DMGetRadioID(), DMGetRadioFreq(), SiDis functions, DM functions

◆ DMGetRadioID()

static char * CSRAPI::DMGetRadioID ( int i )

static

The DMGetRadioID() function returns the ID of a DIS network radio. Valid indices are 0 to DMGetRadioNum()-1. When a new DIS radio connects, its ID is added to a list. This function, in concert with DMGetRadioNum(), can be used to poll the available DIS radios one can listen to.

A slab3d DIS Radio ID is composed of four 16-bit unsigned ints concatenated into a string "%d.%d.%d.%d" (site, host, entity, radio):

Entity ID = [ Site | Host | Entity ] Radio ID = [ Entity ID | Radio ]

Reference: IEEE Std 1278.1-1995, 4.5.7, pgs.49-52, 5.3.8, pgs.112-118

Note: If only RT_DIS used, this function supports RT_DIS. RT_DIS includes an additional field, Exercise, before the Entity ID.

Returns: radio ID string

See also: DMGetRadioNum(), DMGetRadioFreq(), DMGetRadio(), SiDis functions, DM functions

◆ DMGetRadioFreq()

static unsigned long long CSRAPI::DMGetRadioFreq ( int i )

static

The DMGetRadioFreq() function returns the frequency of a DIS network radio. Valid indices are 0 to GetRadioNum()-1.

Returns: radio frequency in Hertz

See also: DMGetRadioNum(), DMGetRadioID(), DMGetRadio(), SiDis functions, DM functions

◆ DMGetRadioPooled()

static bool CSRAPI::DMGetRadioPooled ( int i )

static

The DMGetRadioPooled() function returns true if the radio is a member of a frequency pool (see SiAllocDISRadios()). Valid indices are 0 to GetRadioNum()-1.

Returns: frequency pool member flag

See also: DMGetRadioNum(), DMGetRadioID(), DMGetRadioFreq(), SiDis functions, DM functions

◆ DMGetFreqNum()

static int CSRAPI::DMGetFreqNum ( )

static

The DMGetFreqNum() function returns the number of unique DIS frequencies that have been observed on the DIS network.

Note: If only RT_DIS used, this function supports RT_DIS.

Returns: number of unique DIS frequencies

See also: DMGetRadioNum(), SiDis functions, DM functions

◆ DMGetFreq()

static unsigned long long CSRAPI::DMGetFreq ( int i )

static

The DMGetFreq() function returns a DIS frequency from the unique frequency list. Valid indices are 0 to GetFreqNum()-1.

Note: If only RT_DIS used, this function supports RT_DIS.

Returns: radio frequency in Hertz

See also: DMGetFreqNum(), SiDis functions, DM functions

◆ Si_RT_DIS_Radio_Set_UDP_Receiver_Port()

bool CSRAPI::Si_RT_DIS_Radio_Set_UDP_Receiver_Port	(	int	nStreamIn,
		int	UDP_port
	)

Parameters

nStreamIn	StreamIn ID
UDP_port	UDP receive port

◆ Si_RT_DIS_Radio_Get_UDP_Receiver_Port()

int CSRAPI::Si_RT_DIS_Radio_Get_UDP_Receiver_Port ( int nStreamIn )

Parameters

nStreamIn StreamIn ID

◆ Si_RT_DIS_Radio_Add_Frequency()

bool CSRAPI::Si_RT_DIS_Radio_Add_Frequency	(	int	nStreamIn,
		unsigned __int64	radio_frequency_Hz,
		double	gain
	)

Si_RT_DIS_Radio_Add_Frequency() adds the radio_frequency in Hz to the list of received frequencis for nStreamIn, using the specified gain.

◆ Si_RT_DIS_Radio_Remove_Frequency()

bool CSRAPI::Si_RT_DIS_Radio_Remove_Frequency	(	int	nStreamIn,
		unsigned __int64	radio_frequency_Hz
	)

Si_RT_DIS_Radio_Remove_Frequency() removes the radio_frequency in Hz from the list of received frequencis for nStreamIn.

◆ Si_RT_DIS_Radio_Remove_All_Frequencies()

bool CSRAPI::Si_RT_DIS_Radio_Remove_All_Frequencies ( int nStreamIn )

Si_RT_DIS_Radio_Remove_All_Frequencies() removes all DIS radio frequncies from the list of received frequencies for nStreamIn.

Parameters

nStreamIn StreamIn ID

◆ Si_RT_DIS_Radio_Set_Gain()

bool CSRAPI::Si_RT_DIS_Radio_Set_Gain	(	int	nStreamIn,
		unsigned __int64	radio_frequency_Hz,
		double	gain_dB
	)

Si_RT_DIS_Radio_Set_Gain() sets the gain in dB of of the specified radio_frequency_Hz.

◆ Si_RT_DIS_Radio_Get_Gain()

double CSRAPI::Si_RT_DIS_Radio_Get_Gain	(	int	nStreamIn,
		unsigned __int64	radio_frequency_Hz
	)

Si_RT_DIS_Radio_Get_Gain() retrieves the gain in dB of the specified radio_frequency_Hz.

◆ Si_RT_DIS_Radio_Unblock_All()

bool CSRAPI::Si_RT_DIS_Radio_Unblock_All ( int nStreamIn )

Parameters

nStreamIn StreamIn ID

◆ EnvPlanes()

void CSRAPI::EnvPlanes	(	double	xp = `SC::RoomDim()/2.0`,
		double	xn = `-SC::RoomDim()/2.0`,
		double	yp = `SC::RoomDim()/2.0`,
		double	yn = `-SC::RoomDim()/2.0`,
		double	zp = `SC::RoomDim() -SC::LstHeight()`,
		double	zn = `-SC::LstHeight()`
	)

The EnvPlanes() function sets the locations of the planes (walls) in the rendered environment. The room model consists of a rectangular room with six walls. Each plane location is defined by the signed distance to the origin along the Cartesian axis to which the plane is perpendicular.

Warning: When using the room model, the user should ensure objects remain within the room.

Note: Hint = SHEnvPlane

See also: Environment Functions

Parameters

xp	positive x-axis plane location (meters)
xn	negative x-axis plane location (meters)
yp	positive y-axis plane location (meters)
yn	negative y-axis plane location (meters)
zp	positive z-axis plane location (meters)
zn	negative z-axis plane location (meters)

◆ EnvPlane()

void CSRAPI::EnvPlane	(	SCRvb	scRvb,
		double	distance
	)

The EnvPlane() function sets the distance of a room plane from the origin. For more information, see EnvPlanes().

Note: Hint = SHEnvPlane

See also: Environment Functions

Parameters

scRvb	plane identifier
distance	plane distance from origin (meters)

◆ EnvMaterial()

bool CSRAPI::EnvMaterial	(	SCRvb	scRvb,
		SCMat	scMat = `SC::MatNone`
	)

inline

The EnvMaterial() function sets the plane material for a given plane. Materials are rendered using a first-order IIR filter. The IIR filter responses approximate the absorption coefficients listed below. The material type MAT_NONE disables material processing for the given plane.

/// Absorption Coefficients (percentage absorbed energy):
///
/// Material                     125   250   500   1000  2000  4000 Hz
/// --------                     ----  ----  ----  ----  ----  ----
/// heavy carpet / foam rubber   0.08  0.24  0.57  0.69  0.71  0.73
/// concrete                     0.01  0.012 0.017 0.02  0.02  0.02
/// heavy glass                  0.18  0.06  0.04  0.03  0.02  0.02
/// 2 layer gypsum board         0.28  0.12  0.10  0.17  0.13  0.09
/// 1" thick wood with airspace  0.19  0.14  0.09  0.06  0.06  0.05
/// plaster on metal lath        0.14  0.10  0.06  0.05  0.04  0.03

Materials are identified by the SCMat constants.  Strings
corresponding to the SCMat constants are provided in the
MATERIAL_STRINGS define in slabdefs.h.

\return true = material type set, false = not set due to currently
rendering

\remark static setting
\note Hint = SHEnvMat
\sa Environment Functions

Parameters

scRvb	plane identifier (see SCRvb in slabdefs.h, RvbXP thru RvbZN)
scMat	material type identifier

References GetRenderTime().

◆ EnvBound()

double CSRAPI::EnvBound	(	Pos	scPos,
		double	v
	)

inline

Parameters

scPos	coordinate identifier
v	coordinate to bound

References GetEnvPlane().

◆ EnvBoundX()

double CSRAPI::EnvBoundX ( double x )

inline

Parameters

x	coordinate to bound

References GetEnvPlane().

Referenced by EnvBoundR().

◆ EnvBoundY()

double CSRAPI::EnvBoundY ( double y )

inline

Parameters

y	coordinate to bound

References GetEnvPlane().

Referenced by EnvBoundR().

◆ EnvBoundZ()

double CSRAPI::EnvBoundZ ( double z )

inline

Parameters

z	coordinate to bound

References GetEnvPlane().

Referenced by EnvBoundR().

◆ EnvBoundR()

double CSRAPI::EnvBoundR	(	double	az,
		double	el,
		double	r
	)

inline

Parameters

az	azimuth, radians
el	elevation, radians
r	coordinate to bound

References EnvBoundX(), EnvBoundY(), EnvBoundZ(), PolarToRect(), and RectToPolar().

◆ EnvLLHOrigin()

void CSRAPI::EnvLLHOrigin	(	double	lat,
		double	lon,
		double	height
	)

The EnvLLHOrigin() function sets the origin for converting latitude, longitude, and height (LLH) coordinates to slab3d's coordinate system. The slab3d coordinate system is similar a local ENU (East, North, Up) coordinate system where x,y,z is mapped: x = North y = -East z = Up

The values specified using EnvLLHOrigin() will be used for subsequent SrcLocateLLH() and LstPositionLLH() calls.

See also: SrcLocateLLH(), LstPositionLLH()

Parameters

lat	latitude (degrees, +90N to -90S)
lon	longitude (degrees, -180W to +180E)
height	height (meters)

◆ LstHRTFLoad()

bool CSRAPI::LstHRTFLoad	(	int	nHRTF,
		const char *	pName
	)

The LstHRTFLoad() function loads a Head-Related Transfer Function (HRTF) database. This database is used by some renderers for sound source spatialization. HRTFs loaded with LstHRTFLoad() can be freed with LstHRTFFree() if memory use is a concern. Otherwise, they will be freed when SRAPI is freed. A loaded HRTF is referenced by an integer ID from 0 to SC::MaxHRTF.

Returns: true = success, false = failure

See also: LstHRTFFree(), LstHRTF()

Parameters

nHRTF	HRTF ID, 0 to SC::MaxHRTF
pName	HRTF database filename

◆ LstHRTFFree()

void CSRAPI::LstHRTFFree ( int nHRTF )

The LstHRTFFree() function frees a previously loaded Head-Related Transfer Function (HRTF) database. HRTFs not freed by LstHRTFFree() will be freed when SRAPI is freed.

See also: LstHRTFLoad(), LstHRTF()

Parameters

nHRTF HRTF ID

◆ LstHRTF()

bool CSRAPI::LstHRTF	(	int	nHRTF = `-1`,
		int	nSrc = `-1`
	)

The LstHRTF() function selects the Head-Related Transfer Function (HRTF) database used to render the listener's head and ears. Typically, only the nHRTF parameter is specified. The nSrc parameter can be used to render different sound sources with different HRTFs. If nHRTF is -1, the internal default HRTF database is used (slab3d\hrtf\jdm.slh).

Returns: true = success, false = failure

See also: LstHRTFLoad(), LstHRTFFree()

Parameters

nHRTF	HRTF ID
nSrc	sound source ID

◆ LstHRTFHeader()

bool CSRAPI::LstHRTFHeader	(	int	nHRTF,
		HRTFHeader *	header
	)

The LstHRTFHeader() function retrieves HRTF database header information.

Returns: true = success, false = failure

See also: LstHRTFLoad()

Parameters

nHRTF	HRTF ID, -1 default HRTF, -2 current HRTF
header	struct to receive header data

◆ LstPosition()

void CSRAPI::LstPosition	(	double	x = `0.0`,
		double	y = `0.0`,
		double	z = `0.0`,
		double	yaw = `0.0`,
		double	pitch = `0.0`,
		double	roll = `0.0`
	)

The LstPosition() function positions the listener in world coordinates. The listener position is a six degree of freedom vector composed of x, y, z location components and yaw, pitch, roll orientation components.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

Note: Hint = SHLstPos

See also: LstSensorPos(), LstSensorOffset()

Parameters

x	x-axis location coordinate (meters)
y	y-axis location coordinate (meters)
z	z-axis location coordinate (meters)
yaw	yaw orientation coordinate (radians)
pitch	pitch orientation coordinate (radians)
roll	roll orientation coordinate (radians)

◆ LstPositionLLH()

void CSRAPI::LstPositionLLH	(	double	lat = `0.0`,
		double	lon = `0.0`,
		double	height = `0.0`,
		double	yaw = `0.0`,
		double	pitch = `0.0`,
		double	roll = `0.0`
	)

The LstPositionLLH() function positions the listener using latitude, longitude, and height coordinates. These will be mapped to slab3d x,y,z coordinates using the EnvLLHOrigin() values.

The orientation angles are aircraft angles which rotate the slab3d coordinate system 180 degrees about the x-axis (forward):
aircraft yaw = - slab3d yaw
aircraft pitch = - slab3d pitch

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index.

Note: Hint = SHLstPos

See also: EnvLLHOrigin(), SrcLocateLLH(), LstPosOwnshipLLH()

Parameters

lat	latitude (degrees, +90N to -90S)
lon	longitude (degrees, -180W to +180E)
height	height (meters)
yaw	aircraft yaw orientation (radians)
pitch	aircraft pitch orientation (radians)
roll	roll orientation (radians)

◆ LstPosOwnshipLLH()

void CSRAPI::LstPosOwnshipLLH	(	double	ownLat,
		double	ownLon,
		double	ownHeight,
		double	ownYaw,
		double	ownPitch,
		double	ownRoll,
		double	lstX,
		double	lstY,
		double	lstZ,
		double	lstYaw,
		double	lstPitch,
		double	lstRoll
	)

LstPosOwnshipLLH() positions the listener using the LLH coordinates and orientation of ownship and the listener's location and orientation inside of ownship. The location of ownship can refer to the COG, e.g., near rotor axis for a helicopter. The pilot's head can be offset from that point and, potentially, head tracked. This creates nested reference frames so that we need to transform the listener from ownship to world.

All orientation angles are aircraft angles which rotate the slab3d coordinate system 180 degrees about the x-axis (forward):
aircraft yaw = - slab3d yaw
aircraft pitch = - slab3d pitch
aircraft roll = slab3d roll
aircraft x = slab3d x
aircraft y = - slab3d y
aircraft z = - slab3d z
Listener ownship-relative translation set using the aircraft axes above.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index.

Note: Hint = SHLstPos

See also: EnvLLHOrigin(), SrcLocateLLH(), LstPositionLLH()

Parameters

ownLon	latitude (degrees, +90N to -90S)
ownHeight	longitude (degrees, -180W to +180E)
ownYaw	height (meters)
ownPitch	ownship yaw orientation (radians)
ownRoll	ownship pitch orientation (radians)
lstX	ownship roll orientation (radians)
lstY	ownship-relative x (meters)
lstZ	ownship-relative y (meters)
lstYaw	ownship-relative z (meters)
lstPitch	listener yaw orientation (radians)
lstRoll	listener pitch orientation (radians) listener roll orientation (radians)

◆ LstPosOwnship()

void CSRAPI::LstPosOwnship	(	double	ownX = `0.0`,
		double	ownY = `0.0`,
		double	ownZ = `0.0`,
		double	ownYaw = `0.0`,
		double	ownPitch = `0.0`,
		double	ownRoll = `0.0`,
		double	lstX = `0.0`,
		double	lstY = `0.0`,
		double	lstZ = `0.0`,
		double	lstYaw = `0.0`,
		double	lstPitch = `0.0`,
		double	lstRoll = `0.0`
	)

LstPosOwnship() positions the listener using the XYZ coordinates and orientation of ownship and the listener's location and orientation inside of ownship. The location of ownship can refer to the COG, e.g., near rotor axis for a helicopter. The pilot's head can be offset from that point and, potentially, head tracked. This creates nested reference frames so that we need to transform the listener from ownship to world.

All orientation angles are slab3d angles.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index.

Note: Hint = SHLstPos

See also: LstPosition(), LstPosOwnshipLLH()

Parameters

ownY	ownship x location (meters)
ownZ	ownship y location (meters)
ownYaw	ownship z location (meters)
ownPitch	ownship yaw orientation (radians)
ownRoll	ownship pitch orientation (radians)
lstX	ownship roll orientation (radians)
lstY	ownship-relative x (meters)
lstZ	ownship-relative y (meters)
lstYaw	ownship-relative z (meters)
lstPitch	listener yaw orientation (radians)
lstRoll	listener pitch orientation (radians) listener roll orientation (radians)

◆ LstPos()

void CSRAPI::LstPos	(	Pos	scPos,
		double	v
	)

The LstPos() function is a variation of the LstPosition() function but only sets one position coordinate.

Note: Hint = SHLstPos

See also: LstPosition()

Parameters

scPos	coordinate ID
v	coordinate value (meters or radians)

◆ LstSensorPos()

void CSRAPI::LstSensorPos	(	double	x,
		double	y,
		double	z,
		double	yaw,
		double	pitch,
		double	roll
	)

The LstSensorPos() function positions the listener using a sensor position. The center of the head is computed using the sensor offset.

Note: Hint = SHLstPos

See also: LstPosition(), LstSensorOffset()

Parameters

x	x-axis location coordinate (meters)
y	y-axis location coordinate (meters)
z	z-axis location coordinate (meters)
yaw	yaw orientation coordinate (radians)
pitch	pitch orientation coordinate (radians)
roll	roll orientation coordinate (radians)

◆ LstSensorOffset()

void CSRAPI::LstSensorOffset	(	double	x = `0.0`,
		double	y = `0.0`,
		double	z = `SC::SensorOffsetM()`
	)

The LstSensorOffset() function sets the x,y,z coordinate offsets of the head tracker sensor from the center of the head.

See also: LstSensorPos()

Parameters

x	x-axis sensor offset (meters)
y	y-axis sensor offset (meters)
z	z-axis sensor offset (meters)

◆ OutASIO()

SLABError CSRAPI::OutASIO	(	int	nDevice = `0`,
		int	nCh = `2`,
		int *	nChMap = `NULL`,
		int	nLen = `0`,
		bool	bSplit = `false`
	)

OutASIO() specifies ASIO as the device interface for sound output. Typically, the number of output channels is two for binaural headphone output. But, more channels can be specified if required for special-purpose Render Plugins. The default slab3d renderers simply zero-pad extra channels.

OutASIO() opens the ASIO device specified by nDevice. The size of the ASIO output buffer (and input buffer for SiAllocASIO()) is the "preferred" ASIO buffer size. This is an ASIO parameter set by the sound device driver. The SLABSound application can be used to view ASIO driver information.

ASIO is a trademark of Steinberg Soft- und Hardware GmbH.

Returns: SLABError

Remarks: static-state function
The API-to-display latency for ASIO ranges between the ASIOGetLatencies() output latency value plus one buffer length to the same value plus another buffer length (roughly 2*buf_length to 3*buf_length).

See also: GetASIOName(), GetASIOInfo()

Parameters

nDevice	ASIO device, 0 to SC::AsioDevices-1
nCh	number of output channels
nChMap	ASIO channel map
nLen	ASIO channel map length
bSplit	split stream flag

◆ OutDirectSound()

SLABError CSRAPI::OutDirectSound	(	int	nCh = `2`,
		int	nOut = `DS_BUFSIZE_OUT`,
		int	nWrite = `DS_BUFSIZE_WRITE`,
		bool	bSplit = `false`
	)

OutDirectSound() specifies DirectSound as the device interface for sound output. Typically, the number of output channels is two for binaural headphone output. But, more channels can be specified if required for special-purpose Render Plugins. The default slab3d renderers simply zero-pad extra channels.

The output device opened is the Windows preferred sound playback device set using the Windows Sounds and Multimedia Properties settings dialog (Audio | Sound Playback | Preferred device).

The larger the DirectSound output buffer, the longer the internal latency. If the buffer is too small, sample underflow occurs. The goal is to select the smallest buffer size possible while maintaining reliable sample output. For 16-bit, two-channel output, the size in bytes must be a multiple of 4.

The write buffer is written to and filled prior to writing to the DirectSound output buffer. For 16-bit, two-channel output, the size in bytes must be a multiple of 4*frame_size or 128 bytes for a frame size of 32 samples.

The write buffer exists to optimize DirectSound output buffer management. Writing to the DirectSound output buffer is more computationally expensive than writing to memory. Thus, it is beneficial to queue up some samples before writing to the DirectSound output buffer. How many samples to queue up, however, is not obvious.

Warning: Results vary between different DirectSound peripherals and drivers. Common problems include clicks'n'pops, frequent buffer underflow, and unsupported output (e.g. analog supported, SPDIF not supported).

Returns: SLABError

Remarks: static-state function

See also: Out Functions

Parameters

nCh	number of output channels
nOut	output buffer size (bytes)
nWrite	write buffer size (bytes)
bSplit	split stream flag

◆ OutWave()

SLABError CSRAPI::OutWave	(	int	nCh = `2`,
		bool	bSplit = `false`
	)

OutWave() specifies Waveform-Audio as the device interface for sound output. Typically, the number of output channels is two for binaural headphone output. But, more channels can be specified if required for special-purpose Render Plugins. The default slab3d renderers simply zero-pad extra channels. The device opened is set by the Windows Wave Mapper. The Waveform-Audio interface results in a fairly high latency.

Returns: SLABError

Remarks: static-state function

See also: Out Functions

Parameters

nCh	number of output channels
bSplit	split stream flag

◆ OutFile()

SLABError CSRAPI::OutFile	(	char *	pFilename,
		bool	bMemory = `false`,
		int	nCh = `2`,
		bool	bSplit = `false`
	)

OutFile() specifies a wave file as the destination of sound output. Typically, the number of output channels is two for binaural headphone output. But, more channels can be specified if required for special-purpose Render Plugins. The default slab3d renderers simply zero-pad extra channels.

If bMemory is false, samples are streamed to the file in real time. If bMemory is true, samples are streamed to memory. When rendering stops, the memory samples are saved to a file. This option creates a StreamOutMemory sample stream instead of a StreamOutFile.

Returns: SLABError

Remarks: static-state function
bMemory true is primarily for slab3d development. It is used to capture very small segments (a few seconds) of output. The memory management is not foolproof. Using this feature to capture large segments (several minutes) of slab3d output is not advised.

See also: Out Functions

Parameters

pFilename	output wave file
bMemory	buffer to memory before write flag
nCh	number of output channels
bSplit	split stream flag

◆ OutFree()

bool CSRAPI::OutFree ( )

OutFree() frees all sound output. This is the state after CSRAPI construction. Before initiating rendering, sound output must be selected using one of the output functions above. If more than one output function is called, an "output patch" is constructed.

Output Patch Example:

// primary output
OutASIO();
// bSplit = true, this output receives the same samples as the primary
// output;
// there is a maximum of three splits per primary output
OutFile( "out_split.wav",  false, 2, true  );
// bSplit = false, a second output is created for use by a render plugin,
// its use is render plugin-specific;
// there is a maximum of eight primary outputs
OutFile( "out_second.wav", false, 2, false );

OutFree() is only necessary when changing previously selected output.

Returns: true = success, false = can't free while rendering

Remarks: static-state function

See also: Out Functions

◆ WaitSuspend()

SLABError CSRAPI::WaitSuspend ( )

The WaitSuspend() function waits for the DSP component of slab3d to suspend waiting for ASIO output buffer space. WaitSuspend() can be used with WaitSwap() to reduce latency and latency variability. This technique only works with OutASIO().

Let's say you want to carefully sync a visual display event to a slab3d-rendered scene change. This can be done by placing the scene-modifying SRAPI call between WaitSuspend() and WaitSwap(). The visual display code follows the WaitSwap() function. The time from WaitSwap() to analog output should be about 2 * ASIO_buffer_size(ms). Also, this latency time should be relatively fixed (i.e., latency variability less than a millisecond).

If WaitSwap() and WaitSuspend() are not used, the SRAPI latency can fall anywhere between two and three times the ASIO buffer size (in ms). For an ASIO buffer size of 128 samples, this yields a latency variability of only 2.9ms. This is fine for many applications.

Returns: SLABError

Remarks: The ASIO output buffer size is often set with a utility provided by the sound device manufacturer.

See also: Output Functions, WaitSwap(), OutASIO()

◆ WaitSwap()

SLABError CSRAPI::WaitSwap ( )

The WaitSwap() function waits on an ASIO double-buffer swap. This call can be used with WaitSuspend() to reduce latency and latency variability. See WaitSuspend() for more information.

Returns: SLABError

See also: Output Functions, WaitSuspend(), OutASIO()

◆ GetASIOName()

char * CSRAPI::GetASIOName ( int nDevice )

inline

The GetASIOName() function returns an ASIO device driver name. SRAPI supports devices indexed 0 to SC::AsioDevices-1. The SLABSound application also provides ASIO information.

Returns: ASIO device driver name

See also: OutASIO(), GetASIOInfo()

Parameters

nDevice ASIO device number, 0 to SC::AsioDevices-1

◆ GetASIOInfo()

int CSRAPI::GetASIOInfo	(	int	nDriver,
		ASIOInfo *	pAsioInfo
	)

The GetASIOInfo() function fills an ASIOInfo struct for a given device.

Error return values:
0: none
1: function cannot be called while rendering
2: ASIO library failure
3: SRAPI ASIO driver names failure
4: no driver or driver didn't load
5: driver didn't init, device off or disconnected

Returns: 0 success, else error

See also: OutASIO(), GetASIOName()

Parameters

nDriver	ASIO device number, 0 to SC::AsioDevices-1
pAsioInfo	ASIOInfo struct

◆ GetUnderflows()

unsigned long CSRAPI::GetUnderflows ( )

The GetUnderflows() function returns the current number of sound output device underflows. This counter is reset each time rendering starts.

Returns: number of sound output underflows

◆ GetClips()

unsigned long CSRAPI::GetClips ( )

The GetClips() function returns the current number of sound output sample clips. This counter is reset each time rendering starts. For multiple outputs, this stat is for the first output allocated.

Returns: the number of sample output clips

◆ CallRate()

SLABError CSRAPI::CallRate ( double dUpdateRate = 120.0 )

The CallRate() function sets the Callback, Modifier, and Script update rate. The update rate will be normalized to a multiple of the frame size (32 samples) (e.g., an update rate of 120Hz with a render sample rate of 44100Hz yields an actual update rate of 125.28Hz).

If this function is called, it should be called after SampleRate() and prior to the Modifier functions, ScriptOpen(), or RenderStart().

Internally, the update order is script, modifiers, user callback.

Returns: true = success, false = failure

Remarks: static-state function

See also: CallPeriod(), CallTrueRate(), Callback()

Parameters

dUpdateRate callback update rate in Hz

◆ CallPeriod()

unsigned int CSRAPI::CallPeriod ( )

inline

The CallPeriod() function returns the callback period in samples corresponding to the CallRate() update rate.

Returns: update period in samples

See also: CallRate(), CallTrueRate()

◆ CallTrueRate()

double CSRAPI::CallTrueRate ( )

inline

The CallTrueRate() function returns the callback update rate in Hz corresponding to the frame-normalized CallPeriod().

dTrueRate = double( pScene->GetSampleRate() ) /

double( pSRAPI->CallPeriod() );

Returns: update rate in Hz

See also: CallRate(), CallPeriod()

◆ Callback()

void CSRAPI::Callback	(	bool()(void pData)	pCallback,
		void *	pData = `NULL`
	)

The Callback() function allows the user to specify a callback routine to be called from within the rendering frame update loop. This is primarily useful for actions requiring a high update rate (e.g., a custom trajectory) and/or for sound source sample synchronization (e.g., non-real-time rendering). This function and the user callback function are called from within a Lock()'d block. The callback should return true for success, false for failure.

Returns: none

See also: CallRate(), CallTrueRate(), CallPeriod()

Parameters

pCallback	address of user callback routine
pData	address of user data

◆ ModEnable()

void CSRAPI::ModEnable ( bool bEnable )

inline

The ModEnable() function enables or disables Modifier processing. Processing is disabled by default. Modifiers automatically modify SRAPI state (e.g., to create sound source trajectories). The Modifier update rate is the same as the Callback update rate.

Returns: none

See also: Modifier Functions, CallRate()

Parameters

bEnable true = enable, false = disable

◆ ModSrcLocate()

void CSRAPI::ModSrcLocate	(	int	nSrc,
		double	dX,
		double	dY,
		double	dZ,
		double	dRateX,
		double	dRateY,
		double	dRateZ
	)

The ModSrcLocate() function adds a SrcLocate() Modifier. It defines and starts a linear trajectory for a specified sound source.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

See also: Modifier Functions

Parameters

nSrc	sound source ID
dX	initial x-axis value (meters)
dY	initial y-axis value (meters)
dZ	initial z-axis value (meters)
dRateX	x-axis rate (meters/s)
dRateY	y-axis rate (meters/s)
dRateZ	z-axis rate (meters/s)

◆ ModSrcLocatePolar()

void CSRAPI::ModSrcLocatePolar	(	int	nSrc,
		double	dAz,
		double	dEl,
		double	dR,
		double	dRateAz,
		double	dRateEl,
		double	dRateR
	)

The ModSrcLocatePolar() function adds a SrcLocatePolar() Modifier. It defines and starts a polar trajectory for a specified sound source.

Remarks: Source-listener distances exceeding propagation delay line lengths will result in the max delay index. For the default 500ms delay line, this would occur for ranges exceeding 78 meters.

See also: Modifier Functions

Parameters

nSrc	sound source ID
dAz	initial azimuth value (radians)
dEl	initial elevation value (radians)
dR	initial range value (meters)
dRateAz	azimuth rate (radians/s)
dRateEl	elevation rate (radians/s)
dRateR	range rate (meters/s)

◆ ModSrcGainScalar()

void CSRAPI::ModSrcGainScalar	(	int	nSrc,
		float *	pfTable,
		int	nLength,
		double	dTime,
		bool	bLoop
	)

The ModSrcGainScalar() function modifies SrcGainScalar() using a table. The passed table is copied and no longer needed after this function is called.

Parameters

nSrc	sound source ID
pfTable	table
nLength	table length
dTime	time for one scan through table
bLoop	loop table (if false, modifier automatically removed once table completed)

◆ ModSiAllocFile()

bool CSRAPI::ModSiAllocFile	(	int	nStreamID,
		char *	pFilename,
		bool	bLoop,
		bool	bMemory,
		long	lStart,
		double	dPause
	)

The ModSiAllocFile() function adds an SiAllocFile() Modifier, changing the source stream once the previous stream ends. The previous stream is deleted. If the modifier is removed before the previous stream completes, the modifier's stream is deleted.

Returns: true = success, false = CSIFile allocation failed

Parameters

nStreamID	StreamIn ID
pFilename	wave file
bLoop	loop wave file
bMemory	memory-buffered file
lStart	sample start index
dPause	pause (seconds)

◆ ModStart()

bool CSRAPI::ModStart	(	SCMod	scMod,
		int	nSrc
	)

The ModStart() function starts a Modifier.

Returns: true = success, false = modifier or source not found

See also: Modifier Functions, SCMod constants

Parameters

scMod	modifier ID
nSrc	sound source ID

◆ ModStop()

bool CSRAPI::ModStop	(	SCMod	scMod,
		int	nSrc
	)

The ModStart() function stops a Modifier.

Returns: true = success, false = modifier or source not found

See also: Modifier Functions, SCMod constants

Parameters

scMod	modifier ID
nSrc	sound source ID

◆ ModRate()

bool CSRAPI::ModRate	(	SCMod	scMod,
		int	nSrc,
		double	dRateX,
		double	dRateY,
		double	dRateZ
	)

The ModRate() function adjusts a Modifier's rate of change.

Returns: true = success, false = modifier or source not found

See also: Modifier Functions

Parameters

scMod	modifier ID
nSrc	sound source ID
dRateX	new x-axis or azimuth rate (meters/s, radians/s)
dRateY	new y-axis or elevation rate (meters/s, radians/s)
dRateZ	new z-axis or range rate (meters/s)

◆ ModRemove()

bool CSRAPI::ModRemove	(	SCMod	scMod,
		int	nSrc = `-1`
	)

The ModRemove() function removes a Modifier. If scMod is ModAll, all Modifiers are removed.

Returns: true = success, false = modifier or source not found

See also: Modifier Functions

Parameters

scMod	modifier ID
nSrc	sound source ID

◆ SceneSave()

bool CSRAPI::SceneSave ( char * pFilename )

The SceneSave() function saves an XML scenefile (.scn).

The following state is saved:

<RenderChange>  GetRenderID()
<SetNSOffset>   GetNSOffset()
<SrcLocate>     GetSrcLoc()
<SrcEnable>     GetSrcEnable()
<SrcRefEnable>  GetSrcRefEnable()
<SrcGain>       GetSrcGain()
<SrcMute>       GetSrcMute()
<SrcRadius>     GetSrcRadius(), GetSrcSpread()
<SrcMixGain>    GetSrcMixGain()
<SrcMixReturn>  GetSrcMixGain()
<SrcMixHRTF>    GetSrcMixAuxEn(), GetSrcMixAuxSet()
<EnvPlanes>     GetEnvPlane()
<LstPosition>   GetLstPos()

Returns: true = success, false = failure

See also: SceneOpen()

Parameters

pFilename scenefile filename

◆ SceneOpen()

bool CSRAPI::SceneOpen ( char * pFilename )

The SceneOpen() function opens an XML scenefile (.scn).

The following elements are supported:

<RenderChange>        RenderChange()
<SetNSOffset>         SetNSOffset()
<SrcLocate>           SrcLocate()
<SrcLocatePolar>      SrcLocatePolar(), dDeg2Rad
<SrcEnable>           SrcEnable()
<SrcRefEnable>        SrcRefEnable()
<SrcGain>             SrcGain()
<SrcMute>             SrcMute()
<SrcRadius>           SrcRadius()
<SrcMixGain>          SrcMixGain()
<SrcMixReturn>        SrcMixGain()
<SrcMixHRTF>          SrcMixAux(), dDeg2Rad
<SrcStream>           SrcStream()
<SiAllocFile>         SiAllocFile()
<EnvPlanes>           EnvPlanes()
<LstPosition>         LstPosition(), dDeg2Rad
<ModSrcLocate>        ModSrcLocate()
<ModSrcLocatePolar>   ModSrcLocatePolar(), dDeg2Rad
<ModSiAllocFile>      ModSiAllocFile()
<ModStart>            ModStart()
<ModStop>             ModStop()
<ModRate>             ModRate(), dDeg2Rad
<User>                ScriptCallback() callback
<Time>                time index (only use with scripts)

Examples:

<SrcMixHRTF id="0" aux="0" enable="t" az="30" el="10" />
<SrcMixReturn id="0" aux="0" begin="0" end="1" g0="1.00" g1="1.00" />
<SrcMixGain id="0" begin="2" end="7" g2="0.50" g3="0.80" />
<SrcStream id="0" stream="0" ch="0" />
<!-- sample start optional for SiAllocFile but required for ModSiAllocFile -->
<SiAllocFile id="0" filename="voice.wav" loop="f" memory="f" start="9265152" />
<ModSiAllocFile id="0" filename="voice2.wav" loop="f" memory="f" start="0" pause="2.0" />

Returns: true = success, false = failure

See also: SceneSave(), ScriptOpen()

Parameters

pFilename scenefile filename

◆ ScriptEnable()

void CSRAPI::ScriptEnable ( bool bEnable )

inline

The ScriptEnable() function enables or disables XML script processing. Processing is disabled by default. Scripts specify SRAPI function calls occurring at various time indices.

Returns: none

See also: CallRate()

Parameters

bEnable true = enable, false = disable

◆ ScriptCallback()

void CSRAPI::ScriptCallback	(	bool()(void pData, int nArg, float f0, float f1, float f2, float f3)	pCallback,
		void *	pData = `NULL`
	)

inline

The ScriptCallback() function specifies a callback routine that is called when a "User" XML element is found in a slabscript file. The nArg callback parameter will be the argument ("arg" attribute) specified in the slabscript. It is best to use positive integers. 0 is used for non-script callbacks and negative integers are being reserved for potential future use. pData is user data passed to the callback. ScriptEnable( false ) can be called from within the callback to pause the script. This can be useful for interactive applications and app/script synchronization. To unpause, call ScriptEnable( true ).

Zero to four floats can be specified as additional parameters passed to the callback. The attribute names aren't used by SRAPI, so they can be used to describe the parameters. If a parameter isn't specified, the callback parameter will be 0.0f.

Example: <User arg="5" x="1.5" y="2.0" >

Returns: none

Parameters

pCallback	address of user callback routine
pData	address of user data

◆ ScriptOpen()

bool CSRAPI::ScriptOpen	(	char *	pFilename,
		bool	bScriptThread = `false`
	)

inline

The ScriptOpen() function opens a script file. If scripting is enabled and SRAPI is rendering, script processing begins immediately. If a pre-existing script exists, the current ScriptOpen() replaces it. ScriptOpen() is also the method used to rewind a script. Scripts use the same XML file format as SceneOpen() but with the addition of <Time> index elements. If an initial time index is omitted, it is assumed to be 0. The other supported elements are documented with SceneOpen().

By default, script processing occurs in the render thread. This is useful for tight synchronization and non-real-time rendering (slower or faster than real-time). If real-time (e.g., device I/O) artifacts are heard due to script operations, the script processing can be moved to its own thread using the bScriptThread parameter.

Script XML file example:

<?xml version="1.0" encoding="UTF-8"?>
<scenefile version="1.0">
  <SrcLocate id="0" x="1.00" y="1.00" z="0.00" />
  <Time seconds="1.0" />
  <SrcLocate id="0" x="2.00" y="1.00" z="0.00" />
</scenefile>

Scripting can also be used for API macro support by simply placing several function calls together.

Macro XML file example:

<?xml version="1.0" encoding="UTF-8"?>
<scenefile version="1.0">
  <SrcLocate id="0" x="1.00" y="1.00" z="0.00" />
  <SrcLocate id="1" x="1.00" y="-1.00" z="0.00" />
</scenefile>

SceneOpen() can be used in a similar way. ScriptOpen() uses a memory stream; SceneOpen() uses a file stream.

Warning: The script XML buffer is limited to 32768 bytes.

Returns: true = success, false = failure

See also: ScriptEnable(), ScriptFree(), ScriptMisses(), SceneOpen()

Parameters

pFilename	XML slabscript file (.sls)
bScriptThread	run script in own thread

◆ ScriptFree()

void CSRAPI::ScriptFree ( )

inline

The ScriptFree() function frees script memory.

Returns: none

◆ ScriptMisses()

unsigned int CSRAPI::ScriptMisses ( )

inline

The ScriptMisses() function returns the number of times the script thread missed an update. This can occur if a particularly lengthy or CPU-consuming script sequence occurs and/or if the render thread is heavily burdened. Often misses are perfectly acceptable given the update period relative to the required script timeline accuracy. The default CallRate() of 120 Hz can cause misses to steadily accumulate over time. Update rates in the neighborhood of 30 Hz appear to be better behaved.

Returns: number of script thread misses since last ScriptOpen()

See also: ScriptOpen(), CallRate()

◆ SetSampleRate()

bool CSRAPI::SetSampleRate ( long lSampleRate = SC::DefSampleRate )

inline

The SetSampleRate() function sets the render and output sample rates.

Returns: true = success, false = not set due to rendering

Remarks: static setting

See also: GetSampleRate()

Parameters

lSampleRate render and output sample rate (samples/s)

References GetRenderTime().

◆ SetResampler()

void CSRAPI::SetResampler	(	bool	bOversample = `true`,
		bool	bArbitrary = `true`
	)

inline

The SetResampler() function sets resampler parameters. These parameters are used when initializing stream input delay lines. This function can be called between SiAllocs if different resampler parameters are desired for different StreamIns.

bOversample indicates whether the delay lines should be oversampled. Oversampling the delay line reduces a slight lowpass effect introduced by linear sample interpolation, but increases computional load.

bArbitrary true selects a resampling algorithm that supports arbitrary resample factors. If false, the resample factors are limited to 1,2,4,8x. The limited algorithm is faster to init and can thus be useful for render-time stream allocation. The arbitrary factor algorithm can cause audible artifacts when allocating streams from a script.

Note: SiAllocSubmix() and SiAllocDISFreq()/SiAllocDISRadios() always use arbitrary factor resampling.

Parameters

bOversample	use oversampled delay line
bArbitrary	support arbitrary resample factors

◆ SetSmoothTime()

bool CSRAPI::SetSmoothTime ( double dSmoothTime = SC::SmoothTime() )

inline

The SmoothTime() function sets the time constant of slab3d's leaky integrator parameter smoothing (aka tracking) filter. This parameter adjusts how quickly the DSP parameters change in response to changing scene parameters.

A smooth time of zero yields the most responsive system, but audible artifacts (clicks, zippering) will likely be heard as scene parameters change. Large values (tens of milleseconds) yield audibly smooth systems, but may seem sluggish.

Returns: true = success, false = not set due to rendering

Remarks: static setting

See also: GetSmoothTime()

Parameters

dSmoothTime smoothing filter time constant (ms)

References GetRenderTime().

◆ SetFIRTaps()

bool CSRAPI::SetFIRTaps	(	int	nFIRTaps = `128`,
		int	nFIRTapsRef = `32`
	)

inline

The SetFIRTaps() function sets the number of FIR taps used when performing HRIR filtering. Since this is the most computationally intensive operation in the Spatial renderer, reducing the number of FIR taps can be used to free up computational resources. The tradeoff is audio fidelity. The HRIR filters are truncated when the requested taps are fewer than the HRIR database taps.

Returns: true = success, false = not set due to rendering

Remarks: static setting

See also: Simulation Functions

Parameters

nFIRTaps	number of direct path FIR taps
nFIRTapsRef	number of reflected path FIR taps

References GetRenderTime().

◆ SetDelayOut()

void CSRAPI::SetDelayOut ( int nDelay = 0 )

inline

The SetDelayOut() function sets the sound output delay in frames. This delay line is allocated by the Spatial renderer and can be inserted between the Spatial mixer and sound output. This allows the final sound output of SRAPI to be delayed up to SC.DelayOutMax().

Output delays can be useful for psychoacoustic studies and for synchronizing multimodal displays. When using ASIO output, SRAPI's latency can be quite low (a few ms). Thus, in an audio-visual virtual environment setting, the visual display will most likely lag the audio display. SetDelayOut() can lag the audio to sync the displays. Note, determining the proper delay requires a little effort. One method is to attach a digital storage oscilloscope to the serial port, sound output, and a photodetector placed in the upper-left corner of the video display. By writing to the serial port just prior to updating the audio-visual APIs, one can view the relative timing of API results on the oscilloscope. The slab3d XTime app implements this technique.

Setting the delay to 0 (default) disables the use of the output delay buffer (no samples in, no samples out). Thus, re-enabling delay can result in a very short playback of old sound data before the delay buffer is filled with new data.

The output delay in seconds:

out_delay = GetDelayOut() * GetFrameSize() / GetSampleRate()

See also: GetDelayOut(), GetDelayOutMax()

Parameters

nDelay output delay in frames

◆ SetLevelTimes()

void CSRAPI::SetLevelTimes	(	float	fAttack = `0.137f`,
		float	fRelease = `0.137f`
	)

inline

The SetLevelTimes() function sets the attack and release time constants for the level meters in the Spatial2 render plugin.

See also: GetSrcLevel(), SetSkipSilence()

Parameters

fAttack	attack time constant, seconds
fRelease	release time constant, seconds

References GetSampleRate().

◆ SetSkipSilence()

void CSRAPI::SetSkipSilence	(	float	fLevel = `0.050f`,
		float	fTime = `0.500f`,
		float	fFadeIn = `0.068f`
	)

inline

The SetSkipSilence() function sets the replay skip silence parameters. When using SrcReplay(), the user can catch up to now by skipping silence between the replay point and now. Once the sound level falls below the specified fLevel threshold for fTime seconds, sound samples are skipped until the fLevel threshold is exceeded. The sound level is the same level reported by GetSrcLevel() and the same time constants apply. When exiting skip silence mode, a linear fade in will be performed beginning at fFadeIn seconds before the exit point. The fFadeIn default of 68ms is based on a meter level attack time constant of 137ms. This function requires the Spatial2 plugin.

See also: SrcReplay(), SrcReplaySkip(), SetLevelTimes()

Parameters

fLevel	source level threshold, 0.0 to 1.0
fTime	time below level threshold, seconds
fFadeIn	fade in window, seconds

References GetSampleRate().

◆ SetNSOffset()

void CSRAPI::SetNSOffset ( double dB = -24.0 )

inline

The non-spatial gain offset can be used to match spatial/non-spatial output levels. This is useful when A/B-ing spatial and non-spatial rendering algorithms.

See also: SrcGain(), GetNSOffset(), GetNSScalar()

Parameters

dB	non-spatial gain offset, dB

◆ SetDefaults()

bool CSRAPI::SetDefaults ( )

The SetDefaults() function sets several acoustic scene parameters to their default values: SetSampleRate(), SetResampler(), SetFIRTaps(), SetSmoothTime(), SetNSOffset(), SrcLocate(), SrcEnable(), SrcRefEnable(), SrcRefOffset(), SrcGainScalar(), SrcMute(), SrcRadius(), SrcMixAux(), SrcMixGain(), EnvPlanes(), EnvMaterial(), LstPosition(), and LstSensorOffset().

◆ Reset()

void CSRAPI::Reset ( )

The Reset() function resets SRAPI state: rendering stopped, sources and outputs freed, render plugin set to RenderSpatial, callback rate set to default, callback function nullified, and modifiers and scripts disabled and freed.

Reset() is not called by the error handling code in an effort to preserve state. If a source error occurs, it might be necessary to call Reset() to eliminate the error.

Returns: none

See also: Rendering Functions, Error Functions

◆ SetSharedMemory()

bool CSRAPI::SetSharedMemory ( float * pFloats )

SetSharedMemory() copies an array of 32 floats to shared memory.

Returns: true = success, false = failure

◆ GetSharedMemory()

bool CSRAPI::GetSharedMemory ( float * pFloats )

GetSharedMemory() gets an array of 32 floats from shared memory.

Returns: true = success, false = failure

◆ LLHToSlab3d()

void CSRAPI::LLHToSlab3d	(	CoordLLH &	llh,
		CoordLinear &	xyz
	)

Parameters

xyz	WGS84 LLH cooridnate slab3d x,y,z coordinate

◆ ErrorString()

char * CSRAPI::ErrorString ( )

The ErrorString() function returns a string describing the current SRAPI error condition.

Returns: string describing the current SRAPI error condition (see ERROR_STRINGS in slabdefs.h)

See also: Error Functions

◆ ErrorStack()

char * CSRAPI::ErrorStack ( )

The ErrorStack() function is used to obtain detailed error information after an error occurs. It returns a string describing the error state at each point in the internal function calling sequence at the time of the error. This function is primarily for development and bug reporting.

Returns: string listing the error state at each point in the internal function calling sequence at the time of the last error

See also: Error Functions

◆ ErrorClear()

void CSRAPI::ErrorClear ( )

The ErrorClear() function clears the current SRAPI error. When SRAPI encounters an error, it remains in an error state until the user clears the error. In an error state, most SRAPI functions do nothing but return the current error. This simplifies error handling when calling several SRAPI functions in a row. Only the last function needs to be checked for error.

Returns: none

See also: Error Functions

◆ ErrorState()

bool CSRAPI::ErrorState ( )

The ErrorState() function returns the SRAPI error state. An error state exists once an error occurs and lasts until the error is cleared with ErrorClear.

Returns: true if SRAPI is in an error state. false if SRAPI is not in an error state

See also: Error Functions

◆ Error()

SLABError CSRAPI::Error ( )

The Error() function returns the current SRAPI error code. This error code state exists until the error is cleared with ErrorClear().

Returns: The current SRAPI error. Error returns ErrorNone if SRAPI is not in an error state.

See also: Error Functions

◆ LogName()

void CSRAPI::LogName ( char * pLogName )

The LogName() function specifies the file to use as a SRAPI log file. If this function is not called, no log file is created. By default, the log file will log error information, but it can also log user messages via LogEntry() and LogTime(). If the file already exists, new log entries are appended to the end of the file. LogName() will truncate an existing log to 2000 lines if the log length exceeds 2000 lines.

The log file is named pLogName with a ".log" suffix and placed in the executable directory.

Returns: none

See also: Log Functions

Parameters

pLogName name of SRAPI log file

◆ LogEntry()

void CSRAPI::LogEntry ( char * pLogEntry )

The LogEntry() function logs a user message in the SRAPI log file.

Returns: none

Remarks: The log file is opened and closed for each log entry.

See also: Log Functions

Parameters

pLogEntry user log message

◆ LogTime()

void CSRAPI::LogTime ( )

The LogTime() function logs the current system time in the SRAPI log file.

Returns: none

Remarks: The log file is opened and closed for each log entry.

See also: Log Functions

◆ SetTick()

void CSRAPI::SetTick ( bool bTickUp )

inline

The SetTick() function sets the parameter updating method. The default method is "frame", meaning the API parameters are converted to DSP rendering parameters the next DSP frame (typical frame length is 32 samples). "Tick" updating delays the update until the next Tick() function call. This can be useful for scene functions that are called more frequently than the desired update rate (e.g., a function called from a scroll control handler). Also, ticking allows a simulation app to control the simulation update rate while using CSRAPI to hold environment state. This function only impacts render-time functions.

Note: If an API parameter is used directly by a renderer without requiring an update, tick updating for that parameter will be identical to frame updating. This is the reason SrcEnable() and SrcRefEnable() do not support tick updating. Another example is source gain. GiGain() is used directly by the Mixer render plugin mix but the Mixer HRTF mix and the Spatial render plugin require an update. The tick method of updating is primarily intended for use with the Spatial plugin.

See also: Tick()

Parameters

bTickUp true = tick update, false = frame update

◆ Tick()

void CSRAPI::Tick ( )

inline

The Tick() function informs the SRAPI to convert API parameters to DSP rendering parameters. An update only occurs if a hint is set. Only the functions that set hints are tickable. Tick updating is enabled via SetTick().

See also: SetTick()

References HintClear(), and UpdateSet().

◆ Updated()

bool CSRAPI::Updated ( )

inline

The Updated() function checks if SRAPI scene parameters have been updated. It is used with Recalc() as follows:

m_pSRAPI->Lock();
if( m_pSRAPI->Updated() )
{
  m_pSRAPI->Recalc();
  if( !SceneToSigProc() )
  {
    m_pSRAPI->Unlock();
    return false;
  }
}
// any code that checks scene state should occur before unlock
m_pSRAPI->Unlock();

Where to place this code and how to use it is discussed further in the documentation for CRPlugIn::Process().

Returns: true if SRAPI scene updated, otherwise false

See also: Update Functions, Recalc(), CRPlugIn::Process()

◆ UpdateClear()

void CSRAPI::UpdateClear ( )

inline

The UpdateClear() function clears the update state. This is typically performed inside a render plugin by Recalc(). UpdateClear() is for render plugins that use updated scene state but do not use Recalc().

See also: Update Functions, Updated(), Recalc()

◆ UpdateSet()

void CSRAPI::UpdateSet ( )

inline

The UpdateSet() function sets update state. This is typically used by Recalc() to determine if recalc needed.

See also: Update Functions, Updated(), UpdateClear(), Recalc()

Referenced by Tick().

◆ UpdateWaitReset()

void CSRAPI::UpdateWaitReset ( )

inline

The UpdateWaitReset() function resets the update done event. This can be placed before a scene state function in order to use UpdateWait() to test for DSP update (scene parameters migrated to DSP parameters in a separate thread of execution).

See also: UpdateWait()

◆ UpdateWait()

bool CSRAPI::UpdateWait ( )

inline

The UpdateWait() function waits for a scene-to-DSP update to be complete. The underlying event is automatically reset.

Returns: true = signaled, false = timeout

See also: UpdateSet()

◆ SetUpdateWaitMode()

void CSRAPI::SetUpdateWaitMode ( bool bUpdateWaitMode = false )

inline

The SetUpdateWaitMode() function sets UpdateWait mode. Some functions support this mode where a DSP update is waited upon before the function returns. A typical use of this mode is to wait for listener-source azimuth, elevation, and range to be updated. This mode is false by default and is reset by SetDefaults().

Mode supported by: SrcEnable(), SrcLocate(), SrcLocateLLH(), SrcLocatePolar(), SrcLoc(), LstPosition(), LstPositionLLH(), LstPosOwnshipLLH(), LstPosOwnship(), LstPos(), LstSensorPos()

See also: Update Functions, UpdateWait(), Recalc(), GetUpdateWaitMode()

◆ Recalc()

void CSRAPI::Recalc ( )

The Recalc() function recalculates the scene, computing new reflection image locations and listener-relative geometric quantities from updated SRAPI scene parameters. It is typically paired with the Updated() function. See the Updated() documentation for a code fragment demonstrating the use of Updated() and Recalc().

Note: Recalc() will typically be called from within a Lock()'ed CRPlugIn::Process() override. In that override, all scene API access should occur in one locked block (e.g., see the Spatial render plugin file rspatial.cpp).

See also: Update Functions, Updated(), CRPlugIn::Process()

◆ Lock()

void CSRAPI::Lock ( )

inline

Lock() enters a thread critical section. Most scene functions lock internally. Lock() can be called explicitly to lock a series of calls that set or check scene state. This function must have a corresponding Unlock(). Internally, Lock() synchronizes the app thread (user's setting of scene parameters) and the DSP thread (renderer's use of scene parameters (e.g., CRPlugIn::Process())). Users can use Lock() to lock a simulation update routine that runs in its own thread.

See also: Unlock()

Referenced by SetPIVar().

◆ Unlock()

void CSRAPI::Unlock ( )

inline

Unlock() exits a thread critical section. This function must be paired with Lock().

See also: Lock()

Referenced by SetPIVar().

◆ GetSrcAlloc()

bool CSRAPI::GetSrcAlloc ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcStreamID()

int CSRAPI::GetSrcStreamID ( int nSrc )

inline

The GetSrcStreamID() function gets the sound source's StreamID.

Returns: StreamID or -1 for unassigned stream; error values: -2 unallocated source, -3 invalid source ID

See also: Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcLoc()

double CSRAPI::GetSrcLoc	(	int	nSrc,
		Pos	scPos
	)

inline

The GetSrcLoc() function gets a source location coordinate (x,y,z).

Returns: source location coordinate in meters

See also: Query Functions, SrcLocate()

Parameters

nSrc	sound source ID
scPos	coordinate ID (x,y,z)

Referenced by GetOwnSrcHBearing().

◆ GetSrcAz()

double CSRAPI::GetSrcAz ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcEl()

double CSRAPI::GetSrcEl ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcRange()

double CSRAPI::GetSrcRange ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcLocType()

int CSRAPI::GetSrcLocType ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcPolar()

CoordPolar * CSRAPI::GetSrcPolar ( int nSrc )

Parameters

nSrc	sound source ID

◆ GetSrcGain()

double CSRAPI::GetSrcGain ( int nSrc )

inline

The GetSrcGain() function gets the dB gain of the requested source. If the internal linear gain scalar is 0, the return value is SC::GainMutedB().

Returns: gain in dB

See also: SrcGain(), SrcGainScalar(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcGainScalar()

float CSRAPI::GetSrcGainScalar ( int nSrc )

inline

The GetSrcGainScalar() function gets the linear gain scalar of the requested source.

Returns: linear gain scalar

See also: SrcGain(), SrcGainScalar(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcMute()

bool CSRAPI::GetSrcMute ( int nSrc )

inline

The GetSrcMute() function gets the mute state of the requested source.

Returns: true if muted, false if not muted

See also: SrcMute(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcRadius()

double CSRAPI::GetSrcRadius ( int nSrc )

inline

The GetSrcRadius() function gets the radius of the requested source.

Returns: radius in meters

See also: SrcRadius(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcSpread()

double CSRAPI::GetSrcSpread ( int nSrc )

inline

The GetSrcSpread() function gets the spreading loss of the requested source.

Returns: spreading loss

See also: SrcRadius(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcDistance0dB()

double CSRAPI::GetSrcDistance0dB ( int nSrc )

inline

The GetSrcDistance0dB() function gets the spreading loss 0dB reference of the requested source.

Returns: spreading loss 0dB reference

See also: SrcRadius(), Query Functions

Parameters

nSrc	sound source ID

◆ GetSrcEnable()

bool CSRAPI::GetSrcEnable ( int nSrc )

inline

Parameters

nSrc	sound source ID

◆ GetSrcRefEnable()

bool CSRAPI::GetSrcRefEnable	(	int	nSrc,
		SCRvb	scRvb
	)

inline

Parameters

nSrc	sound source ID
scRvb	reflection identifier (see SCRvb in slabdefs.h)

◆ GetSrcMixGain()

float CSRAPI::GetSrcMixGain	(	int	nSrc,
		int	nIndex,
		int	nAux = `-1`
	)

inline

Parameters

nSrc	sound source ID
nIndex	output index
nAux	-1 = for sound source, 0,1 = for aux channel

◆ GetSrcMixAuxEn()

bool CSRAPI::GetSrcMixAuxEn	(	int	nSrc,
		int	nAux
	)

inline

Parameters

nSrc	sound source ID
nAux	0,1 aux channel

◆ GetSrcMixAuxSet()

double CSRAPI::GetSrcMixAuxSet	(	int	nSrc,
		int	nAux,
		int	nSet
	)

inline

Parameters

nSrc	sound source ID
nAux	0,1 aux channel
nSet	setting (0 = az, 1 = el)

◆ GetSrcReplay()

float CSRAPI::GetSrcReplay ( int n )

inline

The GetSrcReplay() function returns the replay time of the sound source in samples. This time is added to the propagation delay in the Spatial2 renderer. Thus, using large delay lines, the delay line can also serve as a replay buffer. Note, SrcReplaySkip() will change the replay time index.

Returns: replay time of the sound source in samples

See also: SrcReplay(), SrcReplaySkip(), Query Functions

Parameters

n	sound source ID

◆ GetSrcLevel()

float CSRAPI::GetSrcLevel ( int n )

inline

The GetSrcLevel() function returns the source level meter value. The source level meter is an envelope follower with attack and release times specified by SetLevelTimes(). It is similar to a VU meter but on a linear scale. Attack and release times of 137ms should approximate the 300ms rise and fall times of a standard VU meter. This function requires the Spatial2 render plugin.

Returns: source level meter value (0 to 1.0)

See also: SetLevelTimes(), Query Functions

Parameters

n	sound source ID

◆ GetSrcNum()

int CSRAPI::GetSrcNum ( )

inline

The GetSrcNum() function returns the number of sound sources.

Returns: number of sound sources

See also: Query Functions

◆ GetEnvSndSpd()

double CSRAPI::GetEnvSndSpd ( )

inline

The GetEnvSndSpd() function returns the speed of sound.

Returns: speed of sound (meters/s)

See also: Query Functions

◆ GetEnvPlane()

double CSRAPI::GetEnvPlane ( SCRvb scRvb )

inline

The GetEnvPlane() function returns the distance of a room plane from the origin.

Returns: room plane distance from origin in meters

See also: EnvPlanes(), EnvPlane()

Parameters

scRvb plane identifier

Referenced by EnvBound(), EnvBoundX(), EnvBoundY(), and EnvBoundZ().

◆ GetEnvMaterial()

SCMat CSRAPI::GetEnvMaterial ( SCRvb scRvb )

inline

The GetEnvMaterial() function returns the material type of a surface.

Returns: surface material type

See also: Query Functions, EnvMaterial(), GetEnvMatCoeffs()

Parameters

scRvb surface identifier (see SCRvb in slabdefs.h)

◆ GetEnvMatCoeffs()

StMatCoeffs * CSRAPI::GetEnvMatCoeffs	(	SCRvb	scRvb,
		long	fs
	)

The GetEnvMatCoeffs() function returns the material filter coefficients for the specified surface and sample rate.

Returns: pointer to material filter coefficients

See also: Query Functions, GetEnvMaterial(), EnvMaterial()

Parameters

scRvb	surface identifier (see SCRvb in slabdefs.h)
fs	sample rate

◆ GetLstPos()

double CSRAPI::GetLstPos ( Pos scPos )

inline

The GetLstPos() function returns a listener position coordinate.

Returns: listener position coordinate (meters, radians)

See also: LstPosition()

Parameters

scPos coordinate ID

◆ GetOwnPos()

double CSRAPI::GetOwnPos ( Pos scPos )

inline

The GetOwnPos() function returns an ownship position coordinate.

Returns: ownship position coordinate (meters, radians)

See also: LstPosOwnship(), LstPosOwnshipLLH()

Parameters

scPos coordinate ID

Referenced by GetOwnSrcHBearing().

◆ GetOwnSrcHBearing()

void CSRAPI::GetOwnSrcHBearing	(	int	n,
		CoordPolar &	polar
	)

inline

Parameters

n	sound source ID

References CoordPolar::az, CoordPolar::el, GetOwnPos(), GetSrcLoc(), and CoordPolar::r.

◆ GetOwnSrcBearing()

void CSRAPI::GetOwnSrcBearing	(	int	n,
		CoordPolar &	polar
	)

Parameters

n	sound source ID

◆ GetHRTFAllocated()

bool CSRAPI::GetHRTFAllocated ( int nHRTF )

inline

Parameters

nHRTF HRTF ID

◆ GetRenderID()

int CSRAPI::GetRenderID ( )

inline

The GetRenderID() function returns the current Render ID.

Returns: Render ID

See also: Query Functions, RenderID()

◆ GetRenderTime()

bool CSRAPI::GetRenderTime ( )

inline

The GetRenderTime() function returns true if rendering.

Returns: true if rendering, false if not

See also: Query Functions

Referenced by EnvMaterial(), SetFIRTaps(), SetSampleRate(), and SetSmoothTime().

◆ GetUpdateWaitMode()

bool CSRAPI::GetUpdateWaitMode ( )

inline

The GetUpdateWaitMode() function returns DSP UpdateWait mode. Some functions support this mode by waiting on a DSP update before the function returns. A typical use of this mode is to wait for listener-source azimuth, elevation, and range to be updated.

See also: Query Functions, Update Functions, SetUpdateWaitMode()

◆ GetSmoothTime()

double CSRAPI::GetSmoothTime ( )

inline

The GetSmoothTime() function returns the DSP parameter smoothing filter time constant.

Returns: DSP parameter smoothing filter time constant (milliseconds)

See also: Query Functions, SetSmoothTime()

◆ GetSampleRate()

long CSRAPI::GetSampleRate ( )

inline

The GetSampleRate() function returns the sample rate.

Returns: sample rate (samples/s)

See also: Query Functions, SetSampleRate()

Referenced by GetDelayOutMax(), SetLevelTimes(), and SetSkipSilence().

◆ GetFIRTaps()

int CSRAPI::GetFIRTaps ( )

inline

The GetFIRTaps() function returns the number of direct path HRIR FIR taps.

Returns: number of direct path HRIR FIR taps

See also: Query Functions, SetFIRTaps()

◆ GetFrameSize()

int CSRAPI::GetFrameSize ( )

inline

The GetFrameSize() function returns the frame size in samples.

Returns: frame size (samples)

See also: Query Functions

Referenced by GetDelayOutMax().

◆ GetDelayOut()

int CSRAPI::GetDelayOut ( )

inline

The GetDelayOut() function returns the audio output delay in frames.

The output delay in seconds:

out_delay = GetDelayOut() * GetFrameSize() / GetSampleRate()

Returns: output delay (frames)

See also: Query Functions, GetDelayOutMax(), SetDelayOut()

◆ GetDelayOutMax()

int CSRAPI::GetDelayOutMax ( )

inline

The GetDelayOutMax() function returns the maximum audio output delay in frames.

The target maximum output delay in seconds is SC::DelayOutMax(). The true maximum will be equal to this value or slightly higher.

The true maximum output delay in seconds:

max_out_delay = GetDelayOutMax() * GetFrameSize() / GetSampleRate()

Returns: maximum audio output delay (frames)

See also: Query Functions, GetDelayOut(), SetDelayOut(), SC::DelayOutMax()

References GetFrameSize(), and GetSampleRate().

◆ GetOutCh()

int CSRAPI::GetOutCh ( )

inline

The GetOutCh() function returns the number of output channels. The default number of output channels is 2.

Returns: number of output channels

See also: Query Functions, SetOutCh()

◆ GetLevelAttack()

float CSRAPI::GetLevelAttack ( )

inline

The GetLevelAttack() function returns the level meter attack gain corresponding to the level meter attack time constant.

Returns: level meter attack gain, 0.0 to 1.0

See also: SetLevelTimes(), GetSrcLevel(), GetLevelRelease()

◆ GetLevelRelease()

float CSRAPI::GetLevelRelease ( )

inline

The GetLevelRelease() function returns the level meter release gain corresponding to the level meter release time constant.

Returns: level meter release gain, 0.0 to 1.0

See also: SetLevelTimes(), GetSrcLevel(), GetLevelAttack()

◆ GetSkipLevel()

float CSRAPI::GetSkipLevel ( )

inline

The GetSkipLevel() function returns the skip silence sound level threshold.

Returns: skip silence sound level threshold, 0.0 to 1.0

See also: SetSkipSilence()

◆ GetSkipTime()

int CSRAPI::GetSkipTime ( )

inline

The GetSkipTime() function returns the skip silence time threshold.

Returns: skip silence time threshold in samples

See also: SetSkipSilence()

◆ GetSkipFadeIn()

int CSRAPI::GetSkipFadeIn ( )

inline

The GetSkipFadeIn() function returns the skip silence fade in time.

Returns: skip silence fade in time in samples

See also: SetSkipSilence()

◆ GetNSScalar()

float CSRAPI::GetNSScalar ( )

inline

The GetNSScalar() function gets the non-spatial offset linear gain scalar.

Returns: non-spatial offset linear gain scalar

See also: SetNSOffset(), Query Functions

◆ GetNSOffset()

double CSRAPI::GetNSOffset ( )

inline

The GetNSOffset() function gets the non-spatial offset in dB.

Returns: non-spatial offset in dB

See also: SetNSOffset(), Query Functions

◆ GetExeDir()

char * CSRAPI::GetExeDir ( )

inline

The GetExeDir() gets the executable directory (without a trailing backslash).

Returns: pointer to _MAX_PATH char buffer

◆ GetPerf()

double CSRAPI::GetPerf ( )

inline

The Perf() function returns the current value of the performance counter in seconds. Perf() is a diagnostic function used to timestamp events.

Returns: Performance counter time stamp in seconds.

◆ SetPIVar()

void CSRAPI::SetPIVar	(	int	nIndex,
		float	fValue
	)

inline

The SetPIVar() function sets a user plugin variable. These variables allow plugin developers to extend SRAPI with their own parameters. There are PIVARNUM float plugin variables that can be used for plugin input with SetPIVar() or output with GetPIVar().

Remarks: Setting a plugin variable sets an update flag that can be checked with PIVarUpdated(). The scene update flag checked by Updated() is not set.

See also: SetPIVarRange(), GetPIVar()

Parameters

nIndex	plugin variable index
fValue	plugin variable value

References Lock(), and Unlock().

◆ SetPIVarRange()

void CSRAPI::SetPIVarRange	(	int	nIndex,
		float *	pValues,
		int	nCount
	)

The SetPIVarRange() function sets a range of user plugin variables. See the SetPIVar() function for more information.

See also: SetPIVar(), GetPIVar()

Parameters

nIndex	base plugin variable index
pValues	array of plugin variable values
nCount	number of plugin variables to set

◆ SetPIStatus()

bool CSRAPI::SetPIStatus	(	unsigned long	lStatus,
		bool	bBlock = `false`
	)

inline

The SetPIStatus() function sets the user plugin status variable. This variable can used in a variety of ways. For example, a flag could be set indicating that a certain PIVar has been set. If the flag is not set, the plugin could use a default value instead of using the PIVar.

Remarks: Setting plugin status does not set a scene update flag.

Returns: For blocking calls, false = timeout, true = signaled.

See also: GetPIStatus(), SetPIStatusReset(), PICmdArg()

Parameters

lStatus	for status info, commands, etc.
bBlock	block on plugin status reset

◆ SetPIStatusReset()

void CSRAPI::SetPIStatusReset ( )

inline

The SetPIStatusReset() function resets the user plugin status variable and unblocks a blocked SetPIStatus() call. This function is used by a render plugin to signal that the plugin has read and is finished with the status and plugin variables.

See also: GetPIStatus(), SetPIStatus()

◆ PIVarUpdated()

bool CSRAPI::PIVarUpdated ( )

inline

The PIVarUpdated() function checks if a Plugin Variable has been updated. This enables functionality similar to Recalc() for an extended API.

Returns: true if PIVar updated, otherwise false

See also: SetPIVar(), SetPIVarRange()

◆ PIVarUpdateClear()

void CSRAPI::PIVarUpdateClear ( )

inline

The PIVarUpdateClear() clears the Plugin Variable updated flag. Call this function in your plugin after you've updated your processing variables in response to PIVarUpdated().

See also: PIVarUpdated()

◆ GetPIVar()

float CSRAPI::GetPIVar ( int nIndex )

inline

The GetPIVar() function gets a user plugin variable. These variables allow plugin developers to extend SRAPI with their own parameters.

Returns: plugin variable

See also: GetPIStatus(), SetPIVar(), SetPIVarRange()

Parameters

nIndex plugin variable index

◆ GetPIStatus()

unsigned long CSRAPI::GetPIStatus ( )

inline

The GetPIStatus() function gets the plugin status variable. This parameter can be used to pass status information to a user plugin. Users can use this variable however they like, but one method is to pack a one unsigned byte command and a three unsigned byte command argument into the unsigned long status variable. These can be retrieved using GetPIStatusCmd() and GetPIStatusArg().

Returns: plugin variable status

See also: SetPIStatus(), GetPIStatusCmd(), GetPIStatusArg()

◆ GetPIStatusCmd()

unsigned long CSRAPI::GetPIStatusCmd ( )

inline

The GetPIStatusCmd() function gets the plugin status variable command. This is simply the upper unsigned byte of the status variable left in the upper byte of the unsigned long.

Returns: plugin variable status

See also: SetPIStatus(), GetPIStatus(), GetPIStatusArg()

◆ GetPIStatusArg()

unsigned long CSRAPI::GetPIStatusArg ( )

inline

The GetPIStatusArg() function gets the plugin status variable argument. This is simply the lower three unsigned bytes of the status variable.

Returns: plugin variable status

See also: SetPIStatus(), GetPIStatus(), GetPIStatusCmd()

◆ ResetImages()

void CSRAPI::ResetImages ( )

inline

The ResetImages() function resets the sound image list. This function must be called before iterating through sound images with NextImage() or NextSource().

See also: Image Functions, NextImage(), NextSource()

◆ NextImage()

void CSRAPI::NextImage ( )

inline

The NextImage() function advances to the next sound image (source or reflection) in the sound image list. Immediately after calling this function, call GiEmpty() to check if the image is valid. If it is, the Gi* and Si* functions can be used to access the scene parameters of the image. If the image is not valid, the end of the image list has been reached.

See also: Image Functions, ResetImages(), NextSource(), GiEmpty()

References GetNextImage().

◆ NextSource()

void CSRAPI::NextSource ( )

inline

The NextSource() function advances to the next sound source in the sound image list. Immediately after calling this function, call GiEmpty() to check if the source is valid. If it is, the Gi* and Si* functions can be used to access the scene parameters of the source. If the source is not valid, the end of the image list has been reached.

See also: Image Functions, ResetImages(), NextImage(), GiEmpty()

References GetNextSource().

◆ GiEmpty()

bool CSRAPI::GiEmpty ( )

inline

The GiEmpty() function checks if the image list is empty. This function should be called immediately after NextImage() or NextSource().

Returns: true if the image list is empty, otherwise false

See also: Image Functions, NextImage(), NextSource()

◆ GiIn() [1/2]

float CSRAPI::GiIn ( float fIndex )

inline

The GiIn() function returns a sample from a sound image's input delay line. The samples at indices 0 to GetFrameSize()-1 correspond to the current frame of input samples at a pick-up point adjacent to the sound source. Using this frame of samples ignores sound propagation through the environment. To implement time-of-arrival effects such as Doppler shift, ITD, and early reflections, one calculates the time-of-arrival and indexes into the delay line accordingly.

The float indexed version of this routine provides fractional indexing, the integer indexed version does not.

Warning: For performance reasons, delay line index and valid image checks are not performed. The user must make sure to not overflow the input delay line (see GiDelayLength()). Also, this function should only be called when the image list is indexing a valid image (see NextImage(), NextSource()).

Returns: float input sample

See also: Image Functions, GiIn( int nIndex ), GiDelayLength()

Parameters

fIndex fractional index of input sample

◆ GiIn() [2/2]

float CSRAPI::GiIn ( int nIndex )

inline

The GiIn() function returns a sample from a sound image's input delay line. For details, see the float indexed version of this routine.

For implementations that do not require fractional indexing of the delay line, this routine is slightly faster.

Returns: short input sample

See also: Image Functions, GiIn( float fIndex ), GiDelayLength()

Parameters

nIndex index of input sample

◆ GiDelayLength()

float CSRAPI::GiDelayLength ( )

inline

The GiDelayLength() function returns a sound image's input delay line length in samples.

Returns: delay line length in samples

See also: Image Functions, GiIn()

◆ GiEnabled()

bool CSRAPI::GiEnabled ( )

inline

The GiEnabled() function checks if a sound image is enabled. Disabled images should not be rendered.

Returns: true if sound image enabled, otherwise false

See also: Image Functions, SrcEnable(), SrcRefEnable()

◆ GiSrcLocType()

int CSRAPI::GiSrcLocType ( )

inline

The GiSrcLocType() function returns the SrcLocate type. See SC struct SrcLoc-prefixed constants.

Returns: SrcLocate type

See also: Image Functions, SrcLocate(), SrcLocateRel(), SrcLocatePan()

◆ GiGain()

float CSRAPI::GiGain ( )

inline

The GiGain() function returns the scalar gain of the sound image. This gain corresponds to the dB or scalar gain set using SRAPI. If the image is a reflection, the gain of the corresponding sound source is returned.

Returns: scalar gain of the sound image

See also: Image Functions, SrcGain()

◆ GiGainL()

float CSRAPI::GiGainL ( )

inline

The GiGainL() function returns the left scalar pan gain of the sound image.

Returns: left scalar pan gain of the sound image

See also: Image Functions, SrcLocatePan()

◆ GiGainR()

float CSRAPI::GiGainR ( )

inline

The GiGainR() function returns the right scalar pan gain of the sound image.

Returns: right scalar pan gain of the sound image

See also: Image Functions, SrcLocatePan()

◆ GiRadius()

double CSRAPI::GiRadius ( )

inline

The GiRadius() function returns the sound source radius.

Returns: sound source radius (meters)

See also: Image Functions, SrcRadius()

◆ GiSpread()

double CSRAPI::GiSpread ( )

inline

The GiSpread() function returns the sound source spread.

Returns: sound source spread

See also: Image Functions, SrcRadius()

◆ GiDistance0dB()

double CSRAPI::GiDistance0dB ( )

inline

The GiDistance0dB() function returns the sound source spread 0dB reference.

Returns: sound source spread 0dB reference

See also: Image Functions, SrcRadius()

◆ GiX()

double CSRAPI::GiX ( )

inline

The GiX() function returns the x-coordinate of the sound image. For reflections, this value is computed using an image model.

Returns: x-coordinate of the sound image (meters)

See also: Image Functions, SrcLocate()

◆ GiY()

double CSRAPI::GiY ( )

inline

The GiY() function returns the y-coordinate of the sound image. For reflections, this value is computed using an image model.

Returns: y-coordinate of the sound image (meters)

See also: Image Functions, SrcLocate()

◆ GiZ()

double CSRAPI::GiZ ( )

inline

The GiZ() function returns the z-coordinate of the sound image. For reflections, this value is computed using an image model.

Returns: z-coordinate of the sound image (meters)

See also: Image Functions, SrcLocate()

◆ GiAz()

double CSRAPI::GiAz ( )

inline

The GiAz() function returns the listener-relative azimuth of the sound image.

Returns: listener-relative azimuth of the sound image (radians)

See also: Image Functions

◆ GiEl()

double CSRAPI::GiEl ( )

inline

The GiEl() function returns the listener-relative elevation of the sound image.

Returns: listener-relative elevation of the sound image (radians)

See also: Image Functions

◆ GiRange()

double CSRAPI::GiRange ( )

inline

The GiRange() function returns the image-listener range.

Returns: image-listener range (meters)

See also: Image Functions

◆ GiReplay()

float CSRAPI::GiReplay ( )

inline

The GiReplay() function returns the sound source replay time in samples.

Returns: sound source replay time in samples

See also: Image Functions, SrcReplay()

◆ GiFIRn()

int CSRAPI::GiFIRn ( )

inline

The GiFIRn() function returns the SRAPI-specified number of FIR taps for the HRIR filter operation. This can be ignored or used for another purpose by renderers that do not perform an HRIR FIR operation. The default FIRn value for reflections is 1/4 the FIRn for the direct path. This reserves more CPU resources for the direct path, causing the direct path to be rendered at a higher fidelity than the reflections.

Returns: number of FIR taps

See also: Image Functions, FIRPoints()

◆ GiHRTF() [1/2]

void CSRAPI::GiHRTF	(	float	fGain,
		float *	pfHRIRL,
		float *	pfHRIRR,
		float *	pfITDL,
		float *	pfITDR
	)

inline

The GiHRTF() function gets the HRIR and ITD for the image. Internally, the GiAz() and GiEl() values are used to index into the HRTF database. The number of HRIR taps retrieved is specified by GiFIRn(). If the az,el index is not found in the HRTF database, linear interpolation is used to generate the HRIR pair and ITD from the four nearest neighbors.

See also: Image Functions, GiAz(), GiEl(), GiFIRn()

Parameters

fGain	scalar gain applied to HRIR taps
pfHRIRL	left HRIR
pfHRIRR	right HRIR
pfITDL	left ITD (lag or zero)
pfITDR	right ITD (lag or zero)

◆ GiHRTF() [2/2]

void CSRAPI::GiHRTF	(	double	dAz,
		double	dEl,
		int	nFIRPts,
		float	fGain,
		float *	pfHRIRL,
		float *	pfHRIRR,
		float *	pfITDL,
		float *	pfITDR
	)

inline

The GiHRTF() function gets an az,el HRIR and ITD from the image HRTF.

See also: Image Functions

Parameters

dAz	azimuth, radians
dEl	elevation, radians
nFIRPts	number of HRIR points
fGain	scalar gain applied to HRIR taps
pfHRIRL	left HRIR
pfHRIRR	right HRIR
pfITDL	left ITD (lag or zero)
pfITDR	right ITD (lag or zero)

◆ GiRefID()

SCRvb CSRAPI::GiRefID ( )

inline

The GiRefID() function returns the reflection ID of the image. This will either be -1 for the direct path or one of the SCRvb constants in slabdefs.h.

Returns: reflection ID

See also: Image Functions, Planes

◆ GiStruct()

ImageStruct * CSRAPI::GiStruct ( )

inline

The GiStruct() function returns the image struct pointer. In general, this function should be avoided. It is intended for special cases, e.g., plugin modification of an image struct field.

Returns: image struct pointer

See also: Image Functions

◆ GiData()

void * CSRAPI::GiData ( )

inline

The GiData() function returns the plugin image data pointer. See SiData() for a discussion of plugin image data.

Returns: plugin image data pointer

See also: Image Functions, SiData()

◆ SiData()

void CSRAPI::SiData ( void * pData )

inline

The SiData() function sets the plugin image data pointer. Image data is data allocated by the plugin and attached to the image via SiData(). This data is typically allocated in the plugin override of CRPlugIn::Begin() and freed in the override of CRPlugIn::End(). Examples of image data are FIR and IIR memory data and tracked DSP parameters (e.g. delay line indices, FIR taps).

See also: Image Functions, GiData()

Parameters

pData address of plugin image data

◆ OutSample()

bool CSRAPI::OutSample	(	float	fSample,
		int	nOut = `0`
	)

inline

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

Parameters

fSample	+/-1.0-normalized sample output
nOut	output identifier

◆ OutPad()

void CSRAPI::OutPad ( int nOut = 0 )

inline

The OutPad() zeros-out remaining channels in the output buffer.

See also: OutSample()

Parameters

nOut	output identifier (see OutSample())

◆ MsgHandler()

bool CSRAPI::MsgHandler	(	UINT	msg,
		WPARAM	wParam,
		LPARAM	lParam
	)

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ XmlApiElement()

HRESULT CSRAPI::XmlApiElement ( CXML * pxml )

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ XmlApi()

bool CSRAPI::XmlApi ( IStream * stream )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ OutAdd()

SLABError CSRAPI::OutAdd	(	CSSO *	pSSO,
		bool	bSplit
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ErrorHandle()

SLABError CSRAPI::ErrorHandle ( SLABError )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ProcStop()

DSPError CSRAPI::ProcStop ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ InitPlugIns()

bool CSRAPI::InitPlugIns ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ RPlugInEnumDLL()

void CSRAPI::RPlugInEnumDLL ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ModUpdate()

bool CSRAPI::ModUpdate ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ModAdd()

ModStruct * CSRAPI::ModAdd ( SCMod scMod )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ModFree()

void CSRAPI::ModFree ( ModStruct * pMod )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ModDelete()

ModStruct * CSRAPI::ModDelete	(	ModStruct *	pMod,
		ModStruct *	pModPre
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ SetOutCh()

void CSRAPI::SetOutCh ( int nChannels = 2 )

inlineprivate

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ GetSampleBits()

int CSRAPI::GetSampleBits ( )

inlineprivate

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageAlloc()

ImageSrc * CSRAPI::ImageAlloc ( int nSrcID )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageStream()

void CSRAPI::ImageStream	(	ImageSrc *	pSrc,
		int	nStreamID,
		CSSI *	pSSI,
		int	nCh
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageListFree()

void CSRAPI::ImageListFree ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageInit()

void CSRAPI::ImageInit	(	ImageStruct *	pImage,
		SCRvb	refID,
		int	nFIRPts
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageInitSrc()

void CSRAPI::ImageInitSrc	(	ImageSrc *	pSrc,
		int	nSrcID,
		CHRTF *	pHRTF
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageInitRef()

void CSRAPI::ImageInitRef	(	ImageRef *	pRef,
		ImageSrc *	pSrc
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ ImageModel()

void CSRAPI::ImageModel ( ImageRef * pRef )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ F3DP()

void CSRAPI::F3DP	(	ImageStruct *	pImage,
		double	dListenerC[3],
		double	dListenerFLT[][3]
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ DetachStreamIn()

bool CSRAPI::DetachStreamIn	(	ImageSrc *	pSrc,
		int	nStreamID,
		int	nCh
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ SiReplace()

SLABError CSRAPI::SiReplace	(	int	n,
		CSSI *	pSSI
	)

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ GetNextImage()

ImageStruct * CSRAPI::GetNextImage ( )

inlineprivate

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

Referenced by NextImage().

◆ GetNextSource()

ImageSrc * CSRAPI::GetNextSource ( )

inlineprivate

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

Referenced by NextSource().

◆ CallbackInternal()

bool CSRAPI::CallbackInternal ( )

private

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

◆ CallbackStatic()

static bool __cdecl CSRAPI::CallbackStatic ( void * pParam )

staticprivate

The OutSample() function outputs a sample to the output buffer. The output buffer samples are left-right-interleaved and channel-interleaved. If multiple outputs exist, nOut can be used to select the output for writing. See CSRAPI::OutFree() for an output patch example that uses multiple outputs.

Returns: true = success, false = sample value clipped

See also: OutPad()

Public Member Functions

Static Public Member Functions

Sample Output Functions (Render Plugin API)

Detailed Description

Constructor & Destructor Documentation

◆ CSRAPI()

◆ ~CSRAPI()

Member Function Documentation

◆ SetLinks()

◆ RenderStart()

◆ RenderChange()

◆ RenderStop()

◆ RenderBatch()

◆ RenderEventPrepare()

◆ RenderEvent()

◆ RenderEnum()

◆ RenderID()

◆ SetNotify()

◆ SrcGetID()

◆ SrcAlloc()

◆ SrcStream()

◆ SrcFree()

◆ SrcRadius()

◆ SrcLocate()

◆ SrcLoc()

◆ SrcLocatePolar()

◆ SrcLocateLLH()

◆ SrcLocateRel()

◆ SrcLocatePan()

◆ SrcGain()

◆ SrcGainScalar()

◆ SrcMute()

◆ SrcReplay()

◆ SrcReplaySkip()

◆ SrcEnable()

◆ SrcRefEnable()

◆ SrcRefOffset()

◆ SrcMixGain()

◆ SrcMixAux()

◆ SiGetID()

◆ SiAllocFile()

◆ SiAllocMemory()

◆ SiAllocUrl()

◆ SiAllocGen()

◆ SiAllocUser()

◆ SiAllocASIO()

◆ SiAllocWave()

◆ SiAllocSubmix()

◆ SiAllocDISRadio()

◆ SiAllocDISFreq()

◆ SiAllocDISRadios()

◆ SiAlloc_RT_DIS_Radio()

◆ SiFree()

◆ SiFreeAll()

◆ SiStreamIn()

◆ SiDisSetID()

◆ SiDisGetID()

◆ SiDisGetFreq()

◆ SiDisGetPort()

◆ SiDisSetFreq()

◆ SiDisSolo()

◆ SiDisGetSoloID()

◆ DMGetRadioNum()

◆ DMGetRadio()

◆ DMGetRadioID()

◆ DMGetRadioFreq()

◆ DMGetRadioPooled()

◆ DMGetFreqNum()

◆ DMGetFreq()

◆ Si_RT_DIS_Radio_Set_UDP_Receiver_Port()

◆ Si_RT_DIS_Radio_Get_UDP_Receiver_Port()

◆ Si_RT_DIS_Radio_Add_Frequency()

◆ Si_RT_DIS_Radio_Remove_Frequency()

◆ Si_RT_DIS_Radio_Remove_All_Frequencies()

◆ Si_RT_DIS_Radio_Set_Gain()

◆ Si_RT_DIS_Radio_Get_Gain()

◆ Si_RT_DIS_Radio_Unblock_All()

◆ EnvPlanes()

◆ EnvPlane()

◆ EnvMaterial()