ADOFAIRenderer/Util/Audio/Clip/MemoryPCMReader.cs

using System;
using System.Collections.Generic;

namespace ADOFAIRenderer.Util.Audio.Clip;

/// <summary>
/// Forward-only <see cref="IPCMReader"/> over PCM held in memory as a list of blocks.
/// Block b holds frames [b * FramesPerBlock, (b + 1) * FramesPerBlock) interleaved; the last block may be shorter.
/// Each block is released (passed to the release callback and dropped) as soon as the read position passes its end,
/// and all remaining blocks are released on <see cref="Dispose"/>.
/// </summary>
internal sealed class MemoryPCMReader : IPCMReader
{
    /// <summary>Block arrays; an entry is set to null when the block is released.</summary>
    private readonly float[]?[] _blocks;

    /// <summary>Called with each released block (for example to uncount its memory in the store); may be null.</summary>
    private readonly Action<float[]>? _onBlockReleased;

    private int _releasedCount; // Blocks [0, _releasedCount) are released

    /// <inheritdoc/>
    public int Channels { get; }

    /// <inheritdoc/>
    public int SampleRate { get; }

    /// <inheritdoc/>
    public long TotalFrames { get; }

    /// <summary>True: blocks are released as they are read.</summary>
    public bool IsForwardOnly => true;

    /// <inheritdoc/>
    public long Position { get; private set; }

    /// <summary>Frames per block (all blocks except the last).</summary>
    public int FramesPerBlock { get; }

    /// <param name="blocks">Interleaved blocks in frame order; the reader takes ownership of the arrays (the list is copied).</param>
    /// <param name="framesPerBlock">Frames in every block except possibly the last (positive).</param>
    /// <param name="channels">Channel count (positive).</param>
    /// <param name="sampleRate">Sample rate in Hz.</param>
    /// <param name="totalFrames">Frame count; the blocks must hold at least this many frames.</param>
    /// <param name="onBlockReleased">Called with each block when it is released; may be null.</param>
    public MemoryPCMReader(IReadOnlyList<float[]> blocks, int framesPerBlock, int channels, int sampleRate, long totalFrames,
        Action<float[]>? onBlockReleased)
    {
        if (channels <= 0) throw new ArgumentOutOfRangeException(nameof(channels));
        if (framesPerBlock <= 0) throw new ArgumentOutOfRangeException(nameof(framesPerBlock));
        if (totalFrames > (long)blocks.Count * framesPerBlock) throw new ArgumentException("Blocks hold fewer frames than totalFrames.", nameof(blocks));

        _blocks = new float[blocks.Count][];
        for (var i = 0; i < blocks.Count; i++) _blocks[i] = blocks[i];
        _onBlockReleased = onBlockReleased;
        FramesPerBlock = framesPerBlock;
        Channels = channels;
        SampleRate = sampleRate;
        TotalFrames = totalFrames;
    }

    /// <inheritdoc/>
    /// <exception cref="InvalidOperationException"><paramref name="frame"/> lies in a block that was already released.</exception>
    public void Seek(long frame)
    {
        if (frame < 0 || frame > TotalFrames) throw new ArgumentOutOfRangeException(nameof(frame));
        if (frame < (long)_releasedCount * FramesPerBlock)
            throw new InvalidOperationException($"Frame {frame} was already released by the forward-only reader.");
        Position = frame;
    }

    /// <inheritdoc/>
    /// <remarks>Blocks whose end the position has passed are released after each copy.</remarks>
    public int Read(float[] buffer, int frameCount)
    {
        var total = (int)Math.Min(frameCount, TotalFrames - Position);
        if (total <= 0) return 0;

        var written = 0;
        while (written < total)
        {
            var blockIndex = (int)(Position / FramesPerBlock);
            var block = _blocks[blockIndex] ?? throw new InvalidOperationException($"Block {blockIndex} was already released.");
            var offset = (int)(Position - (long)blockIndex * FramesPerBlock);
            var count = Math.Min(total - written, FramesPerBlock - offset);
            Array.Copy(block, offset * Channels, buffer, written * Channels, count * Channels);
            written += count;
            Position += count;
            ReleaseBlocksBefore((int)(Position / FramesPerBlock));
        }
        return written;
    }

    /// <summary>Releases every block with an index below <paramref name="blockIndex"/> that is not released yet, in order.</summary>
    private void ReleaseBlocksBefore(int blockIndex)
    {
        while (_releasedCount < blockIndex && _releasedCount < _blocks.Length)
        {
            var block = _blocks[_releasedCount];
            _blocks[_releasedCount] = null;
            _releasedCount++;
            if (block != null) _onBlockReleased?.Invoke(block);
        }
    }

    /// <summary>Releases every remaining block. Safe to call more than once.</summary>
    public void Dispose() => ReleaseBlocksBefore(_blocks.Length);
}