ReturnFrame

1. 概要

ReturnFrame は、指定したフレーム数が経過した後に単一の値を発行して完了するファクトリメソッドです。デフォルトでは次のフレームで発行されます。

ゲームエンジン（Unity など）や UI フレームワークなど、フレーム単位のタイミング制御が必要なシナリオで有用です。

2. シグネチャ

基本（次フレーム）

public static Observable<T> ReturnFrame<T>(T value, CancellationToken cancellationToken = default)

次のフレームで値を発行します。FrameProvider はデフォルトのプロバイダーが使用されます。

Observable.ReturnFrame(42)

FrameProvider 指定

public static Observable<T> ReturnFrame<T>(T value, FrameProvider frameProvider, CancellationToken cancellationToken = default)

使用する FrameProvider を明示的に指定して、次のフレームで値を発行します。

Observable.ReturnFrame(42, myFrameProvider)

フレーム数指定

public static Observable<T> ReturnFrame<T>(T value, int dueTimeFrame, CancellationToken cancellationToken = default)
public static Observable<T> ReturnFrame<T>(T value, int dueTimeFrame, FrameProvider frameProvider, CancellationToken cancellationToken = default)

指定したフレーム数が経過した後に値を発行します。FrameProvider を省略するとデフォルトのプロバイダーが使用されます。

// 5 フレーム後に発行
Observable.ReturnFrame("hello", 5)

// FrameProvider を指定して 10 フレーム後に発行
Observable.ReturnFrame("hello", 10, myFrameProvider)

オーバーロードの使い分け

overload	使う場面
ReturnFrame<T>(T)	次のフレームで値を発行する（最も一般的）
ReturnFrame<T>(T, FrameProvider)	FrameProvider を指定して次フレームで発行する
ReturnFrame<T>(T, int)	指定フレーム数後に発行する
ReturnFrame<T>(T, int, FrameProvider)	FrameProvider とフレーム数の両方を指定する

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

購読後、指定したフレーム数（デフォルトは 1 フレーム）が経過すると値を発行し、直後に完了通知を送ります。

4. サンプルコード

using R3;

// 次のフレームで値を発行
Observable.ReturnFrame(100)
    .Subscribe(x => Console.WriteLine($"値: {x}"));
// 出力（次フレーム）: 値: 100

// 5 フレーム後に値を発行
Observable.ReturnFrame("hello", 5)
    .Subscribe(
        x => Console.WriteLine($"値: {x}"),
        _ => Console.WriteLine("完了"));
// 出力（5 フレーム後）: 値: hello
// 出力: 完了

5. 補足

Return との違い

Return は時間ベース（TimeSpan + TimeProvider）で遅延を指定しますが、ReturnFrame はフレーム数で遅延を指定します。ゲームループなどフレーム駆動の環境では ReturnFrame が適しています。

NextFrame との関係

フレーム単位の遅延で Unit を発行したいだけの場合は、NextFrame がより簡潔です。ReturnFrame は任意の型の値を発行できる点で汎用的です。