CSRAPI Class Reference

SLAB Render API. More...

List of all members.

Public Member Functions

SRAPI Construction

CSRAPI ()

allocates a CSRAPI object

Render Functions

SLABError RenderStart (int nID=RENDER_SPATIAL, bool bAutoStop=true, bool bAsync=true)

starts rendering

SLABError RenderChange (int nID)

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 (int nID, 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

int RenderID (char *pName)

returns the Render ID corresponding to a renderer's name

SLABError SetNotify (HWND hWnd, WPARAM wParam)

sets the notification window and notification message

Source Functions

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

void SrcRadius (int nSrc, double dRadius=0.1, double dSpread=1.0)

sets the radius of a sound source

void SrcLocate (int nSrc, double x=0.0, double y=0.0, double z=0.0)

sets the location of a sound source

void SrcLoc (int nSrc, Pos pos, double v)

sets the location of a sound source using one coordinate

void SrcLocatePolar (int nSrc, double az, double el, double r)

sets the location of a sound source relative to the origin

void SrcLocateRel (int nSrc, double az, double el, double r)

sets the location of a sound source relative to listener

void SrcGain (int nSrc, double dDB)

sets the gain of a sound source in dB

void SrcGainScalar (int nSrc, float fScalar=0.0)

sets the gain of a sound source using a linear scalar

void SrcMute (int nSrc, bool bMute=false)

mutes or unmutes a sound source

void SrcReplay (int nSrc, float fSeconds)

sets the replay time of the sound source in seconds (Spatial2)

void SrcReplaySkip (int nSrc)

enters replay skip silence mode (Spatial2)

void SrcEnable (int nSrc, bool bEnable=false)

enables or disables rendering of a sound source

void SrcRefEnable (int nSrc, int nRef=RVB_ALL, bool bEnable=false)

enables or disables a sound source's reflection

void SrcRefOffset (int nSrc, int nRef=RVB_ALL, bool bRefOffset=false, double x=0.0, double y=0.0, double z=0.0)

enables or disables reflection offsets

void SrcMixGain (int nSrc, int nBegin, int nEnd, float *fGains, int nAux=-1)

sets "Mixer" gains

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

sets "Mixer" aux send parameters

StreamIn Functions

SLABError SiAllocFile (int nStreamIn, char *pFilename, bool bLoop=true, bool bMemory=false, HWND hwndNotify=NULL, WPARAM wparamNotify=0)

allocates a wave file StreamIn

SLABError SiAllocUrl (int nStreamIn, const char *pUrl, const char *pDir, bool bLoop=false, HWND hwndNotify=NULL, WPARAM wparamNotify=0, int nPreBuf=1, long lDownBytes=8192, long lReadBytes=8192)

allocates a URL StreamIn

SLABError SiAllocGen (int nStreamIn, char *pDir=NULL)

allocates a signal generator StreamIn

SLABError SiAllocUser (int nStreamIn, int nSamples, int nCh, float **pBufPtr, HANDLE *pEventSwap)

allocates a user StreamIn

SLABError SiAllocASIO (int nStreamIn, int nCh=1, int *nChMap=NULL, int nLen=0)

allocates an ASIO device StreamIn

SLABError SiAllocWave (int nSrc)

allocates a Waveform-Audio device StreamIn

SLABError SiAllocVoIP (int nStreamIn, int nPort=5000, int nID=0)

allocates a VoIP StreamIn

SLABError SiAllocSubmix (int nStreamIn, CSSIList *pSSIList)

allocates a submix StreamIn

SLABError SiAllocDISRadio (int nStreamIn, int nPort, char *strID="", int nSilence=DEF_DISR1INT, int nPreBuf=DEF_DISR1PB, bool nRT=false)

allocates a DIS radio StreamIn

SLABError SiAllocDISFreq (int nStreamIn, unsigned long long ullFreq=0)

allocates a DIS frequency StreamIn

SLABError SiAllocDISRadios (int nNum, int nPort, int nSilence=DEF_DISR1INT, int nPreBuf=DEF_DISR1PB, bool bRT=false)

allocates multiple DIS radios for SiAllocDISFreq()

void SiFree (int nStreamIn)

frees an individual StreamIn

void SiFreeAll ()

frees all StreamIns

CSSI * SiStreamIn (int nStreamIn)

returns a slabwire StreamIn (CSSI) pointer

Si CSSI Wrapper Functions (see also slabwire docs)

StreamType SiType (int nStreamIn)

returns stream type, see CSSI::SSInStreamType()

bool SiPause (int nStreamIn)

pause stream, see CSSI::SSInPause()

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

SiGen CSIGen Wrapper Functions (see also slabwire docs)

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

Environment Functions

void EnvPlanes (double xp=dRoomDim/2.0, double xn=-dRoomDim/2.0, double yp=dRoomDim/2.0, double yn=-dRoomDim/2.0, double zp=dRoomDim-dLstHeight, double zn=-dLstHeight)

sets the locations of the room planes

void EnvPlane (Planes plane, double distance)

sets the location of a room plane

bool EnvMaterial (int nPlane, MaterialType matType=MAT_NONE)

sets the plane material for a given plane

double EnvBound (Pos pos, 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

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

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 LstPos (Pos pos, 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=dSENSOROFFSETm)

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

void 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 GetASIOChIn (int nDevice)

returns the number of input channels on an ASIO device

int GetASIOChOut (int nDevice)

returns the number of output channels on an ASIO 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, double dPause)

adds a SiAllocFile() Modifier

bool ModStart (IDMOD idMod, int nSrc)

starts a Modifier

bool ModStop (IDMOD idMod, int nSrc)

stops a Modifier

bool ModRate (IDMOD idMod, int nSrc, double dRateX, double dRateY, double dRateZ)

adjusts a Modifier's rate of change

bool ModRemove (IDMOD idMod, 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)

opens an XML slabscript file (.sls)

void ScriptFree ()

frees script memory

Miscellaneous Functions

bool SetSampleRate (long lSampleRate=44100)

sets the render and output sample rate

void SetResampler (bool bOversample=true, bool bArbitrary=true)

sets resampler parameters

bool SetSmoothTime (double dSmoothTime=15.0)

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 SetDelayIn (int nDelay=500)

sets the sound source input delay line length

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

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

double GetSrcLoc (int nSrc, Pos pos)

gets a source location coordinate

Polar * GetSrcRel (int nSrc)

gets the listener-relative location of the requested source

bool GetSrcLocRel (int nSrc)

returns true if source is a listener-relative source

Polar * GetSrcPolar (int nSrc)

returns the polar coordinates of source

double GetSrcGain (int nSrc)

gets the dB gain 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

bool GetSrcEnable (int nSrc)

gets enable state of source

bool GetSrcRefEnable (int nSrc, int nRef)

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 (Planes plane)

gets the location of a room plane

MaterialType GetEnvMaterial (int n)

returns the material type of a surface

StMatCoeffs * GetEnvMatCoeffs (int n, long fs)

returns material filter coefficients

bool GetEnvBoundMove ()

true if bound function changed coordinate

double GetLstPos (Pos pos)

returns a listener position coordinate

double GetLstX ()

listener x axis coordinate, meters

double GetLstY ()

listener y axis coordinate, meters

double GetLstZ ()

listener z axis coordinate, meters

double GetLstYaw ()

listener yaw coordinate, radians

double GetLstPitch ()

listener pitch coordinate, radians

double GetLstRoll ()

listener roll coordinate, radians

bool GetHRTFAllocated (int nHRTF)

returns true if HRTF allocated

int GetRenderID ()

returns current Render ID

bool GetRenderTime ()

returns true if rendering

double GetSmoothTime ()

returns the DSP parameter smoothing filter time constant

long GetSampleRate ()

returns the sampling rate

int GetFIRTaps ()

returns the number of direct path HRIR FIR taps

int GetFrameSize ()

returns the frame size in samples

int GetDelayIn ()

returns the input delay line length in ms

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

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

bool GiEnabled ()

gets the sound image enabled flag

float GiGain ()

gets the scalar gain of the sound image

double GiRadius ()

returns the sound source radius

double GiSpread ()

returns the sound source spread

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

Planes 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

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

Static Public Member Functions

slab3d Installation

static bool SetLinks ()

creates a slab3d Start Menu folder

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

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 (IDRender) 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

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

SLABError CSRAPI::RenderStart	(	int	nID = `RENDER_SPATIAL`,
		bool	bAutoStop = `true`,
		bool	bAsync = `true`
	)

The RenderStart() function initiates rendering. nID specifies either a pre-existing Render ID (e.g., RENDER_SPATIAL, RENDER_DIOTIC (see IDRender)) 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() message. 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:

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

RENDER_DICHOTIC: 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().

RENDER_DIOTIC: 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.

RENDER_MONOTIC_L: 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.

RENDER_MONOTIC_R: 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:

	nID	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

SLABError CSRAPI::RenderChange ( int nID )

The RenderChange() function changes the current Render Plugin. nID specifies either a pre-existing Render ID (e.g., RENDER_SPATIAL, RENDER_DIOTIC) 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:

nID

render plugin ID

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

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.

SLABError CSRAPI::RenderEventPrepare	(	int	nID,
		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:

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

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

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

int 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

SLABError CSRAPI::SetNotify	(	HWND	hWnd,
		WPARAM	wParam
	)

The SetNotify() function sets the notification window and notification message used by SRAPI to notify the user's thread of render-time events. Currently, the user thread is only notified when a render-time error occurs or when all playback completes (RenderStart() AutoStop).

If developing a GUI application, a simple way to create and handle a notification message ID is to add an invisible dummy button and message handler using Visual Studio's Resource View.

Returns:: SLABError

Remarks:: static-state function

See also:: Error Functions, RenderStart()

Parameters:

	hWnd	the user's window for receiving notification messages
	wParam	the message ID sent to the user's notification window

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 MAX_SRC. This is simply a lookup index, so these need not be sequential. Sources do consume CPU, however, so only allocate the number of sources you need. 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(), SiAlloc Functions

Parameters:

nSrc

sound source ID

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

nSrc 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

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

void CSRAPI::SrcRadius	(	int	nSrc,
		double	dRadius = `0.1`,
		double	dSpread = `1.0`
	)

The SrcRadius() function sets the radius of the sound source. The dRadius and dSpread parameters affect the spherical spreading loss model which controls the rate at which source gain decreases as the source-listener range increases.

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 / dRadius)^2)^(-dSpread/2)

