using System;

namespace ADOFAIRenderer.Util.Audio.Clip;

/// <summary>
/// Sequential reader of decoded PCM at the clip's own sample rate and channel count.
/// Samples are interleaved 32-bit float. Positions and counts are in frames (one frame = one sample per channel).
/// Used by one thread at a time (the store's decoder thread). <see cref="IDisposable.Dispose"/> may be called more than once.
/// </summary>
internal interface IPCMReader : IDisposable
{
    /// <summary>Channel count of the decoded audio (1 or more).</summary>
    int Channels { get; }

    /// <summary>Sample rate of the decoded audio in Hz.</summary>
    int SampleRate { get; }

    /// <summary>Total frame count of the clip at <see cref="SampleRate"/>.</summary>
    long TotalFrames { get; }

    /// <summary>
    /// True when the data can be read only once, from frame 0 to the end (data is released as it is read).
    /// The source then keeps every chunk (<see cref="ChunkPolicy.Resident"/>).
    /// </summary>
    bool IsForwardOnly { get; }

    /// <summary>Frame index that the next <see cref="Read"/> starts at.</summary>
    long Position { get; }

    /// <summary>
    /// Moves the read position to <paramref name="frame"/> (0 ~ <see cref="TotalFrames"/>).
    /// A forward-only reader accepts only frames whose data has not been released.
    /// </summary>
    void Seek(long frame);

    /// <summary>
    /// Reads up to <paramref name="frameCount"/> frames into <paramref name="buffer"/> starting at index 0 and advances the position.
    /// <paramref name="buffer"/> must hold at least frameCount * Channels floats.
    /// </summary>
    /// <returns>Frames read. 0 at the end of the clip.</returns>
    int Read(float[] buffer, int frameCount);
}