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 (SCRender scRender=SC::RenderSpatial, bool bAutoStop=true, bool bAsync=true)
 starts rendering
SLABError RenderChange (SCRender scRender)
 changes the current Render Plugin
SLABError RenderStop ()
 stops rendering
SLABError RenderBatch (char *pBatchDirIn, char *pBatchDirOut, char *pScriptFile)
 batch renders a directory of wave files
SLABError RenderEventPrepare (SCRender scRender, int nCh=2, int nDevice=0, int *nChMap=NULL, int nLen=0)
 prepares RenderEvent() for event-triggered playback
SLABError RenderEvent ()
 plays pre-rendered sound data from memory
Desc ** RenderEnum ()
 enumerates Render Plugins
SCRender RenderID (char *pName)
 returns the Render ID corresponding to a renderer's name
void SetNotify (CBNOTIFY pcbNotify)
 sets the notification callback function
Source Functions
int SrcGetID ()
 returns the next available sound source ID
SLABError SrcAlloc (int nSrc)
 allocates a sound source
SLABError SrcStream (int nSrc, int nStreamIn, int nChannel=0)
 attaches a stream to a sound source
bool SrcFree ()
 frees all allocated sound sources
bool SrcRadius (int nSrc, double dRadius=SC::SrcRadius(), double dSpread=SC::SrcSpread())
 sets the radius of a sound source
bool SrcLocate (int nSrc, double x=0.0, double y=0.0, double z=0.0)
 sets the location of a sound source
bool SrcLoc (int nSrc, Pos scPos, double v)
 sets the location of a sound source using one coordinate
bool SrcLocatePolar (int nSrc, double az, double el, double r)
 sets the location of a sound source relative to the origin
bool SrcLocateRel (int nSrc, double az, double el, double r)
 sets the location of a sound source relative to listener
bool SrcLocatePan (int nSrc, float fPan)
 sets the location of a panned sound source
bool SrcGain (int nSrc, double dDB)
 sets the gain of a sound source in dB
bool SrcGainScalar (int nSrc, float fScalar=0.0)
 sets the gain of a sound source using a linear scalar
bool SrcMute (int nSrc, bool bMute=false)
 mutes or unmutes a sound source
bool SrcReplay (int nSrc, float fSeconds)
 sets the replay time of the sound source in seconds (Spatial2)
bool SrcReplaySkip (int nSrc)
 enters replay skip silence mode (Spatial2)
bool SrcEnable (int nSrc, bool bEnable=false)
 enables or disables rendering of a sound source
bool SrcRefEnable (int nSrc, SCRvb scRvb=SC::RvbAll, bool bEnable=false)
 enables or disables a sound source's reflection
bool SrcRefOffset (int nSrc, SCRvb scRvb=SC::RvbAll, bool bRefOffset=false, double x=0.0, double y=0.0, double z=0.0)
 enables or disables reflection offsets
bool SrcMixGain (int nSrc, int nBegin, int nEnd, float *fGains, int nAux=-1)
 sets "Mixer" gains
bool SrcMixAux (int nSrc, int nAux, bool bEnable, double dSet1, double dSet2)
 sets "Mixer" aux send parameters
StreamIn Functions
int SiGetID ()
 returns the next available StreamIn ID not allocated or mapped
SLABError SiAllocFile (int nStreamIn, char *pFilename, bool bLoop=true, bool bMemory=false, long lIndex=0)
 allocates a wave file StreamIn
SLABError SiAllocMemory (int nStreamIn, float *pBuffer, long lSamples, long lFs=44100, bool bLoop=true)
 allocates a memory sample buffer StreamIn
