play3d method

SoundHandle play3d(AudioSource sound, double posX, double posY, double posZ, { double velX = 0, double velY = 0, double velZ = 0, int busId = 0, double volume = 1, bool paused = false, bool looping = false, Duration loopingStartAt = Duration.zero, })

This function is the 3D version of the play call.

The coordinate system is right handed.

          Y
          ^
          |
          |
          |
          --------> X
         /
        /
       Z

The listener position is (0, 0, 0) by default but can be changed with set3dListenerParameters.

The parameters posX, posY and posZ are the audio source's position coordinates.

The parameters velX, velY and velZ are the audio source's velocity. Defaults to (0, 0, 0).

busId is the bus on which to play the sound. By default it is 0, which means the sound will be played on the default player engine. If a mixing bus has already been created, you can provide its busId to play the sound on that bus or you can use the comfy Bus.play method. See Bus for more information.

The rest of the parameters are equivalent to the non-3D version of this method (play).

Returns the SoundHandle of this new sound.

Note: by default, the maximum number of sounds you can play is 16 and it can be changed with setMaxActiveVoiceCount. If this limit is reached and other instances of the same sound are played, the oldest one will be stopped to make room to play the new sound. If there are no instances of the sound and the max limit is reached, a warning will be printed and the sound will not play.

Throws SoLoudNotInitializedException if the engine is not initialized.

Throws SoLoudBufferStreamCanBePlayedOnlyOnceCppException if we try to play a BufferStream using release buffer type more than once.

Implementation

SoundHandle play3d(
  AudioSource sound,
  double posX,
  double posY,
  double posZ, {
  double velX = 0,
  double velY = 0,
  double velZ = 0,
  int busId = 0,
  double volume = 1,
  bool paused = false,
  bool looping = false,
  Duration loopingStartAt = Duration.zero,
}) {
  if (!isInitialized) {
    throw const SoLoudNotInitializedException();
  }

  final ret = _controller.soLoudFFI.play3d(
    sound.soundHash,
    posX,
    posY,
    posZ,
    velX: velX,
    velY: velY,
    velZ: velZ,
    busId: busId,
    volume: volume,
    paused: paused,
    looping: looping,
    loopingStartAt: loopingStartAt,
  );

  _logPlayerError(ret.error, from: 'play3d()');
  if (!(ret.error == PlayerErrors.noError ||
      ret.error == PlayerErrors.maxActiveVoiceCountReached)) {
    throw SoLoudCppException.fromPlayerError(ret.error);
  }

  final filtered = _activeSounds
      .where((s) => s.soundHash == sound.soundHash)
      .toSet();
  if (filtered.isEmpty) {
    _log.severe(() => 'play3d(): soundHash ${sound.soundHash} not found');
    throw SoLoudSoundHashNotFoundDartException(sound.soundHash);
  }

  assert(filtered.length == 1, 'Duplicate sounds found');
  for (final activeSound in filtered) {
    activeSound.handlesInternal.add(ret.newHandle);
  }
  sound.handlesInternal.add(ret.newHandle);
  return ret.newHandle;
}