JoltPhysics/Jolt/Physics/Constraints/SpringSettings.h

// Jolt Physics Library (https://github.com/jrouwe/JoltPhysics)
// SPDX-FileCopyrightText: 2023 Jorrit Rouwe
// SPDX-License-Identifier: MIT

#pragma once

#include <Jolt/ObjectStream/SerializableObject.h>

JPH_NAMESPACE_BEGIN

class StreamIn;
class StreamOut;

/// Enum used by constraints to specify how the spring is defined
enum class ESpringMode : uint8
{
	FrequencyAndDamping,		///< Frequency and damping are specified
	StiffnessAndDamping,		///< Stiffness and damping are specified
};

/// Settings for a linear or angular spring
class JPH_EXPORT SpringSettings
{
public:
	JPH_DECLARE_SERIALIZABLE_NON_VIRTUAL(JPH_EXPORT, SpringSettings)

	/// Constructor
								SpringSettings() = default;
								SpringSettings(const SpringSettings &) = default;
	SpringSettings &			operator = (const SpringSettings &) = default;
								SpringSettings(ESpringMode inMode, float inFrequencyOrStiffness, float inDamping) : mMode(inMode), mFrequency(inFrequencyOrStiffness), mDamping(inDamping) { }

	/// Saves the contents of the spring settings in binary form to inStream.
	void						SaveBinaryState(StreamOut &inStream) const;

	/// Restores contents from the binary stream inStream.
	void						RestoreBinaryState(StreamIn &inStream);

	/// Selects the way in which the spring is defined
	/// If the mode is StiffnessAndDamping then mFrequency becomes the stiffness (k) and mDamping becomes the damping ratio (c) in the spring equation F = -k * x - c * v. Otherwise the properties are as documented.
	ESpringMode 				mMode = ESpringMode::FrequencyAndDamping;

	union
	{
		/// Valid when mSpringMode = ESpringMode::FrequencyAndDamping.
		/// If mFrequency > 0 the constraint will be soft and mFrequency specifies the oscillation frequency in Hz.
		/// If mFrequency <= 0, mDamping is ignored and the distance constraint will have hard limits (as hard as the time step / the number of velocity / position solver steps allows).
		float					mFrequency = 0.0f;

		/// Valid when mSpringMode = ESpringMode::StiffnessAndDamping.
		/// If mStiffness > 0 the constraint will be soft and mStiffness specifies the stiffness (k) in the spring equation F = -k * x - c * v for a linear or T = -k * theta - c * w for an angular spring.
		/// If mStiffness <= 0, mDamping is ignored and the distance constraint will have hard limits (as hard as the time step / the number of velocity / position solver steps allows).
		float					mStiffness;
	};

	/// When mSpringMode = ESpringMode::FrequencyAndDamping mDamping is the damping ratio (0 = no damping, 1 = critical damping).
	/// When mSpringMode = ESpringMode::StiffnessAndDamping mDamping is the damping (c) in the spring equation F = -k * x - c * v for a linear or T = -k * theta - c * w for an angular spring.
	/// Note that if you set mDamping = 0, you will not get an infinite oscillation. Because we integrate physics using an explicit Euler scheme, there is always energy loss.
	/// This is done to keep the simulation from exploding, because with a damping of 0 and even the slightest rounding error, the oscillation could become bigger and bigger until the simluation explodes.
	float						mDamping = 0.0f;
};

JPH_NAMESPACE_END