SLABError SiAllocUrl (int nStreamIn, const char *pUrl, const char *pDir, bool bLoop=false, 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 SiAllocSubmix (int nStreamIn, CSSIList *pSSIList)
 allocates a submix StreamIn
SLABError SiAllocDISRadio (int nStreamIn, int nPort, char *strID, int nPreBuf=SC::DisPreBuf)
 allocates a DIS radio StreamIn
SLABError SiAllocDISFreq (int nStreamIn, unsigned long long ullFreq)
 allocates a DIS frequency StreamIn
SLABError SiAllocDISRadios (int nNum, int nPort, int nPreBuf=SC::DisPreBuf)
 allocates multiple DIS radios for SiAllocDISFreq()
SLABError SiAlloc_RT_DIS_Radio (int nStreamIn, int UDP_port, int output_sfreq, unsigned int min_latency_ms)
 allocates a Real-Time DIS Radio Receiver StreamIn
void SiFree (int nStreamIn)
 frees an individual StreamIn
void SiFreeAll ()
 frees all StreamIns
CSSI * SiStreamIn (int nStreamIn)
 returns a slabwire StreamIn (CSSI) pointer
Si StreamIn Support Functions (see also slabwire CSSI)
StreamType SiType (int nStreamIn)
 returns stream type, see CSSI::SSInStreamType()
char * SiTypeName (int nStreamIn)
 returns stream type name, see streams.h StreamStrings
bool SiDone (int nStreamIn)
 returns true is stream done, e.g., one-shot wavefile playback finished
bool SiPause (int nStreamIn)
 pause stream, see CSSI::SSInPause()
bool SiPaused (int nStreamIn)
 returns true if stream paused, see CSSI::SSInPaused()
bool SiPlay (int nStreamIn)
 play stream, see CSSI::SSInPlay()
bool SiRewind (int nStreamIn)
 rewind stream, see CSSI::SSInRewind()
bool SiAlias (int nStreamIn, bool bAlias)
 allows resample aliasing, see CSSI::DelayAlias()
SiGen Support Functions (see also slabwire CSIGen)
GMapSiGenEnum (int nStreamIn)
 enumerates signal generator plugins, see CSIGen::GenEnum()
GDescSiGenDesc (int nStreamIn)
 returns a gplugin description struct, see CGPlugIn::GetDesc()
bool SiGenSelect (int nStreamIn, char *pName)
 selects a signal generator plugin, see CSIGen::GenSelect()
bool SiGenSet (int nStreamIn, int nParam, float fValue, bool bApply=false)
 sets gplugin parameter value, see CGPlugIn::Set()
bool SiGenApply (int nStreamIn)
 informs gplugin one or more parameters set, see CGPlugIn::Apply()
bool SiGenStart (int nStreamIn)
 starts gplugin sample generation, see CGPlugIn::Start()
bool SiGenStop (int nStreamIn)
 stops gplugin sample generation (generates zeroes), see CGPlugIn::Stop()
GPList * SiGenPList (int nStreamIn)
 returns gplugin parameter list, see CGPlugIn::GetPList()
SiDis Support Functions (see also slabwire CSIDISRadio/CSIDISFreq)
bool SiDisSetID (int nStreamIn, const char *strID)
 sets the radio ID of a DIS radio stream
char * SiDisGetID (int nStreamIn)
 returns the DIS radio ID of a DIS radio stream
unsigned long long SiDisGetFreq (int nStreamIn)
 returns the DIS radio frequency in Hertz
int SiDisGetPort (int nStreamIn)
 returns the DIS radio stream UDP port number of a DIS radio stream
bool SiDisSetFreq (int nStreamIn, unsigned long long ullFreq)
 sets the radio frequency in Hertz of a DIS frequency stream
bool SiDisSolo (int nStreamIn, const char *strID, bool bSolo)
 soloes a DIS radio in a DIS frequency stream
char * SiDisGetSoloID (int nStreamIn)
 returns a radio ID if a radio is soloed in a DIS frequency stream
RT_DIS Support Functions
bool Si_RT_DIS_Radio_Set_UDP_Receiver_Port (int nStreamIn, int UDP_port)
 sets the RT_DIS UDP receiver port
int Si_RT_DIS_Radio_Get_UDP_Receiver_Port (int nStreamIn)
 gets the RT_DIS UDP receiver port
bool Si_RT_DIS_Radio_Add_Frequency (int nStreamIn, unsigned __int64 radio_frequency_Hz, double gain)
 adds a DIS radio frequency to a Real-Time DIS Radio Receiver
bool Si_RT_DIS_Radio_Remove_Frequency (int nStreamIn, unsigned __int64 radio_frequency_Hz)
 removes a DIS radio frequency from a Real-Time DIS Radio Receiver
bool Si_RT_DIS_Radio_Remove_All_Frequencies (int nStreamIn)
 removes all DIS radio frequencies from a Real-Time DIS Radio Receiver
bool Si_RT_DIS_Radio_Set_Gain (int nStreamIn, unsigned __int64 radio_frequency_Hz, double gain_dB)
 sets the gain(dB) of a DIS radio_frequency(Hz)
double Si_RT_DIS_Radio_Get_Gain (int nStreamIn, unsigned __int64 radio_frequency_Hz)
 gets the gain(dB) of a DIS radio_frequency(Hz)
bool Si_RT_DIS_Radio_Block_ID (int nStreamIn, int exercise, int site, int application, int entity, int radio)
 blocks (mutes) a radio ID in an RT_DIS stream
bool Si_RT_DIS_Radio_Unblock_ID (int nStreamIn, int exercise, int site, int application, int entity, int radio)
 unblocks (unmutes) a radio ID in an RT_DIS stream
bool Si_RT_DIS_Radio_Unblock_All (int nStreamIn)
 unblocks (unmutes) all blocked radio IDs in an RT_DIS stream
Environment Functions
void EnvPlanes (double xp=SC::RoomDim()/2.0, double xn=-SC::RoomDim()/2.0, double yp=SC::RoomDim()/2.0, double yn=-SC::RoomDim()/2.0, double zp=SC::RoomDim()-SC::LstHeight(), double zn=-SC::LstHeight())
 sets the locations of the room planes
void EnvPlane (SCRvb scRvb, double distance)
 sets the location of a room plane
bool EnvMaterial (SCRvb scRvb, SCMat scMat=SC::MatNone)
 sets the plane material for a given plane
double EnvBound (Pos scPos, double v)
 places a position coordinate inside room
double EnvBoundX (double x)
 places x coordinate inside room
double EnvBoundY (double y)
 places y coordinate inside room
double EnvBoundZ (double z)
 places z coordinate inside room
double EnvBoundR (double az, double el, double r)
 places polar range coordinate inside room
Listener Functions
bool LstHRTFLoad (int nHRTF, const char *pName)
 loads an HRTF database
void LstHRTFFree (int nHRTF)
 frees a loaded HRTF database
bool LstHRTF (int nHRTF=-1, int nSrc=-1)
 selects an HRTF database
bool LstHRTFHeader (int nHRTF, HRTFHeader *header)
 retrieves HRTF database header information
void LstPosition (double x=0.0, double y=0.0, double z=0.0, double yaw=0.0, double pitch=0.0, double roll=0.0)
 positions the listener
void LstPos (Pos scPos, double v)
 positions the listener using one coordinate
void LstSensorPos (double x, double y, double z, double yaw, double pitch, double roll)
 positions the listener using a sensor position
void LstSensorOffset (double x=0.0, double y=0.0, double z=SC::SensorOffsetM())
 sets tracker sensor offsets
Output Functions
SLABError OutASIO (int nDevice=0, int nCh=2, int *nChMap=NULL, int nLen=0, bool bSplit=false)
 specifies ASIO as the device interface for sound output
SLABError OutDirectSound (int nCh=2, int nOut=DS_BUFSIZE_OUT, int nWrite=DS_BUFSIZE_WRITE, bool bSplit=false)
 specifies DirectSound as the device interface for sound output
SLABError OutWave (int nCh=2, bool bSplit=false)
 specifies Waveform-Audio as the device interface for sound output
SLABError OutFile (char *pFilename, bool bMemory=false, int nCh=2, bool bSplit=false)
 specifies a wave file as the destination of sound output
bool OutFree ()
 frees all sound output
SLABError WaitSuspend ()
 waits on process suspend
SLABError WaitSwap ()
 waits on an ASIO double-buffer swap
char * GetASIOName (int nDevice)
 returns an ASIO device driver name
int GetASIOInfo (int nDriver, ASIOInfo *pAsioInfo)
 fills an ASIOInfo struct for a given device
unsigned long GetUnderflows ()
 returns the number of sound output underflows
unsigned long GetClips ()
 returns the number of sample output clips
Callback Functions
SLABError CallRate (double dUpdateRate=120.0)
 sets the Callback, Modifier, and Script update rate
unsigned int CallPeriod ()
 returns the callback period in samples
double CallTrueRate ()
 returns the true callback update rate in Hz
void Callback (bool(*pCallback)(void *pData), void *pData=NULL)
 specifies a user callback routine
Modifier Functions
void ModEnable (bool bEnable)
 enables or disables Modifier processing
void ModSrcLocate (int nSrc, double dX, double dY, double dZ, double dRateX, double dRateY, double dRateZ)
 adds a SrcLocate() Modifier
void ModSrcLocatePolar (int nSrc, double dAz, double dEl, double dR, double dRateAz, double dRateEl, double dRateR)
 adds a SrcLocatePolar() Modifier
void ModSrcGainScalar (int nSrc, float *pfTable, int nLength, double dTime, bool bLoop)
 adds a SrcGainScalar() Modifier
bool ModSiAllocFile (int nStreamID, char *pFilename, bool bLoop, bool bMemory, long lStart, double dPause)
 adds a SiAllocFile() Modifier
bool ModStart (SCMod scMod, int nSrc)
 starts a Modifier
bool ModStop (SCMod scMod, int nSrc)
 stops a Modifier
bool ModRate (SCMod scMod, int nSrc, double dRateX, double dRateY, double dRateZ)
 adjusts a Modifier's rate of change
bool ModRemove (SCMod scMod, int nSrc=-1)
 removes a Modifier
Scenefile and Script Functions
bool SceneSave (char *pFilename)
 saves an XML scenefile (.scn)
bool SceneOpen (char *pFilename)
 opens an XML scenefile (.scn)
void ScriptEnable (bool bEnable)
 enables or disables script list processing
void ScriptCallback (bool(*pCallback)(void *pData, int nArg, float f0, float f1, float f2, float f3), void *pData=NULL)
 specifies a slabscript callback routine
bool ScriptOpen (char *pFilename, bool bScriptThread=false)
 opens an XML slabscript file (.sls)
void ScriptFree ()
 frees script memory
unsigned int ScriptMisses ()
 returns script thread update misses
Miscellaneous Functions
bool SetSampleRate (long lSampleRate=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 SetDelayOut (int nDelay=0)
 sets the sound output delay in frames
void SetLevelTimes (float fAttack=0.137f, float fRelease=0.137f)
 sets the level meter attack and release time constants (Spatial2)
void SetSkipSilence (float fLevel=0.050f, float fTime=0.500f, float fFadeIn=0.068f)
 sets the replay skip silence parameters (Spatial2)
void SetNSOffset (double dB=-24.0)
 sets the non-spatial gain offset in dB
bool SetDefaults ()
 sets several acoustic scene parameters to their default values
void Reset ()
 resets SRAPI state
bool SetSharedMemory (float *pFloats)
 Copies an array of 32 floats to shared memory.
bool GetSharedMemory (float *pFloats)
 Gets an array of 32 floats from shared memory.
Error Functions
char * ErrorString ()
 returns the current SRAPI error string
char * ErrorStack ()
 returns the SRAPI error strack
void ErrorClear ()
 clears the current SRAPI error
bool ErrorState ()
 returns the SRAPI error state
SLABError Error ()
 returns the current SRAPI error code
Log Functions
void LogName (char *pLogName)
 sets the log filename
void LogEntry (char *pLogEntry)
 logs a user message
void LogTime ()
 logs the current system time
Update Functions (App and Render Plugin API)
void SetHint (unsigned long ul)
 set hint
unsigned long GetHint ()
 get hint
void HintClear ()
 clear hint
void SetTick (bool bTickUp)
 selects frame or tick parameter updating
void Tick ()
 updates DSP parameters if using tick parameter updating
bool Updated ()
 checks if SRAPI scene parameters have been updated
void UpdateClear ()
 clears update state
void UpdateSet ()
 sets update state
void UpdateWaitReset ()
 resets the update done event
bool UpdateWait ()
 waits for an update to be complete
void Recalc ()
 recalculates the scene
void Lock ()
 locks scene access
void Unlock ()
 unlocks scene access
Query Functions (App and Render Plugin API)
bool GetSrcAlloc (int nSrc)
 returns true if sound source allocated
int GetSrcStreamID (int nSrc)
 gets the sound source's StreamID
double GetSrcLoc (int nSrc, Pos scPos)
 gets a source location coordinate
double GetSrcAz (int nSrc)
 returns the listener-relative source azimuth in radians
double GetSrcEl (int nSrc)
 returns the listener-relative source elevation in radians
double GetSrcRange (int nSrc)
 returns the listener-relative source range in meters
int GetSrcLocType (int nSrc)
 returns true if source is a listener-relative source
PolarGetSrcPolar (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, SCRvb scRvb)
 gets enable state of reflection
float GetSrcMixGain (int nSrc, int nIndex, int nAux=-1)
 gets the Mixer render plugin source gain or aux return gain
bool GetSrcMixAuxEn (int nSrc, int nAux)
 gets the Mixer render plugin aux channel enable state
double GetSrcMixAuxSet (int nSrc, int nAux, int nSet)
 gets the Mixer render plugin aux channel setting
float GetSrcReplay (int n)
 gets the replay time in samples (Spatial2)
float GetSrcLevel (int n)
 gets the source level meter value (Spatial2)
int GetSrcNum ()
 returns the number of sound sources
double GetEnvSndSpd ()
 returns the speed of sound
double GetEnvPlane (SCRvb scRvb)
 gets the location of a room plane
SCMat GetEnvMaterial (SCRvb scRvb)
 returns the material type of a surface
StMatCoeffs * GetEnvMatCoeffs (SCRvb scRvb, long fs)
 returns material filter coefficients
bool GetEnvBoundMove ()
 true if bound function changed coordinate
double GetLstPos (Pos scPos)
 returns a listener position coordinate
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 sample 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 GetDelayOut ()
 returns the audio output delay in frames
int GetDelayOutMax ()
 returns the maximum audio output delay in frames
int GetOutCh ()
 returns the number of output channels
float GetLevelAttack ()
 returns the level meter attack gain
float GetLevelRelease ()
 returns the level meter release gain
float GetSkipLevel ()
 returns the skip silence sound level threshold
int GetSkipTime ()
 returns the skip silence time threshold
int GetSkipFadeIn ()
 returns the skip silence fade in time
float GetNSScalar ()
 gets the non-spatial offset linear gain scalar
double GetNSOffset ()
 gets the non-spatial offset in dB
char * GetExeDir ()
 gets the executable directory
double GetPerf ()
 returns a performance counter time stamp
long GetCPU ()
 returns CPU use (averaged over 10 calls)
Plugin Variable Functions (App and Render Plugin API)
void SetPIVar (int nIndex, float fValue)
 sets a user plugin variable
void SetPIVarRange (int nIndex, float *pValues, int nCount)
 sets a range of user plugin variables
bool SetPIStatus (unsigned long lStatus, bool bBlock=false)
 sets the user plugin status variable
void SetPIStatusReset ()
 resets the user plugin status variable
bool PIVarUpdated ()
 checks if a plugin variable has been updated
void PIVarUpdateClear ()
 clears the plugin variable updated flag
float GetPIVar (int nIndex)
 gets the specified plugin variable
unsigned long GetPIStatus ()
 gets the plugin status variable
unsigned long GetPIStatusCmd ()
 gets the plugin status variable command
unsigned long GetPIStatusArg ()
 gets the plugin status variable argument
Image Functions (Render Plugin API)
void ResetImages ()
 resets the sound image list
void NextImage ()
 advances to the next sound image
void NextSource ()
 advances to the next sound source
bool GiEmpty ()
 gets the image list empty flag
float GiIn (float fIndex)
 gets a sample from a sound image's input delay line
float GiIn (int nIndex)
 gets a sample from a sound image's input delay line
bool GiEnabled ()
 gets the sound image enabled flag
int GiSrcLocType ()
 gets the SrcLocate type
float GiGain ()
 gets the scalar gain of the sound image
float GiGainL ()
 gets the left scalar pan gain of the sound image
float GiGainR ()
 gets the right scalar pan gain of the sound image
double GiRadius ()
 returns the sound source radius
double GiSpread ()
 returns the sound source spread
double GiX ()
 gets the x-coordinate of the sound image
double GiY ()
 gets the y-coordinate of the sound image
double GiZ ()
 gets the z-coordinate of the sound image
double GiAz ()
 gets the listener-relative azimuth of the sound image
double GiEl ()
 gets the listener-relative elevation of the sound image
double GiRange ()
 gets the image-listener range
float GiReplay ()
 returns the sound source replay time in samples
int GiFIRn ()
 gets the number of FIR taps
void GiHRTF (float fGain, float *pfHRIRL, float *pfHRIRR, float *pfITDL, float *pfITDR)
 gets the HRIR and ITD for the image
void GiHRTF (double dAz, double dEl, int nFIRPts, float fGain, float *pfHRIRL, float *pfHRIRR, float *pfITDL, float *pfITDR)
 gets an az,el HRIR and ITD from the image HRTF
SCRvb GiRefID ()
 gets the reflection ID of the image
ImageStruct * GiStruct ()
 gets the image struct pointer
void * GiData ()
 gets the plugin image data pointer
void SiData (void *pData)
 sets the plugin image data pointer
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
DM (DIS Manager) Functions (see also slabwire CDISManager)
static int DMGetRadioNum ()
 returns the number of DIS network radios
static CSIDISRadio * DMGetRadio (int i)
 returns the slabwire radio pointer of a DIS network radio
static char * DMGetRadioID (int i)
 returns the ID of a DIS network radio
static unsigned long long DMGetRadioFreq (int i)
 returns the frequency of a DIS network radio
static bool DMGetRadioPooled (int i)
 returns the frequency pool status of a DIS network radio
static int DMGetFreqNum ()
 returns the number of unique DIS frequencies
static unsigned long long DMGetFreq (int i)
 returns a DIS frequency from the unique frequency list


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:

Render Plugin 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 (SCRender) are built into the SRAPI library.

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


Member Function Documentation

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 ( SCRender  scRender = SC::RenderSpatial,
bool  bAutoStop = true,
bool  bAsync = true 
)

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

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

The pre-defined Render Plugin IDs:

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

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

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

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

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

Warning:
Do NOT use infinite length sound sources (e.g., looping wave files) with synchronous rendering (bAsync = false)!
Returns:
SLABError
Remarks:
static-state function
See also:
RenderStop(), RenderChange()
Parameters:
scRender specifies the type of rendering to perform
bAutoStop if true, when input ends, stop rendering
bAsync if true, return immediately, don't wait for rendering to complete

SLABError CSRAPI::RenderChange ( SCRender  scRender  ) 

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

Returns:
SLABError
See also:
RenderStart()
Parameters:
scRender render plugin ID

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 ( SCRender  scRender,
int  nCh = 2,
int  nDevice = 0,
int *  nChMap = NULL,
int  nLen = 0 
)

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

Returns:
SLABError
See also:
RenderEvent(), RenderStart(), Render Functions
Parameters:
scRender Render ID
nCh Number of output channels
nDevice ASIO device
nChMap ASIO channel map
nLen ASIO channel map length

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

SCRender CSRAPI::RenderID ( char *  pName  ) 

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

Returns:
integer ID >= 0 if name found, -1 if name not found or SRAPI in an error state
See also:
Render Functions
Parameters:
pName case-sensitive name of Render Plugin

void CSRAPI::SetNotify ( CBNOTIFY  pcbNotify  ) 

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

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

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

Returns:
none
See also:
Error Functions, RenderStart()
Parameters:
pcbNotify address of user callback routine

int CSRAPI::SrcGetID (  ) 

SrcGetID() returns the next available sound source ID.

Returns:
-1 if all IDs taken

SLABError CSRAPI::SrcAlloc ( int  nSrc  ) 

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

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

nSrc can be any integer from 0 to SC::MaxSrc. This is simply a lookup index, so these need not be sequential. Sources do consume CPU, however, so only allocate the number of sources 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(), GetSrcAlloc(), 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).

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

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

Note:
Continuous streams, like sound device input, need to remain attached to a sound source while rendering in order to service the continuous stream of input buffers.
See also:
SiAlloc Functions
Parameters:
nSrc sound source ID
nStreamIn StreamIn ID
nChannel StreamIn channel

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

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

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 source radius (meters)
dSpread source spread exponent (see formula)

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

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

Remarks:
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)

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

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

