play3d method

Future<SoundHandle> play3d(AudioSource sound, double posX, double posY, double posZ, { double velX = 0, double velY = 0, double velZ = 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).

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

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

  final ret = _controller.soLoudFFI.play3d(
    sound.soundHash,
    posX,
    posY,
    posZ,
    velX: velX,
    velY: velY,
    velZ: velZ,
    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;
}