NextFrame

1. 概要

NextFrame は、次のフレームで Unit を 1 つ発行して完了するファクトリメソッドです。EveryUpdate の単発版であり、処理を次のフレームに遅延させたいときに使用します。

ゲームエンジン（Unity など）で、現在のフレームの処理完了後に後続の処理を実行したい場合に有用です。

2. シグネチャ

基本

public static Observable<Unit> NextFrame(CancellationToken cancellationToken = default)

デフォルトの FrameProvider を使用して、次のフレームで Unit を発行し完了します。

Observable.NextFrame()

FrameProvider 指定

public static Observable<Unit> NextFrame(FrameProvider frameProvider, CancellationToken cancellationToken = default)

使用する FrameProvider を明示的に指定するオーバーロードです。

Observable.NextFrame(myFrameProvider)

Unity では UnityFrameProvider.Update、UnityFrameProvider.FixedUpdate、UnityFrameProvider.PostLateUpdate などを指定して、「どの PlayerLoop の次フレームで再開するか」を選べます。利用できる Unity 向け Provider は Unity providers を参照してください。

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

overload	使う場面
NextFrame()	デフォルトの FrameProvider で次フレームに遅延する
NextFrame(FrameProvider)	カスタム FrameProvider を使用する

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

購読すると、次のフレームで Unit を 1 つ発行し、直後に完了通知を送ります。

4. サンプルコード

using R3;

// 次のフレームで 1 回だけ発行
Observable.NextFrame()
    .Subscribe(
        _ => Console.WriteLine("次フレームで実行"),
        _ => Console.WriteLine("完了"));
// 出力（次フレーム）: 次フレームで実行
// 出力: 完了

// SelectMany と組み合わせてフレーム遅延を挿入
someObservable
    .SelectMany(_ => Observable.NextFrame())
    .Subscribe(_ => Console.WriteLine("元のイベントの次フレームで実行"));

5. 補足

YieldFrame との違い

YieldFrame も Unit を発行して完了するフレーム遅延 API ですが、待ち方が少し異なります。

NextFrame は購読時点のフレーム番号を記録し、そのフレーム番号の間は発行せず、フレーム番号が進んでから Unit を発行します。「必ず次のフレーム以降に回したい」処理には NextFrame を使います。

一方、YieldFrame は ReturnFrame で Unit を返すユーティリティです。FrameProvider に登録された後、Provider が処理する次のタイミングで Unit を発行します。フレーム番号そのものをまたぐことより、「フレーム処理キューに処理を譲る」意図を表したい場合に向いています。

迷った場合は、Unity の Update 中に「このフレームではなく次フレームで実行したい」なら NextFrame、Yield のフレーム版として軽く処理を譲りたいなら YieldFrame を選ぶと分かりやすいです。

ReturnFrame との違い

ReturnFrame は任意の型の値を次のフレーム（またはフレーム数指定）で発行できます。Unit のみが必要な場合は NextFrame がより簡潔です。

Yield との違い

Yield は TimeProvider ベースの次のタイムステップに遅延します。フレームベースの遅延が必要な場合は NextFrame を使用してください。