Note:
Hint = SHSrcLocate
See also:
SrcLocate()
Parameters:
nSrc sound source ID
scPos coordinate ID
v coordinate value (meters)

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

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

Remarks:
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)

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

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

Remarks:
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)

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

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

Note:
Hint = SHSrcLocate
See also:
Source Functions
Parameters:
nSrc sound source ID
fPan fully left 0.0, fully right 1.0, diotic 0.5

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

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

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

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

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

Note:
Hint = SHSrcGain
See also:
SrcGain(), SrcMute(), Source Functions
Parameters:
nSrc sound source ID
fScalar linear scalar gain

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

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

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

Hint = SHSrcGain

See also:
SrcGain(), Source Functions
Parameters:
nSrc sound source ID
bMute true = mute, false = unmute

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

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

See also:
SrcReplaySkip(), Source Functions
Parameters:
nSrc sound source ID
fSeconds replay time, seconds

bool CSRAPI::SrcReplaySkip ( int  nSrc  ) 

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

See also:
SrcReplay(), SetSkipSilence(), Source Functions
Parameters:
nSrc sound source ID

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

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

See also:
SrcRefEnable(), Source Functions
Parameters:
nSrc sound source ID
bEnable if true, the source is enabled, if false, the source is disabled

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

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

See also:
SrcEnable(), Source Functions
Parameters:
nSrc sound source ID
scRvb reflection identifier (see slabdefs.h)
bEnable if true, the reflection is enabled, if false, the reflection is disabled

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

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