By setting dRadius = dINTERAURALm/2 and dSpread = 1, 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 mentioned 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	radius of sound source (meters)
	dSpread	source spread exponent (see formula)

void 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:: Due to sound sample delay line length limitations, the world should not be considered infinite. For the default 500ms delay line, the coordinate values should not exceed +/- 45 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)

void CSRAPI::SrcLoc	(	int	nSrc,
		Pos	pos,
		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
	pos	coordinate ID
	v	coordinate value (meters)

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

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

Remarks:: Due to sound sample delay line length limitations, the world should not be considered infinite. For the default 500ms delay line, the range coordinate value should not exceed 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)

void 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:: Due to sound sample delay line length limitations, the world should not be considered infinite. For the default 500ms delay line, the coordinate values should not exceed +/- 45 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)

void 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.

Remarks:: Source gain is one of two API gain parameters when using slab3d signal generation. The source generator gain specified by the SrcGen function is applied in the signal generator, before the input delay line. Source gain is applied after the input delay line, inside the Render Plugin.

Note:: Hint = SHSrcGain

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

Parameters:

	nSrc	sound source ID
	dDB	gain, dB

void 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

void 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

void 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

void 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

void 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

void CSRAPI::SrcRefEnable	(	int	nSrc,
		int	nRef = `RVB_ALL`,
		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
	nRef	reflection identifier (see Planes in slabdefs.h)
	bEnable	if true, the reflection is enabled, if false, the reflection is disabled

void CSRAPI::SrcRefOffset	(	int	nSrc,
		int	nRef = `RVB_ALL`,
		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
	nRef	reflection identifier (see Planes in 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

void 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

void 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

SLABError CSRAPI::SiAllocFile	(	int	nStreamIn,
		char *	pFilename,
		bool	bLoop = `true`,
		bool	bMemory = `false`,
		HWND	hwndNotify = `NULL`,
		WPARAM	wparamNotify = `0`
	)

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.

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 your available RAM). This option creates a StreamInMemory sample stream instead of a StreamInFile.

The RenderStart() AutoStop feature can be used to enable application notification of playback completion. This form of notification only occurs after all StreamIns have completed. If notification is desired for a one-shot StreamIn alone, the hwndNotify and wparamNotify parameters can be used to specify a window and message for file done notification. This form of notification is completely independent from the AutoStop feature.

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
	hwndNotify	one-shot SrcFile done
	wparamNotify	one-shot SrcFile done

SLABError CSRAPI::SiAllocUrl	(	int	nStreamIn,
		const char *	pUrl,
		const char *	pDir,
		bool	bLoop = `false`,
		HWND	hwndNotify = `NULL`,
		WPARAM	wparamNotify = `0`,
		int	nPreBuf = `1`,
		long	lDownBytes = `8192`,
		long	lReadBytes = `8192`
	)

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.

The RenderStart() AutoStop feature can be used to enable application notification of playback completion. This form of notification only occurs after all StreamIns have completed. If notification is desired for a one-shot StreamIn alone, the hwndNotify and wparamNotify parameters can be used to specify a window and message for file done notification. This form of notification is completely independent from the AutoStop feature.

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.

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
	hwndNotify	one-shot done notify window
	wparamNotify	one-shot done notify message
	nPreBuf	number of buffers to download before playback
	lDownBytes	size of download buffer in bytes
	lReadBytes	size of read buffer in bytes

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

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

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

Parameters:

	nStreamIn	StreamIn ID
	pDir	generator plugin dir

SLABError CSRAPI::SiAllocUser	(	int	nStreamIn,
		int	nSamples,
		int	nCh,
		float **	pBufPtr,
		HANDLE *	pEventSwap
	)

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.

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

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

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().

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

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

Parameters:

	nStreamIn	StreamIn ID
	nCh	number of input channels
	nChMap	channel map
	nLen	channel map length

SLABError CSRAPI::SiAllocWave ( int nSrc )

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.

See also:: SrcStream()

Parameters:

nSrc

StreamIn ID

SLABError CSRAPI::SiAllocVoIP	(	int	nStreamIn,
		int	nPort = `5000`,
		int	nID = `0`
	)

SiAllocVoIP() listens on port nPort for a VoIP connection.

nPort is the port on which to listen for VoIP connections. If nID is set to -1, a new session (thread and port) is created for the VoIP connection. In this case, the port acts as an ID. This is termed a session-per-connection configuration.

nID is the ID of the incoming VoIP connection this StreamIn will connect to. When allocating StreamIns, the first VoIP StreamIn allocated with a positive ID creates a VoIP session (thread and port). Thereafter, all positive ID VoIP StreamIns will use that same session and port (i.e., nPort is ignored).

-1: session-per-connection, slabwire StreamInVoipPort (CSIVoipPort) stream
>= 0: slabwire StreamInVoipID (CSIVoipID) stream

For StreamInVoipID StreamIns, the following CSIVoipID functions might be of use (see SiStreamIn()):

SetID() - sets the VoIP transmitter ID
GetID() - gets the VoIP transmitter ID

The slab3d application SLABCall demonstrates how to configure a VoIP connection for use with slab3d.

See also:: SrcStream(), SiStreamIn()

Parameters:

	nStreamIn	StreamIn ID
	nPort	VoIP listening port
	nID	connection ID

SLABError CSRAPI::SiAllocSubmix	(	int	nStreamIn,
		CSSIList *	pSSIList
	)

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().

See also:: SrcStream(), SiFreeAll()

Parameters:

	nStreamIn	StreamIn ID
	pSSIList	slabwire SSI (sample stream input) list

SLABError CSRAPI::SiAllocDISRadio	(	int	nStreamIn,
		int	nPort,
		char *	strID = `""`,
		int	nSilence = `DEF_DISR1INT`,
		int	nPreBuf = `DEF_DISR1PB`,
		bool	nRT = `false`
	)

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 "". CDISManager can be used to query available IDs. Use "auto" to have a radio automatically assigned when one becomes available.

nSilence is the time interval used to detect DIS channel silence. DIS packets are not sent for silence. A DIS StreamIn streams zeroes if a DIS packet has not arrived during this interval.

nPreBuf specifies the number of zeroes to pre-buffer in the DIS buffer. This provides a look-ahead for the silence detection and provides buffering for going in and out of silence detect mode.

bRT is a flag indicating real-time sound output status. If set, this enables a low-latency DIS buffering algorithm. nPreBuf can be on the order of tens of milliseconds versus hundreds. nSilence is ignored.

Warning:: Do not use bRT with non-real-time sound output. 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.

The following CSIDISRadio functions might be of interest (see SiStreamIn()):

SetID() - sets the radio ID of a slabwire DIS radio object
GetID() - gets the DIS radio ID
GetFreq() - gets the DIS radio frequency in Hertz
GetPort() - gets the UDP port number
Pooled() - returns true if radio is in a frequency pool
Soloed() - returns true if radio soloed

See also:: SrcStream(), SiAllocDISFreq(), CDISManager class, SiStreamIn()

Parameters:

	nStreamIn	StreamIn ID
	nPort	DIS listening port (e.g., 3000)
	strID	radio ID (e.g., "100.104.1.1")
	nSilence	silence detection threshold, default = 525 ms
	nPreBuf	pre-buffered zeroes, default = 600 ms
	nRT	real-time sound output

SLABError CSRAPI::SiAllocDISFreq	(	int	nStreamIn,
		unsigned long long	ullFreq = `0`
	)

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().

The following CSIDISFreq functions might be of interest (see SiStreamIn()):

SetFreq() - sets the slabwire radio frequency in Hertz
GetFreq() - gets the slabwire radio frequency in Hertz
Solo() - soloes a DIS radio in a frequency pool

See also:: SrcStream(), SiAllocDISRadios(), SiAllocDISRadio(), CDISManager class, SiStreamIn()

Parameters:

	nStreamIn	StreamIn ID
	ullFreq	DIS frequency

SLABError CSRAPI::SiAllocDISRadios	(	int	nNum,
		int	nPort,
		int	nSilence = `DEF_DISR1INT`,
		int	nPreBuf = `DEF_DISR1PB`,
		bool	bRT = `false`
	)

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().

If SRAPI sound output is real-time (e.g., device versus file), then the bRT parameter can be used to greatly reduce the DIS buffering latency. In this instance, nPreBuf can be tens of milliseconds versus hundreds (nSilence is ignored).

Warning:: Do not use bRT with non-real-time sound output. 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()

Parameters:

	nNum	number of DIS radios to allocate
	nPort	DIS listening port (e.g., 3000)
	nSilence	silence detection threshold, default = 525 ms
	nPreBuf	pre-buffered zeroes, default = 600 ms
	bRT	real-time sound output

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

void CSRAPI::SiFreeAll ( )

SiFreeAll() frees all StreamIns.

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

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

CSSI* CSRAPI::SiStreamIn ( int nStreamIn )

SiStreamIn() returns a slabwire StreamIn (CSSI) pointer. In general, SRAPI users should use one of the Si*() wrapper functions.

Parameters:

nStreamIn

StreamIn ID

void CSRAPI::EnvPlanes	(	double	xp = `dRoomDim/2.0`,
		double	xn = `-dRoomDim/2.0`,
		double	yp = `dRoomDim/2.0`,
		double	yn = `-dRoomDim/2.0`,
		double	zp = `dRoomDim-dLstHeight`,
		double	zn = `-dLstHeight`
	)

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)

void CSRAPI::EnvPlane	(	Planes	plane,
		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:

	plane	plane identifier
	distance	plane distance from origin (meters)

bool CSRAPI::EnvMaterial	(	int	nPlane,
		MaterialType	matType = `MAT_NONE`
	)			`[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 MaterialType enum. Strings corresponding to the MaterialType enum values can be found in the MATERIAL_STRINGS define in slabdefs.h.

Returns:: true = material type set, false = not set due to currently rendering

Remarks:: static setting

Note:: Hint = SHEnvMat

See also:: Environment Functions

Parameters:

	nPlane	plane identifier (see Planes enum in slabdefs.h, RVB_XP thru RVB_ZN)
	matType	material type identifier

References GetRenderTime().

double CSRAPI::EnvBound	(	Pos	pos,
		double	v
	)			`[inline]`

Parameters:

	pos	coordinate identifier
	v	coordinate to bound

References GetEnvPlane().

double CSRAPI::EnvBoundX ( double x ) [inline]

Parameters:

x

coordinate to bound

References GetEnvPlane(), RVB_XN, and RVB_XP.

Referenced by EnvBoundR().

double CSRAPI::EnvBoundY ( double y ) [inline]

Parameters:

y

coordinate to bound

References GetEnvPlane(), RVB_YN, and RVB_YP.

Referenced by EnvBoundR().

double CSRAPI::EnvBoundZ ( double z ) [inline]

Parameters:

z

coordinate to bound

References GetEnvPlane(), RVB_ZN, and RVB_ZP.

Referenced by 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().

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 MAX_HRTF.

Returns:: true = success, false = failure

See also:: LstHRTFFree(), LstHRTF()

Parameters:

	nHRTF	HRTF ID, 0 to MAX_HRTF
	pName	HRTF database filename

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

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

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:: Due to sound sample delay line length limitations, the world should not be considered infinite. For the default 500ms delay line, the listener location coordinate values should not exceed +/- 45 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)

void CSRAPI::LstPos	(	Pos	pos,
		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:

	pos	coordinate ID
	v	coordinate value (meters or radians)

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)

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

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)

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(), GetASIOChIn(), GetASIOChOut()

Parameters:

	nDevice	ASIO device
	nCh	number of output channels
	nChMap	ASIO channel map
	nLen	ASIO channel map length
	bSplit	split stream flag

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

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

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

void CSRAPI::OutFree ( ) [inline]

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:: none

Remarks:: static-state function

See also:: Out Functions

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 jitter. 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 jitter 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 jitter 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()

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 jitter. See WaitSuspend() for more information.

Returns:: SLABError

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

char* CSRAPI::GetASIOName ( int nDevice ) [inline]

The GetASIOName() function returns an ASIO device driver name. Available devices are listed sequentially from 0 to 9 (max supported by SRAPI).

Returns:: ASIO device driver name

See also:: OutASIO(), GetASIOChIn(), GetASIOChOut()

Parameters:

nDevice

ASIO device number 0-9

int CSRAPI::GetASIOChIn ( int nDevice )

The GetASIOChIn() function returns the number of input channels on an ASIO device.

Error return values:
-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:: number of input channels, if negative, error

See also:: OutASIO(), GetASIOName(), GetASIOChOut()

Parameters:

nDevice

ASIO device number

int CSRAPI::GetASIOChOut ( int nDevice )

The GetASIOChOut() function returns the number of output channels on an ASIO device.

Returns:: number of output channels, if negative, error (see GetASIOChIn())

See also:: OutASIO(), GetASIOName(), GetASIOChIn()

Parameters:

nDevice

ASIO device number

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

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

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

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

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

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 scenes 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

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

Parameters:

bEnable

true = enable, false = disable

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.

Warning:: Be sure to stop the trajectory before it causes a delay line overflow (see SrcLocate())!

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)

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.

Warning:: Be sure to stop the trajectory before it causes a delay line overflow (see SrcLocatePolar())!

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)

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)

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

The ModSiAllocFile() function adds a 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
	dPause	pause (seconds)

bool CSRAPI::ModStart	(	IDMOD	idMod,
		int	nSrc
	)

The ModStart() function starts a Modifier.

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

See also:: Modifier Functions, IDMOD enum

Parameters:

	idMod	modifier ID
	nSrc	sound source ID

bool CSRAPI::ModStop	(	IDMOD	idMod,
		int	nSrc
	)

The ModStart() function stops a Modifier.

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

See also:: Modifier Functions, IDMOD enum

Parameters:

	idMod	modifier ID
	nSrc	sound source ID

bool CSRAPI::ModRate	(	IDMOD	idMod,
		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:

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

bool CSRAPI::ModRemove	(	IDMOD	idMod,
		int	nSrc = `-1`
	)

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

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

See also:: Modifier Functions

Parameters:

	idMod	modifier ID
	nSrc	sound source ID

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>   GetLstX(), etc.

Returns:: true = success, false = failure

See also:: SceneOpen()

Parameters:

pFilename

scenefile filename

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()
 <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()
 <ModSrcLocate>        ModSrcLocate()
 <ModSrcLocatePolar>   ModSrcLocatePolar()
 <ModSiAllocFile>      ModSiAllocFile()
 <ModStart>            ModStart()
 <ModStop>             ModStop()
 <ModRate>             ModRate()
 <User>                ScriptCallback() callback
 <Time>                time index (only use with slabscripts)

Returns:: true = success, false = failure

See also:: SceneSave(), ScriptOpen()

Parameters:

pFilename

scenefile filename

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

Parameters:

bEnable

true = enable, false = disable

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

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. The callback is called from within a locked section. 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

bool CSRAPI::ScriptOpen ( char * pFilename )

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().

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(), SceneOpen()

Parameters:

pFilename

XML slabscript file (.sls)

void CSRAPI::ScriptFree ( )

The ScriptFree() function frees script memory.

Returns:: none

bool CSRAPI::SetSampleRate ( long lSampleRate = 44100 ) [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().

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

bool CSRAPI::SetSmoothTime ( double dSmoothTime = 15.0 ) [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().

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().

void CSRAPI::SetDelayIn ( int nDelay = 500 ) [inline]

The SetDelayIn() function sets the sound source input delay line length. This delay line is allocated when a sound source is allocated and is used for modeling time delay effects such as source-to-listener propagation delay. A delay line is allocated for each sound source.

See also:: GetDelayIn()

Parameters:

nDelay

delay line length in ms

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().

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().

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

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().

void CSRAPI::Reset ( )

The Reset() function resets SRAPI state: rendering stopped, sources and outputs freed, render plugin set to RENDER_SPATIAL, 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

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

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

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. This prevents any further SRAPI functions from executing until the error is explicitly cleared by the SRAPI user. This is necessary since the user's application can be in a scene updating loop when an error occurs. Once the error occurs, all SRAPI functions do nothing but return the current error. Within a few iterations, the user's application will receive an error notification through the SetNotify() mechanism.

Returns:: none

See also:: Error Functions

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

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 ERR_SLAB_NONE if SRAPI is not in an error state.

See also:: Error Functions

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

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

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

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

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().

bool CSRAPI::Updated ( ) [inline]

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

 if( m_pScene->Updated() )
 {
   m_pScene->Recalc();
   if( !SceneToSigProc() )
     return false;
 }

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

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

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 used in conjunction with Updated(). See Updated() for a code fragment demonstrating the use of this function.

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

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 UI and DSP threads. Users can use Lock() to lock a simulation update routine that runs in its own thread.

See also:: Unlock()

Referenced by SetPIVar().

void CSRAPI::Unlock ( ) [inline]

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

See also:: Lock()

Referenced by SetPIVar().

bool CSRAPI::GetSrcAlloc ( int nSrc ) [inline]

Parameters:

nSrc

sound source ID

double CSRAPI::GetSrcLoc	(	int	nSrc,
		Pos	pos
	)			`[inline]`

The GetSrcLoc() function gets a source location coordinate.

Returns:: source location coordinate in meters

See also:: Query Functions, SrcLocate()

Parameters:

	nSrc	sound source ID
	pos	coordinate ID

Polar* CSRAPI::GetSrcRel ( int nSrc )

The GetSrcRel() function gets the listener-relative azimuth, elevation, and range of the requested source.

Returns:: Polar structure containing listener-relative polar source location

See also:: Query Functions, Polar structure in slabdefs.h

Parameters:

nSrc

sound source ID

bool CSRAPI::GetSrcLocRel ( int nSrc ) [inline]

Parameters:

nSrc

sound source ID

Polar* CSRAPI::GetSrcPolar ( int nSrc )

Parameters:

nSrc

sound source ID

double CSRAPI::GetSrcGain ( int nSrc ) [inline]

The GetSrcGain() function gets the dB gain of the requested source.

Returns:: gain in dB

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

Parameters:

nSrc

sound source ID

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

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

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

bool CSRAPI::GetSrcEnable ( int nSrc ) [inline]

Parameters:

nSrc

sound source ID

bool CSRAPI::GetSrcRefEnable	(	int	nSrc,
		int	nRef
	)			`[inline]`

Parameters:

	nSrc	sound source ID
	nRef	reflection identifier (see Planes in slabdefs.h)

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

bool CSRAPI::GetSrcMixAuxEn	(	int	nSrc,
		int	nAux
	)			`[inline]`

Parameters:

	nSrc	sound source ID
	nAux	0,1 aux channel

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)

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

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

int CSRAPI::GetSrcNum ( ) [inline]

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

Returns:: number of sound sources

See also:: Query Functions

double CSRAPI::GetEnvSndSpd ( ) [inline]

The GetEnvSndSpd() function returns the speed of sound.

Returns:: speed of sound (meters/s)

See also:: Query Functions

References dSoundSpeed.

double CSRAPI::GetEnvPlane ( Planes plane ) [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:

plane

plane identifier

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

MaterialType CSRAPI::GetEnvMaterial ( int n ) [inline]

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

Returns:: surface material type

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

Parameters:

n

surface identifier (see Planes in slabdefs.h)

StMatCoeffs* CSRAPI::GetEnvMatCoeffs	(	int	n,
		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:

	n	surface identifier (see Planes in slabdefs.h)
	fs	sample rate

double CSRAPI::GetLstPos ( Pos pos ) [inline]

The GetLstPos() function returns a listener position coordinate.

Returns:: listener position coordinate (meters, radians)

See also:: LstPosition()

Parameters:

pos

coordinate ID

bool CSRAPI::GetHRTFAllocated ( int nHRTF ) [inline]

Parameters:

nHRTF

HRTF ID

int CSRAPI::GetRenderID ( ) [inline]

The GetRenderID() function returns the current Render ID.

Returns:: Render ID

See also:: Query Functions, RenderID()

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().

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

long CSRAPI::GetSampleRate ( ) [inline]

The GetSampleRate() function returns the sampling rate.

Returns:: sampling rate (samples/s)

See also:: Query Functions, SetSampleRate()

Referenced by SetLevelTimes(), and SetSkipSilence().

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

int CSRAPI::GetFrameSize ( ) [inline]

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

Returns:: frame size (samples)

See also:: Query Functions

int CSRAPI::GetDelayIn ( ) [inline]

The GetDelayIn() function returns the input delay line length in ms.

Returns:: input delay line length (milliseconds)

See also:: Query Functions, GiIn(), SetDelayIn()

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

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

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

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

int CSRAPI::GetSkipTime ( ) [inline]

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

Returns:: skip silence time threshold in samples

See also:: SetSkipSilence()

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

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

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

char* CSRAPI::GetExeDir ( ) [inline]

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

Returns:: pointer to _MAX_PATH char buffer

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.

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().

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

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

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

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

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

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

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

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

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

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

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

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

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

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, you need to calculate the time-of-arrival and index 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 GetDelayIn()). 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 ), GetDelayIn()

Parameters:

fIndex

fractional index of input sample

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 ), GetDelayIn()

Parameters:

nIndex

index of input sample

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

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

References RVB_DIRECT.

double CSRAPI::GiRadius ( ) [inline]

The GiRadius() function returns the sound source radius.

Returns:: sound source radius (meters)

See also:: Image Functions, SrcRadius()

References RVB_DIRECT.

double CSRAPI::GiSpread ( ) [inline]

The GiSpread() function returns the sound source spread.

Returns:: sound source spread

See also:: Image Functions, SrcRadius()

References RVB_DIRECT.

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

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

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

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

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

double CSRAPI::GiRange ( ) [inline]

The GiRange() function returns the image-listener range.

Returns:: image-listener range (meters)

See also:: Image Functions

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

References RVB_DIRECT.

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

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)

References RVB_DIRECT.

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)

References RVB_DIRECT.

Planes 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 Planes enum values in slabdefs.h.

Returns:: reflection ID

See also:: Image Functions, Planes

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

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

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

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

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


Public Member Functions
SRAPI Construction
	CSRAPI ()
	allocates a CSRAPI object
Render Functions
SLABError	RenderStart (int nID=RENDER_SPATIAL, bool bAutoStop=true, bool bAsync=true)
	starts rendering
SLABError	RenderChange (int nID)
	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 (int nID, 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
int	RenderID (char *pName)
	returns the Render ID corresponding to a renderer's name
SLABError	SetNotify (HWND hWnd, WPARAM wParam)
	sets the notification window and notification message
Source Functions
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
void	SrcRadius (int nSrc, double dRadius=0.1, double dSpread=1.0)
	sets the radius of a sound source
void	SrcLocate (int nSrc, double x=0.0, double y=0.0, double z=0.0)
	sets the location of a sound source
void	SrcLoc (int nSrc, Pos pos, double v)
	sets the location of a sound source using one coordinate
void	SrcLocatePolar (int nSrc, double az, double el, double r)
	sets the location of a sound source relative to the origin
void	SrcLocateRel (int nSrc, double az, double el, double r)
	sets the location of a sound source relative to listener
void	SrcGain (int nSrc, double dDB)
	sets the gain of a sound source in dB
void	SrcGainScalar (int nSrc, float fScalar=0.0)
	sets the gain of a sound source using a linear scalar
void	SrcMute (int nSrc, bool bMute=false)
	mutes or unmutes a sound source
void	SrcReplay (int nSrc, float fSeconds)
	sets the replay time of the sound source in seconds (Spatial2)
void	SrcReplaySkip (int nSrc)
	enters replay skip silence mode (Spatial2)
void	SrcEnable (int nSrc, bool bEnable=false)
	enables or disables rendering of a sound source
void	SrcRefEnable (int nSrc, int nRef=RVB_ALL, bool bEnable=false)
	enables or disables a sound source's reflection
void	SrcRefOffset (int nSrc, int nRef=RVB_ALL, bool bRefOffset=false, double x=0.0, double y=0.0, double z=0.0)
	enables or disables reflection offsets
void	SrcMixGain (int nSrc, int nBegin, int nEnd, float *fGains, int nAux=-1)
	sets "Mixer" gains
void	SrcMixAux (int nSrc, int nAux, bool bEnable, double dSet1, double dSet2)
	sets "Mixer" aux send parameters
StreamIn Functions
SLABError	SiAllocFile (int nStreamIn, char *pFilename, bool bLoop=true, bool bMemory=false, HWND hwndNotify=NULL, WPARAM wparamNotify=0)
	allocates a wave file StreamIn
SLABError	SiAllocUrl (int nStreamIn, const char pUrl, const char pDir, bool bLoop=false, HWND hwndNotify=NULL, WPARAM wparamNotify=0, int nPreBuf=1, long lDownBytes=8192, long lReadBytes=8192)
	allocates a URL StreamIn
SLABError	SiAllocGen (int nStreamIn, char *pDir=NULL)
	allocates a signal generator StreamIn
SLABError	SiAllocUser (int nStreamIn, int nSamples, int nCh, float *pBufPtr, HANDLE pEventSwap)
	allocates a user StreamIn
SLABError	SiAllocASIO (int nStreamIn, int nCh=1, int *nChMap=NULL, int nLen=0)
	allocates an ASIO device StreamIn
SLABError	SiAllocWave (int nSrc)
	allocates a Waveform-Audio device StreamIn
SLABError	SiAllocVoIP (int nStreamIn, int nPort=5000, int nID=0)
	allocates a VoIP StreamIn
SLABError	SiAllocSubmix (int nStreamIn, CSSIList *pSSIList)
	allocates a submix StreamIn
SLABError	SiAllocDISRadio (int nStreamIn, int nPort, char *strID="", int nSilence=DEF_DISR1INT, int nPreBuf=DEF_DISR1PB, bool nRT=false)
	allocates a DIS radio StreamIn
SLABError	SiAllocDISFreq (int nStreamIn, unsigned long long ullFreq=0)
	allocates a DIS frequency StreamIn
SLABError	SiAllocDISRadios (int nNum, int nPort, int nSilence=DEF_DISR1INT, int nPreBuf=DEF_DISR1PB, bool bRT=false)
	allocates multiple DIS radios for SiAllocDISFreq()
void	SiFree (int nStreamIn)
	frees an individual StreamIn
void	SiFreeAll ()
	frees all StreamIns
CSSI *	SiStreamIn (int nStreamIn)
	returns a slabwire StreamIn (CSSI) pointer
Si CSSI Wrapper Functions (see also slabwire docs)
StreamType	SiType (int nStreamIn)
	returns stream type, see CSSI::SSInStreamType()
bool	SiPause (int nStreamIn)
	pause stream, see CSSI::SSInPause()
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()
SiGen CSIGen Wrapper Functions (see also slabwire docs)
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()
Environment Functions
void	EnvPlanes (double xp=dRoomDim/2.0, double xn=-dRoomDim/2.0, double yp=dRoomDim/2.0, double yn=-dRoomDim/2.0, double zp=dRoomDim-dLstHeight, double zn=-dLstHeight)
	sets the locations of the room planes
void	EnvPlane (Planes plane, double distance)
	sets the location of a room plane
bool	EnvMaterial (int nPlane, MaterialType matType=MAT_NONE)
	sets the plane material for a given plane
double	EnvBound (Pos pos, 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
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
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	LstPos (Pos pos, 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=dSENSOROFFSETm)
	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
void	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	GetASIOChIn (int nDevice)
	returns the number of input channels on an ASIO device
int	GetASIOChOut (int nDevice)
	returns the number of output channels on an ASIO 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, double dPause)
	adds a SiAllocFile() Modifier
bool	ModStart (IDMOD idMod, int nSrc)
	starts a Modifier
bool	ModStop (IDMOD idMod, int nSrc)
	stops a Modifier
bool	ModRate (IDMOD idMod, int nSrc, double dRateX, double dRateY, double dRateZ)
	adjusts a Modifier's rate of change
bool	ModRemove (IDMOD idMod, 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)
	opens an XML slabscript file (.sls)
void	ScriptFree ()
	frees script memory
Miscellaneous Functions
bool	SetSampleRate (long lSampleRate=44100)
	sets the render and output sample rate
void	SetResampler (bool bOversample=true, bool bArbitrary=true)
	sets resampler parameters
bool	SetSmoothTime (double dSmoothTime=15.0)
	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	SetDelayIn (int nDelay=500)
	sets the sound source input delay line length
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
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	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
double	GetSrcLoc (int nSrc, Pos pos)
	gets a source location coordinate
Polar *	GetSrcRel (int nSrc)
	gets the listener-relative location of the requested source
bool	GetSrcLocRel (int nSrc)
	returns true if source is a listener-relative source
Polar *	GetSrcPolar (int nSrc)
	returns the polar coordinates of source
double	GetSrcGain (int nSrc)
	gets the dB gain 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
bool	GetSrcEnable (int nSrc)
	gets enable state of source
bool	GetSrcRefEnable (int nSrc, int nRef)
	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 (Planes plane)
	gets the location of a room plane
MaterialType	GetEnvMaterial (int n)
	returns the material type of a surface
StMatCoeffs *	GetEnvMatCoeffs (int n, long fs)
	returns material filter coefficients
bool	GetEnvBoundMove ()
	true if bound function changed coordinate
double	GetLstPos (Pos pos)
	returns a listener position coordinate
double	GetLstX ()
	listener x axis coordinate, meters
double	GetLstY ()
	listener y axis coordinate, meters
double	GetLstZ ()
	listener z axis coordinate, meters
double	GetLstYaw ()
	listener yaw coordinate, radians
double	GetLstPitch ()
	listener pitch coordinate, radians
double	GetLstRoll ()
	listener roll coordinate, radians
bool	GetHRTFAllocated (int nHRTF)
	returns true if HRTF allocated
int	GetRenderID ()
	returns current Render ID
bool	GetRenderTime ()
	returns true if rendering
double	GetSmoothTime ()
	returns the DSP parameter smoothing filter time constant
long	GetSampleRate ()
	returns the sampling rate
int	GetFIRTaps ()
	returns the number of direct path HRIR FIR taps
int	GetFrameSize ()
	returns the frame size in samples
int	GetDelayIn ()
	returns the input delay line length in ms
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
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
bool	GiEnabled ()
	gets the sound image enabled flag
float	GiGain ()
	gets the scalar gain of the sound image
double	GiRadius ()
	returns the sound source radius
double	GiSpread ()
	returns the sound source spread
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
Planes	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
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
Static Public Member Functions
slab3d Installation
static bool	SetLinks ()
	creates a slab3d Start Menu folder