Firelight Technologies FMOD Studio API

System::playDSP

Plays a DSP unit object and its input network on a particular channel.

C++ Syntax

FMOD_RESULT System::playDSP(
  FMOD::DSP *dsp,
  FMOD::ChannelGroup *channelgroup,
  bool paused,
  FMOD::Channel **channel
);

C Syntax

FMOD_RESULT FMOD_System_PlayDSP(
  FMOD_SYSTEM *system,
  FMOD_DSP *dsp,
  FMOD_CHANNELGROUP *channelgroup,
  FMOD_BOOL paused,
  FMOD_CHANNEL **channel
);

Parameters

dsp
Pointer to the dsp unit to play. This is opened with System::createDSP, System::createDSPByType, System::createDSPByPlugin.
channelgroup
Pointer to a channelgroup become a member of. This is more efficient than using Channel::setChannelGroup, as it does it during the channel setup, rather than connecting to the master channel group, then later disconnecting and connecting to the new channelgroup when specified. Use 0/NULL to ignore.
paused
True or false flag to specify whether to start the channel paused or not. Starting a channel paused allows the user to alter its attributes without it being audible, and unpausing with Channel::setPaused actually starts the dsp running.
channel
Address of a channel handle pointer that receives the newly playing channel.

Return Values

If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.

Remarks

When a dsp is played, it will use the dsp's default frequency, volume, pan, levels and priority.

A dsp defined as FMOD_3D will by default play at the position of the listener.

To change channel attributes before the dsp is audible, start the channel paused by setting the paused flag to true, and calling the relevant channel based functions. Following that, unpause the channel with Channel::setPaused.

Channels are reference counted. If a channel is stolen by the FMOD priority system, then the handle to the stolen voice becomes invalid, and Channel based commands will not affect the new channel playing in its place.
If all channels are currently full playing a dsp or sound, FMOD will steal a channel with the lowest priority dsp or sound.
If more channels are playing than are currently available on the soundcard/sound device or software mixer, then FMOD will 'virtualize' the channel. This type of channel is not heard, but it is updated as if it was playing. When its priority becomes high enough or another sound stops that was using a real hardware/software channel, it will start playing from where it should be. This technique saves CPU time (thousands of sounds can be played at once without actually being mixed or taking up resources), and also removes the need for the user to manage voices themselves.
An example of virtual channel usage is a dungeon with 100 torches burning, all with a looping crackling sound, but with a soundcard that only supports 32 hardware voices. If the 3D positions and priorities for each torch are set correctly, FMOD will play all 100 sounds without any 'out of channels' errors, and swap the real voices in and out according to which torches are closest in 3D space.
Priority for virtual channels can be changed in the sound's defaults, or at runtime with Channel::setPriority.

See Also




Version 1.03.06 Built on Apr 17, 2014