FilterFrame

用途：滤镜/背景渲染器的输入帧只读视图——提供尺寸、音乐时间、进度、游玩上下文快照与绘制入口。

完整签名

public interface FilterFrame {

    int width();

    int height();

    long musicTimeMs();

    double progress();

    RenderCanvas canvas();

    GameplayContext context();

    RenderLayer layer();

    int zOrder();
}

width() / height()

签名：

int width();

int height();

行为：帧尺寸（像素）。滤镜/背景绘制通常铺满这个范围。

musicTimeMs()

签名：

long musicTimeMs();

行为：当前音乐时间（毫秒），可用于按节拍做脉冲等效果。

progress()

签名：

double progress();

行为：游玩进度 0-1（0 = 开始，1 = 结束）。

canvas()

签名：

RenderCanvas canvas();

行为：本帧的绘制入口，滤镜/背景在此画布上修改最终画面。

context()

签名：

GameplayContext context();

行为：当前游玩上下文快照（combo / accuracy / misses / lanes 等）。返回不可变快照，持有引用不会泄漏后续状态变化。

layer() / zOrder()

签名：

RenderLayer layer();

int zOrder();

行为：layer() 为当前回调所在层——背景渲染器回调时为 BACKGROUND，滤镜回调时为 FULLSCREEN；zOrder() 为该回调声明（或透传）的层号，便于自绘内容按同一口径排序。