using System.Diagnostics.CodeAnalysis;

namespace ADOFAIRenderer.API;

/// <summary>
/// Represents a custom frame modification hook that can modify rendered frames using GPU ping-pong double buffering.
/// </summary>
/// <remarks>
/// <b>Execution Frequency Note:</b> Frame hooks are only invoked for frames that are actually encoded into the final video (<c>VideoFPS</c>).
/// When <c>RenderFPS</c> is higher than <c>VideoFPS</c>, intermediate game render frames are skipped and this hook
/// will <b>not</b> be called on every game frame.
/// </remarks>
[SuppressMessage("ReSharper", "UnusedType.Global")]
public interface IFrameHook
{
    /// <summary>
    /// Invoked for each captured video frame before it is encoded.
    /// </summary>
    /// <remarks>
    /// This method is not called on every rendered game frame if <c>RenderFPS</c> exceeds <c>VideoFPS</c>.
    /// </remarks>
    /// <param name="context">The frame hook context providing access to ping-pong textures and frame metadata.</param>
    void OnRenderFrame(FrameHookContext context);
}