Note:
Hint = SHSrcLocate
See also:
SrcRefEnable(), Source Functions
Parameters:
nSrc sound source ID
scRvb reflection identifier (see slabdefs.h)
bRefOffset if true, reflection offsets are enabled, if false, reflection offsets are disabled
x x offset amount
y y offset amount
z z offset amount

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

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

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

See also:
SrcMixAux()
Parameters:
nSrc sound source ID
nBegin beginning gain index
nEnd ending gain index
fGains scalar output gains
nAux -1 = sound source, 0,1 = aux return

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

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

dSet1 = azimuth in radians dSet2 = elevation in radians

See also:
SrcMixGain()
Parameters:
nSrc sound source ID
nAux aux send, 0 or 1
bEnable enable or disable aux send
dSet1 aux setting 1
dSet2 aux setting 2

int CSRAPI::SiGetID (  ) 

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

Returns:
-1 if all IDs taken

SLABError CSRAPI::SiAllocFile ( int  nStreamIn,
char *  pFilename,
bool  bLoop = true,
bool  bMemory = false,
long  lIndex = 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. See the SetNotify() function for notifications that are available for one-shot playback.

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

See also:
SrcStream(), SiStreamIn()
Parameters:
nStreamIn StreamIn ID
pFilename file to play
bLoop if true, loop file
bMemory if true, load entire file into memory
lIndex sample start index

SLABError CSRAPI::SiAllocMemory ( int  nStreamIn,
float *  pBuffer,
long  lSamples,
long  lFs = 44100,
bool  bLoop = true 
)

SiAllocMemory() allocates a memory sample buffer StreamIn.

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

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

See also:
SrcStream(), SiStreamIn()
Parameters:
nStreamIn StreamIn ID
pBuffer 1-channel sample buffer
lSamples number of samples in buffer
lFs sample rate in samples/s
bLoop if true, loop buffer

SLABError CSRAPI::SiAllocUrl ( int  nStreamIn,
const char *  pUrl,
const char *  pDir,
bool  bLoop = false,
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. See the SetNotify() function for notifications that are available for one-shot playback.

The supported file types are:

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

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

Note:
If the remote file has been streamed before, it might stream from the cache rather than from the remote site.

The remote files are saved using their WAV filename. Thus, playing multiple WAV files with the same name is not supported.

See also:
SrcStream()
Parameters:
nStreamIn StreamIn ID
pUrl "http://target.wav"-style address
pDir local download dir
bLoop loop wave file
nPreBuf number of buffers to download before playback
lDownBytes size of download buffer in bytes
lReadBytes size of read buffer in bytes

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(), GetASIOInfo()
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::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  nPreBuf = SC::DisPreBuf 
)

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

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

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

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

Warning:
Do not use DIS with non-real-time sound output alone. Samples are provided as fast as they are requested. Thus, for faster than real-time processing to wave file output, the file will grow very large very quickly.
See also:
SrcStream(), SiAllocDISFreq(), DM (DIS Manager) functions, SiDisSetID(), SiDisGetID(), SiDisGetFreq(), SiDisGetPort()
Parameters:
nStreamIn StreamIn ID
nPort DIS listening port (e.g., 3000)
strID radio ID (e.g., "100.104.1.1")
nPreBuf pre-buffered zeroes, default = 10ms

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

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

See also:
SrcStream(), SiAllocDISRadios(), SiAllocDISRadio(), DM (DIS Manager) functions, SiDisSetFreq(), SiDisGetFreq(), SiDisSolo()
Parameters:
nStreamIn StreamIn ID
ullFreq DIS frequency

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

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

Warning:
Do not use DIS with non-real-time sound output alone. Samples are provided as fast as they are requested. Thus, for faster than real-time processing to wave file output, the file will grow very large very quickly.
See also:
SiAllocDISFreq(), SiFreeAll(), DM (DIS Manager) functions
Parameters:
nNum number of DIS radios to allocate
nPort DIS listening port (e.g., 3000)
nPreBuf pre-buffered zeroes, default = 10ms

SLABError CSRAPI::SiAlloc_RT_DIS_Radio ( int  nStreamIn,
int  UDP_port,
int  output_sfreq,
unsigned int  min_latency_ms 
)

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

Parameters:
nStreamIn StreamIn ID
UDP_port UDP receive port
output_sfreq frequency in Hz which this source will produce
min_latency_ms minimum latency (added when a transmission starts/restarts)

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 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. This function allows users to access features not available via the Si*() wrapper functions.

Parameters:
nStreamIn StreamIn ID

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

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

Returns:
false if radio ID already mapped to a DIS radio stream
See also:
SiDisGetID(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID
strID radio ID string (see SiDisGetID())

char* CSRAPI::SiDisGetID ( int  nStreamIn  ) 

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

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

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

Returns:
radio ID
See also:
SiDisSetID(), SiDisGetFreq(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID

unsigned long long CSRAPI::SiDisGetFreq ( int  nStreamIn  ) 

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

Returns:
DIS radio frequency in Hertz
See also:
SiDisGetID(), SiDisSetFreq(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID

int CSRAPI::SiDisGetPort ( int  nStreamIn  ) 

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

Returns:
UDP port number
See also:
SiDisGetID()
Parameters:
nStreamIn StreamIn ID

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

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

Returns:
false if nStreamIn invalid
See also:
SiDisGetFreq(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID
ullFreq radio frequency in Hertz

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

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

Returns:
false if radio ID not found in frequency pool
See also:
SiDisSetFreq(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID
strID DIS radio ID (see SiDisGetID())
bSolo true = solo radio, false = unsolo

char* CSRAPI::SiDisGetSoloID ( int  nStreamIn  ) 

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

Returns:
radio ID or NULL
See also:
SiDisSolo(), DM (DIS Manager) functions
Parameters:
nStreamIn StreamIn ID

static int CSRAPI::DMGetRadioNum (  )  [static]

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

Note:
If only RT_DIS used, this function supports RT_DIS.
Returns:
number of DIS network radios
See also:
DMGetFreqNum(), SiDis functions, DM functions

static CSIDISRadio* CSRAPI::DMGetRadio ( int  i  )  [static]

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

Returns:
slabwire radio pointer
See also:
DMGetRadioNum(), DMGetRadioID(), DMGetRadioFreq(), SiDis functions, DM functions

static char* CSRAPI::DMGetRadioID ( int  i  )  [static]

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

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

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

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

Note:
If only RT_DIS used, this function supports RT_DIS. RT_DIS includes an additional field, Exercise, before the Entity ID.
Returns:
radio ID string
See also:
DMGetRadioNum(), DMGetRadioFreq(), DMGetRadio(), SiDis functions, DM functions

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

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

Returns:
radio frequency in Hertz
See also:
DMGetRadioNum(), DMGetRadioID(), DMGetRadio(), SiDis functions, DM functions

static bool CSRAPI::DMGetRadioPooled ( int  i  )  [static]

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

Returns:
frequency pool member flag
See also:
DMGetRadioNum(), DMGetRadioID(), DMGetRadioFreq(), SiDis functions, DM functions

static int CSRAPI::DMGetFreqNum (  )  [static]

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

Note:
If only RT_DIS used, this function supports RT_DIS.
Returns:
number of unique DIS frequencies
See also:
DMGetRadioNum(), SiDis functions, DM functions

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

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

Note:
If only RT_DIS used, this function supports RT_DIS.
Returns:
radio frequency in Hertz
See also:
DMGetFreqNum(), SiDis functions, DM functions

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

Parameters:
nStreamIn StreamIn ID
UDP_port UDP receive port

int CSRAPI::Si_RT_DIS_Radio_Get_UDP_Receiver_Port ( int  nStreamIn  ) 

Parameters:
nStreamIn StreamIn ID

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

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

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

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

bool CSRAPI::Si_RT_DIS_Radio_Remove_All_Frequencies ( int  nStreamIn  ) 

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

Parameters:
nStreamIn StreamIn ID

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

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

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

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

bool CSRAPI::Si_RT_DIS_Radio_Unblock_All ( int  nStreamIn  ) 

Parameters:
nStreamIn StreamIn ID

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

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

Warning:
When using the room model, the user should ensure objects remain within the room.
Note:
Hint = SHEnvPlane
See also:
Environment Functions
Parameters:
xp positive x-axis plane location (meters)
xn negative x-axis plane location (meters)
yp positive y-axis plane location (meters)
yn negative y-axis plane location (meters)
zp positive z-axis plane location (meters)
zn negative z-axis plane location (meters)

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

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

Note:
Hint = SHEnvPlane
See also:
Environment Functions
Parameters:
scRvb plane identifier
distance plane distance from origin (meters)

bool CSRAPI::EnvMaterial ( SCRvb  scRvb,
SCMat  scMat = SC::MatNone 
) [inline]

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

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

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

Returns:
true = material type set, false = not set due to currently rendering
Remarks:
static setting
Note:
Hint = SHEnvMat
See also:
Environment Functions
Parameters:
scRvb plane identifier (see SCRvb in slabdefs.h, RvbXP thru RvbZN)
scMat material type identifier

References GetRenderTime().

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

Parameters:
scPos coordinate identifier
v coordinate to bound

References GetEnvPlane().

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

Parameters:
x coordinate to bound

References GetEnvPlane().

Referenced by EnvBoundR().

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

Parameters:
y coordinate to bound

References GetEnvPlane().

Referenced by EnvBoundR().

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

Parameters:
z coordinate to bound

References GetEnvPlane().

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 SC::MaxHRTF.

Returns:
true = success, false = failure
See also:
LstHRTFFree(), LstHRTF()
Parameters:
nHRTF HRTF ID, 0 to SC::MaxHRTF
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

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

The LstHRTFHeader() function retrieves HRTF database header information.

Returns:
true = success, false = failure
See also:
LstHRTFLoad()
Parameters:
nHRTF HRTF ID, -1 default HRTF, -2 current HRTF
header struct to receive header data

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  scPos,
double  v 
)

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

Note:
Hint = SHLstPos
See also:
LstPosition()
Parameters:
scPos coordinate ID
v coordinate value (meters or radians)

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 = SC::SensorOffsetM() 
)

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

See also:
LstSensorPos()
Parameters:
x x-axis sensor offset (meters)
y y-axis sensor offset (meters)
z z-axis sensor offset (meters)

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

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

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

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

Returns:
SLABError
Remarks:
static-state function
The API-to-display latency for ASIO ranges between the ASIOGetLatencies() output latency value plus one buffer length to the same value plus another buffer length (roughly 2*buf_length to 3*buf_length).
See also:
GetASIOName(), GetASIOInfo()
Parameters:
nDevice ASIO device, 0 to SC::AsioDevices-1
nCh number of output channels
nChMap ASIO channel map
nLen ASIO channel map length
bSplit split stream flag

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

bool CSRAPI::OutFree (  ) 

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

Output Patch Example:

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

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

Returns:
true = success, false = can't free while rendering
Remarks:
static-state function
See also:
Out Functions

SLABError CSRAPI::WaitSuspend (  ) 

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

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

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

Returns:
SLABError
Remarks:
The ASIO output buffer size is often set with a utility provided by the sound device manufacturer.
See also:
Output Functions, WaitSwap(), OutASIO()

SLABError CSRAPI::WaitSwap (  ) 

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

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

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

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

Returns:
ASIO device driver name
See also:
OutASIO(), GetASIOInfo()
Parameters:
nDevice ASIO device number, 0 to SC::AsioDevices-1

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

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

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

Returns:
0 success, else error
See also:
OutASIO(), GetASIOName()
Parameters:
nDriver ASIO device number, 0 to SC::AsioDevices-1
pAsioInfo ASIOInfo struct

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 the Modifier functions, ScriptOpen(), or RenderStart().

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

Returns:
true = success, false = failure
Remarks:
static-state function
See also:
CallPeriod(), CallTrueRate(), Callback()
Parameters:
dUpdateRate callback update rate in Hz

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 actions requiring a high update rate (e.g., a custom trajectory) and/or for sound source sample synchronization (e.g., non-real-time rendering). This function and the user callback function are called from within a Lock()'d block. The callback should return true for success, false for failure.

Returns:
none
See also:
CallRate(), CallTrueRate(), CallPeriod()
Parameters:
pCallback address of user callback routine
pData address of user data

void CSRAPI::ModEnable ( bool  bEnable  )  [inline]

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

Returns:
none
See also:
Modifier Functions, CallRate()
Parameters:
bEnable true = enable, false = disable

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,
long  lStart,
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
lStart sample start index
dPause pause (seconds)

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

The ModStart() function starts a Modifier.

Returns:
true = success, false = modifier or source not found
See also:
Modifier Functions, SCMod constants
Parameters:
scMod modifier ID
nSrc sound source ID

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

The ModStart() function stops a Modifier.

Returns:
true = success, false = modifier or source not found
See also:
Modifier Functions, SCMod constants
Parameters:
scMod modifier ID
nSrc sound source ID

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

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

Returns:
true = success, false = modifier or source not found
See also:
Modifier Functions
Parameters:
scMod modifier ID
nSrc sound source ID
dRateX new x-axis or azimuth rate (meters/s, radians/s)
dRateY new y-axis or elevation rate (meters/s, radians/s)
dRateZ new z-axis or range rate (meters/s)

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

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

Returns:
true = success, false = modifier or source not found
See also:
Modifier Functions
Parameters:
scMod modifier ID
nSrc sound source ID

bool CSRAPI::SceneSave ( char *  pFilename  ) 

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

The following state is saved:

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:

Examples:

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

Returns:
true = success, false = failure
See also:
SceneSave(), ScriptOpen()
Parameters:
pFilename scenefile filename

void CSRAPI::ScriptEnable ( bool  bEnable  )  [inline]

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

Returns:
none
See also:
CallRate()
Parameters:
bEnable true = enable, false = disable

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

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

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

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

Returns:
none
Parameters:
pCallback address of user callback routine
pData address of user data

bool CSRAPI::ScriptOpen ( char *  pFilename,
bool  bScriptThread = false 
) [inline]

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

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

Script XML file example:

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

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

Macro XML file example:

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

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

Warning:
The script XML buffer is limited to 32768 bytes.
Returns:
true = success, false = failure
See also:
ScriptEnable(), ScriptFree(), ScriptMisses(), SceneOpen()
Parameters:
pFilename XML slabscript file (.sls)
bScriptThread run script in own thread

void CSRAPI::ScriptFree (  )  [inline]

The ScriptFree() function frees script memory.

Returns:
none

unsigned int CSRAPI::ScriptMisses (  )  [inline]

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

Returns:
number of script thread misses since last ScriptOpen()
See also:
ScriptOpen(), CallRate()

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::SetDelayOut ( int  nDelay = 0  )  [inline]

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

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

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

The output delay in seconds:

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

See also:
GetDelayOut(), GetDelayOutMax()
Parameters:
nDelay output delay in frames

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

void CSRAPI::Reset (  ) 

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

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

Returns:
none
See also:
Rendering Functions, Error Functions

bool CSRAPI::SetSharedMemory ( float *  pFloats  ) 

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

Returns:
true = success, false = failure

bool CSRAPI::GetSharedMemory ( float *  pFloats  ) 

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

Returns:
true = success, false = failure

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. In an error state, most SRAPI functions do nothing but return the current error. This simplifies error handling when calling several SRAPI functions in a row. Only the last function needs to be checked for error.

Returns:
none
See also:
Error Functions

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 ErrorNone 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(), and UpdateSet().

bool CSRAPI::Updated (  )  [inline]

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

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

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

Returns:
true if SRAPI scene updated, otherwise false
See also:
Update Functions, Recalc(), CRPlugIn::Process()

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::UpdateSet (  )  [inline]

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

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

Referenced by Tick().

void CSRAPI::UpdateWaitReset (  )  [inline]

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

See also:
UpdateWait()

bool CSRAPI::UpdateWait (  )  [inline]

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

Returns:
true = signaled, false = timeout
See also:
UpdateSet()

void CSRAPI::Recalc (  ) 

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

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

void CSRAPI::Lock (  )  [inline]

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

See also:
Unlock()

Referenced by SetPIVar().

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

int CSRAPI::GetSrcStreamID ( int  nSrc  )  [inline]

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

Returns:
StreamID or -1 for unassigned stream; error values: -2 unallocated source, -3 invalid source ID
See also:
Query Functions
Parameters:
nSrc sound source ID

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

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

Returns:
source location coordinate in meters
See also:
Query Functions, SrcLocate()
Parameters:
nSrc sound source ID
scPos coordinate ID (x,y,z)

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

Parameters:
nSrc sound source ID

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

Parameters:
nSrc sound source ID

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

Parameters:
nSrc sound source ID

int CSRAPI::GetSrcLocType ( 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. If the internal linear gain scalar is 0, the return value is SC::GainMutedB().

Returns:
gain in dB
See also:
SrcGain(), SrcGainScalar(), Query Functions
Parameters:
nSrc sound source ID

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,
SCRvb  scRvb 
) [inline]

Parameters:
nSrc sound source ID
scRvb reflection identifier (see SCRvb 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

double CSRAPI::GetEnvPlane ( SCRvb  scRvb  )  [inline]

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

Returns:
room plane distance from origin in meters
See also:
EnvPlanes(), EnvPlane()
Parameters:
scRvb plane identifier

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

SCMat CSRAPI::GetEnvMaterial ( SCRvb  scRvb  )  [inline]

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

Returns:
surface material type
See also:
Query Functions, EnvMaterial(), GetEnvMatCoeffs()
Parameters:
scRvb surface identifier (see SCRvb in slabdefs.h)

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

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

Returns:
pointer to material filter coefficients
See also:
Query Functions, GetEnvMaterial(), EnvMaterial()
Parameters:
scRvb surface identifier (see SCRvb in slabdefs.h)
fs sample rate

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

The GetLstPos() function returns a listener position coordinate.

Returns:
listener position coordinate (meters, radians)
See also:
LstPosition()
Parameters:
scPos coordinate ID

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 sample rate.

Returns:
sample rate (samples/s)
See also:
Query Functions, SetSampleRate()

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

Referenced by GetDelayOutMax().

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::GetDelayOut (  )  [inline]

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

The output delay in seconds:

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

Returns:
output delay (frames)
See also:
Query Functions, GetDelayOutMax(), SetDelayOut()

int CSRAPI::GetDelayOutMax (  )  [inline]

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

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

The true maximum output delay in seconds:

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

Returns:
maximum audio output delay (frames)
See also:
Query Functions, GetDelayOut(), SetDelayOut(), SC::DelayOutMax()

References GetFrameSize(), and GetSampleRate().

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

int CSRAPI::GiSrcLocType (  )  [inline]

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

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

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

float CSRAPI::GiGainL (  )  [inline]

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

Returns:
left scalar pan gain of the sound image
See also:
Image Functions, SrcLocatePan()

float CSRAPI::GiGainR (  )  [inline]

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

Returns:
right scalar pan gain of the sound image
See also:
Image Functions, SrcLocatePan()

double CSRAPI::GiRadius (  )  [inline]

The GiRadius() function returns the sound source radius.

Returns:
sound source radius (meters)
See also:
Image Functions, SrcRadius()

double CSRAPI::GiSpread (  )  [inline]

The GiSpread() function returns the sound source spread.

Returns:
sound source spread
See also:
Image Functions, SrcRadius()

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

int CSRAPI::GiFIRn (  )  [inline]

The GiFIRn() function returns the SRAPI-specified number of FIR taps for the HRIR filter operation. This can be ignored or used for another purpose by renderers that do not perform an HRIR FIR operation. The default FIRn value for reflections is 1/4 the FIRn for the direct path. This reserves more CPU resources for the direct path, causing the direct path to be rendered at a higher fidelity than the reflections.

Returns:
number of FIR taps
See also:
Image Functions, FIRPoints()

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)

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)

SCRvb CSRAPI::GiRefID (  )  [inline]

The GiRefID() function returns the reflection ID of the image. This will either be -1 for the direct path or one of the SCRvb constants in slabdefs.h.

Returns:
reflection ID
See also:
Image Functions, Planes

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


SRAPI Reference Manual generated Tue Jul 26 16:40:37 2016 by doxygen 1.5.9