FrameCount

1. 概要

FrameCount は、ソースシーケンスの各要素に現在のフレームカウントを付加するオペレーターです。FrameProvider から取得したフレーム数と元の値のタプル (long FrameCount, T Value) を発行します。

Unity などのゲームエンジン環境で、各値がどのフレームで到着したかを記録したい場合に使用します。

2. シグネチャ

デフォルト FrameProvider によるフレームカウント付加

public static Observable<ValueTuple<long, T>> FrameCount<T>(
    this Observable<T> source)

デフォルトの FrameProvider を使用して、各要素にフレームカウントを付加します。

source.FrameCount()

FrameProvider 指定によるフレームカウント付加

public static Observable<ValueTuple<long, T>> FrameCount<T>(
    this Observable<T> source,
    FrameProvider frameProvider)

指定した FrameProvider を使用してフレームカウントを取得します。テスト時に FakeFrameProvider を使用可能です。

source.FrameCount(fakeFrameProvider)

overload の使い分け

overload	使う場面
引数なし	Unity などでデフォルトのフレームプロバイダーを使う場合
FrameProvider	テスト時や独自のフレームプロバイダーを使いたい場合

3. マーブルダイアグラム

各要素に到着時点のフレームカウントが付加されます。元の値はタプルの第 2 要素としてそのまま保持されます。

4. サンプルコード

using R3;

// 各イベントのフレームカウントを記録
inputObservable
    .FrameCount()
    .Subscribe(item =>
    {
        var (frame, value) = item;
        Console.WriteLine($"[Frame {frame}] 値: {value}");
    });

// FakeFrameProvider を使ったテスト
var fakeFrames = new FakeFrameProvider();
var results = new List<(long, int)>();

var subject = new Subject<int>();
subject
    .FrameCount(fakeFrames)
    .Subscribe(item => results.Add(item));

fakeFrames.Advance(10);
subject.OnNext(42);
// results: [(10, 42)]

fakeFrames.Advance(5);
subject.OnNext(99);
// results: [(10, 42), (15, 99)]

5. 補足

Timestamp / FrameInterval との違い

オペレーター	付加する値	型	基準
Timestamp	到着時刻（ticks）	(long, T)	実時間
FrameCount	到着フレーム番号	(long, T)	フレーム
FrameInterval	前回からのフレーム経過数	(long, T)	フレーム（相対）

FrameCount は絶対的なフレーム番号を付加するのに対し、FrameInterval は相対的なフレーム経過数を付加します。Timestamp は実時間版の類似オペレーターです。