Function SoundEffect

TombEngine/Sound/sound.cpp:168–337

TODO: Use std::optional for pose argument.

// TODO: Use std::optional for pose argument.
bool SoundEffect(int soundID, Pose* pose, SoundEnvironment soundEnv, float pitchMult, float gainMult)
{
	if (!g_Configuration.EnableSound)
		return false;

	if (soundID >= g_Level.SoundMap.size())
		return false;

	if (BASS_GetDevice() == -1)
		return false;

	// Test if sound effect environment matches camera environment.
	if (soundEnv != SoundEnvironment::Always)
	{
		bool isCameraUnderwater = TestEnvironment(ENV_FLAG_WATER, Camera.pos.RoomNumber);
		if ((soundEnv == SoundEnvironment::Underwater && !isCameraUnderwater) ||
			(soundEnv != SoundEnvironment::Underwater && isCameraUnderwater))
		{
			return false;
		}
	}

	// Get actual sample index from sound map.
	int sampleIndex = g_Level.SoundMap[soundID];

	// -1 means no such effect exists in level file.Set to -2 afterwards to prevent further debug message firings.
	if (sampleIndex == -1)
	{
		TENLog("Missing sound effect " + std::to_string(soundID), LogLevel::Warning);
		g_Level.SoundMap[soundID] = -2;
		return false;
	}
	else if (sampleIndex == -2)
	{
		return false;
	}

	const auto& sample = g_Level.SoundDetails[sampleIndex];
	if (sample.Number < 0)
	{
		TENLog("No valid samples count for effect " + std::to_string(sampleIndex), LogLevel::Warning);
		return false;
	}

	// Assign common sample flags.
	DWORD sampleFlags = SOUND_SAMPLE_FLAGS;

	// Test play chance.
	if (sample.Randomness && ((GetRandomControl() & UCHAR_MAX) > sample.Randomness))
		return false;

	// Apply 3D attribute only to sound with position property.
	if (pose != nullptr)
		sampleFlags |= BASS_SAMPLE_3D;

	// Set and randomize volume (if needed).
	float gain = ((float)sample.Volume / UCHAR_MAX) * std::clamp(gainMult, SOUND_MIN_PARAM_MULTIPLIER, SOUND_MAX_PARAM_MULTIPLIER);
	if ((sample.Flags & SOUND_FLAG_RND_GAIN))