Monogame-Extended/source/MonoGame.Extended/Particles/Modifiers/Modifier.cs

// Copyright (c) Craftwork Games. All rights reserved.
// Licensed under the MIT license.
// See LICENSE file in the project root for full license information.

namespace MonoGame.Extended.Particles.Modifiers;

/// <summary>
/// Represents a base class for all particle modifiers.
/// </summary>
/// <remarks>
/// Particle modifiers are used to alter the behavior or properties of particles during their lifetime.
/// Each modifier applies changes to particles at a configurable frequency, optimizing performance by
/// spreading updates across frames when appropriate.
/// Custom modifiers should inherit from this class and implement the <see cref="Update"/> method.
/// </remarks>
public abstract class Modifier
{
    private const float DEFAULT_MODIFIER_FREQUENCY = 60.0f;

    /// <summary>
    /// Gets or sets the display name of this modifier.
    /// </summary>
    public string Name;

    /// <summary>
    /// Gets or sets the update frequency of this modifier.
    /// </summary>
    /// <remarks>
    /// This value defines how often, in times per second, the modifier attempts to update
    /// the entire particle buffer. For example, a value of 60.0f means that all particles
    /// will be updated collectively approximately 60 times per second.
    ///
    /// To improve performance, updates are distributed across frames. Rather than updating
    /// every particle in every frame, the modifier mathematically distributes updates by
    /// processing a portion of the particles each frame based on the elapsed time and the
    /// desired frequency. Over time, this results in all particles being updated at the
    /// specified frequency on average, regardless of the actual frame rate.
    ///
    /// Higher values result in more frequent updates and smoother particle behavior, at the
    /// cost of performance. Lower values reduce CPU usage but may make particle changes appear
    /// less fluid.
    /// </remarks>
    public float Frequency;

    /// <summary>
    /// Indicates whether this modifier is enabled.
    /// </summary>
    /// <remarks>
    /// This value determines if this modifier is enabled.  When a modifier is disabled, the modifier is not applied
    /// to the particles.
    /// </remarks>
    public bool Enabled;

    /// <summary>
    /// Initializes a new instance of the <see cref="Modifier"/> class.
    /// </summary>
    /// <remarks>
    /// The default constructor sets the <see cref="Name"/> property to the name of the derived class
    /// and initializes <see cref="Frequency"/> to <see cref="DEFAULT_MODIFIER_FREQUENCY"/>.
    /// </remarks>
    protected Modifier()
    {
        Name = GetType().Name;
        Frequency = DEFAULT_MODIFIER_FREQUENCY;
        Enabled = true;
    }

    /// <summary>
    /// Updates the properties of particles according to this modifier's specific behavior.
    /// </summary>
    /// <param name="elapsedSeconds">The elapsed time, in seconds, since the last update.</param>
    /// <param name="iterator">The iterator used to iterate the particles ot update.</param>
    public abstract void Update(float elapsedSeconds, ParticleIterator iterator);
}