R3 日本語リファレンス

Appearance

YieldFrame ​

1. 概要 ​

YieldFrame は、次のフレームで Unit を 1 つ発行して完了するファクトリメソッドです。Yield のフレームベース版であり、FrameProvider を介して次のフレームまで処理を遅延させます。

2. シグネチャ ​

基本 ​

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

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

csharp
Observable.YieldFrame()

FrameProvider 指定 ​

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

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

csharp
Observable.YieldFrame(myFrameProvider)

Unity では UnityFrameProvider.Update、UnityFrameProvider.FixedUpdate、UnityFrameProvider.PostLateUpdate などを指定して、次フレームへ遅延する PlayerLoop タイミングを選べます。利用できる Unity 向け Provider は Unity providers を参照してください。

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

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

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

YieldFrame のマーブルダイアグラム

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

4. サンプルコード ​

csharp
using R3;

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

// FrameProvider を指定
Observable.YieldFrame(myFrameProvider)
    .Subscribe(_ => Console.WriteLine("次フレームで実行"));

// Concat で 2 フレームにまたがる処理
Observable.YieldFrame()
    .Select(_ => "フレーム 1")
    .Concat(Observable.YieldFrame().Select(_ => "フレーム 2"))
    .Subscribe(x => Console.WriteLine(x));
// 出力:
// フレーム 1
// フレーム 2

5. 補足 ​

Yield との違い ​

Yield は TimeProvider ベースの次のタイムステップに遅延します。YieldFrame は FrameProvider ベースの次のフレームに遅延します。フレームの概念がない環境では Yield を、ゲームエンジンなどでは YieldFrame を使用してください。

NextFrame との違い ​

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

YieldFrame は ReturnFrame で Unit を返すユーティリティです。FrameProvider に登録された後、Provider が処理する次のタイミングで Unit を発行します。await Task.Yield() や Yield に近い感覚で、「今すぐ続けずにフレーム処理キューへ譲る」意図を表したい場合に向いています。

一方、NextFrame は購読時点のフレーム番号を記録し、そのフレーム番号の間は発行せず、フレーム番号が進んでから Unit を発行します。Unity の Update 中などで「このフレームではなく、必ず次のフレーム以降に実行したい」場合は NextFrame を選びます。

迷った場合は、フレーム番号をまたぐ保証を重視するなら NextFrame、Yield のフレーム版として軽く処理を譲るなら YieldFrame を使うと分かりやすいです。