TSMPDecoder

ヘッダーと本文の直接出力

useCombinedByteOutput の既定値は true です。予測経路では対応コーデックが復元済みの56バイトヘッダーと本文を専用の RGBA8 readback テクスチャへ直接出力し、別の結合パスと本文の中間出力を省きます。元画像のスナップショット、ヘッダー CRC 検証、長さの完全一致と同じ画像でのフォールバックは維持されます。送信データグラムは変わらず、一定の受信率を保証する機能ではありません。

シェーダーが _TSMPHeaderTex と _TSMPHeaderPixels の両方を実装すると使用できます。未対応の既存コーデックは別の結合パスを使用します。比較用の設定は Diagnostics > Advanced Decode にあります。combinedByteOutputCount は投入回数であり、後から拒否・再処理された予測も含みます。受信フレーム数ではありません。ResetDecodeDiagnostics() でリセットします.

TSMPDecoder は、TSMP テクスチャを読み取り、ヘッダーを検証し、選択されたコーデックにペイロード バイトを回復するように要求し、変数/RPC メッセージをバインドされた動作に適用します。

このページは、カスタム レシーバーの配線、診断の読み取り、またはフレームが無視された理由のデバッグを行うときに使用します。

コンポーネントフィールド

分野	目的
sourceTexture	エンコードされた TSMP フレームを含むテクスチャ。
payloadByteTexture	ペイロード バイトをデコードするときにコーデック シェーダによって使用されるテクスチャをレンダリングします。
codecHandlers	デコーダで使用できるコーデック コンポーネント。ヘッダー codecId はハンドラーを選択します。
applyEveryFrame	コンポーネント更新ループからデコードを実行します。別のスクリプトが DecodeNow() を呼び出すときは無効にします。
skipDuplicateFrames	現在のストリームの重複・古いフレームを除外します。Inspector 表示は Filter Frames です。
frameWindowSize	Window Size。既定256フレーム、実効最小値1。フレーム0の再開判定に使用し、バッファは確保しません。
flipY	画像を反転するキャプチャ パスのテクスチャ サンプリングを反転します。
useHeaderPayloadLayout	ヘッダー ペイロード メタデータを使用してリードバックのサイズを決定します。通常の使用では有効にしておいてください。
payloadBytesOverride	テスト パスの手動ペイロード バイト数。
decodeSafetyMode	変形したフレームまたは部分的なフレームのための追加のガード。
usePredictedReadback	既定 true。前回検証した設定でヘッダーと payload をまとめて読み取ります。手動レイアウトと安全モードでは使用しません。
useCombinedByteOutput	既定 true。対応コーデックのシェーダーがヘッダー/payload の結合 readback テクスチャへ直接出力します。
overlapReadbacks	既定 true。独立してキャプチャした最大2フレームを同時に処理し、false では1フレームのみ受理します。

TSMPSetup は通常、sourceTexture、バイト テクスチャ、コーデック ハンドラー、およびバインディング配列を割り当てます。

ヘッダーの検証

次の場合、デコーダは payload メッセージを適用する前にフレームを拒否します。

• マジックバイトはTSMPではありません。
• ヘッダー サイズはサポートされていません。
• メジャー プロトコル バージョンはサポートされていません。
• ヘッダーの CRC が一致しません。
• ペイロード サイズが利用可能なテクスチャ レイアウトを超えています。

CRC エラーは警告として記録されます。これは、不正なデータを適用せずにキャプチャの破損を特定するのに役立ちます。

DecodeNow()

public void DecodeNow()

現在の画像をキャプチャし、非同期デコードを開始します。applyEveryFrame が無効でも呼べますが、コンポーネントは有効である必要があります。既定の overlapReadbacks=true では最初の結果を待つ間に2枚目を開始できます。両スロットが埋まると呼び出しをスキップし、別の画像キューは作りません。false では保留を1枚に制限します。結果適用中の再入呼び出しはキャプチャしません。

初回とフォールバック経路では次の順序で実行します。

1. 現在の入力画像を decoder のスナップショットへコピーします。
2. スナップショットからヘッダーピクセルを読み取ります。
3. マジック、バージョン、ペイロード レイアウト、および CRC を検証します。
4. codecId でコーデック ハンドラーを選択します。
5. 同じスナップショットからペイロードバイトをデコードします。
6. ネットワークメッセージを解析します。
7. 変数を適用し、RPC 呼び出しをディスパッチします。

予測 readback

有効なヘッダーを学習した後は、CPU がヘッダーを待たず、前回の設定で現在の画像の Luma4 ヘッダーパスと payload パスを実行できます。復元バイトを専用の linear RGBA8 ターゲットにまとめて1回だけ readback します。このバイトターゲットは入力形式を維持するスナップショットとは別です。

現在のヘッダーの magic、version、size、CRC と通常のフレーム順序検査を通過する必要があります。CRC より前のバイトは、フレーム番号・時刻・payload 長を除いてキャッシュと一致する必要があります。payload 長は別途完全一致を検査し、解釈後の block/sample/start-block 設定も比較します。長さの増減、コーデック・オプション・ストリーム・レイアウトなどの変更があれば、推測した payload を破棄し、同じスナップショットから実際の payload を要求します。元画像は再キャプチャしません。CRC 不一致では、未検証データへフォールバックせずフレームを破棄します。

長さの完全一致により、カスタムコーデックへ多くのバイトを要求した場合も同じ先頭データが得られるとは仮定しません。既存のコーデック API とシェーダーは変更せず、各パスの PrepareDecode も呼び出します。無効化、入力サイズ・向きの変更、手動レイアウト・安全モードの使用後はヘッダーを再学習します。結合リソースがなければ逐次経路を使います。マテリアルは Editor とビルド準備で自動設定し、通常 Unity の実行時生成ではパッケージのリソースから読み込みます。

各スロットの内部 readback バッファの 0..55 はヘッダー、56 以降は予測 payload、残りは行パディングです。送信データグラムの変更ではありません。 各スロットが14x1のヘッダーと、幅 min(256, ceil((56 + payloadBytes)/4)) に必要な行数を持つ結合テクスチャを所有し、1ピクセル4バイトで再利用します。無効化時は未使用リソースを即時解放し、保留スロットはキャンセルしてコールバック到着後に解放します。コンポーネント破棄時は所有ターゲットを解放します。

predictedReadbackCount は採用した予測 payload 数で、RPC の実行成功数ではありません。predictionFallbackCount は有効なヘッダーで予測不一致となりフォールバックした回数です。Runtime Status に表示されます。重複・古いフレームでも推測 GPU 処理が実行済みの場合はありますが、メッセージを解析・適用しません。60Hz 配送は保証せず、適用率・遅延・RPC 実行率を個別に測定してください。

入力スナップショット

Inspector に追加設定は不要です。各スロットが入力と同じサイズの RenderTexture を所有して再利用します。判別可能な RGBA/BGRA 8-bit 入力には linear/sRGB 解釈を維持した ARGB32、RGBA half-float 入力には linear ARGBHalf を使います。Float32 と不明な入力には linear ARGBFloat を維持します。Native Unity は graphics format を参照し、Udon は RenderTexture の format と sRGB 状態だけを参照するため、他の入力型では保守的に Float32 を使います。形式変更時は空きストレージを再生成します。割り当て失敗は lastError で通知して拒否し、更新中の元画像には戻りません。

割り当て済みスロットごとの保存量は width * height * bytesPerPixel で、上記の形式では1ピクセル4・8・16バイトです。8-bit スナップショット2枚は1280x720で約7.03 MiB、3840x2160で約63.28 MiBとなり、Float32 の2枚より75%少なくなります。他のテクスチャやドライバー費用は含みません。開始した処理では全入力を1回コピーし、後で CRC・重複検査に失敗してもコピー費用は発生します。CPU readback は追加しません。実機で GPU 費用を測定してください。

キャプチャ後に sourceTexture を差し替えたり破棄したりしても、現在の画像は変わらず、変更は次の処理に反映されます。無効化は使用中の全スロットをキャンセルし、再有効化後の古いコールバックも破棄します。キャンセル済みスロットは要求完了まで再利用しません。native と Udon の両方でヘッダー・LUT 準備・payload は同じスナップショットを使用します。カスタムコーデックは画像を読み取り専用とし、恒久的なコピーとして保持しないでください。適用はトランザクション方式ではありません。

制限付き readback 並行処理

overlapReadbacks は Diagnostics > Advanced Decode にあります。2スロットが画像、予測メタデータ、読み取りバッファ、フォールバック状態を個別に保持します。Udon は要求オブジェクトの同一性、通常 Unity はスロット別コールバックで結果を識別し、完了順序を仮定しません。適用はキャプチャ順です。後の結果が先に届いても前のスロットのフォールバック完了まで待ち、既存のフレーム順序検査と RPC 重複抑制を維持します。失敗・キャンセルされた先頭は本文を適用せず除去し、後続を進めます。

readbackInFlight は前の結果を待つ完了済みスロットも含め、未処理フレームがあることを示します。pendingDecodeCount は 0..2 です。skippedBusyDecodeCount は容量不足で拒否したキャプチャ試行数であり、固有の欠落映像フレーム数ではありません。ResetDecodeDiagnostics() でリセットします。

上記の式は1スロット単位ですが、数値例はすでにスナップショット2枚分の合計です。バイトターゲットと管理バッファのメモリは別途必要です。処理中に並行処理を無効にすると空きができるまで新規要求を制限しますが、受け付けたフレームの破棄や保持メモリの即時解放はしません。キャプチャ機会を増やす代わりにメモリ・遅延・GPU/CPU 費用が増える可能性があります。readback 自体の高速化、60Hz の保証、入力へ届かなかったフレームの復元を行う機能ではありません。

ウィンドウとフレーム順序

フィルターが有効な場合、受信番号 N と現在のストリームで最後に適用に成功した番号 P を比較します。実効ウィンドウは W = max(1, frameWindowSize) です。変更は次のヘッダー判定から反映されます。

1. 適用履歴がない場合、または StreamId が異なる場合は、順序を比較せず候補を許可します。
2. N == P は重複として除外します。
3. D = (N - P) modulo 2^32 を計算し、0 < D < 2^31 なら番号の正常な周回も含めて新しいフレームとして許可します。
4. それ以外でも N == 0 かつ P >= W なら再開と推定して許可します。
5. 残りは古い、または順序が不明なフレームとして除外します。UInt32 範囲のちょうど半分の差も、フレーム0の再開例外を除き拒否します。

許可は payload 処理へ進むという意味で、無条件の適用ではありません。ネットワークフレームの適用成功時だけ基準ストリームと番号を更新します。壊れた payload、取り消した要求、ヘッダー/readback 専用安全モードでは基準を更新しません。重複・逆順で除外した場合は従来の重複処理と同様に lastFrameValid=true です。skippedDuplicateFrameCount と skippedOutOfOrderFrameCount に別々に集計し、lastError に状態を表示します。推測したバイトデコード・readback が完了済みでも payload メッセージの解析・実行は行いません。

W=256 では 100 -> 101 -> 100 の最後の100を除外し、255 -> 0 は拒否、256 -> 0 -> 1 は再開と後続フレームとして許可します。4294967295 -> 0 はウィンドウによらず正常な周回です。W=512 では 256 -> 0 を拒否します。ウィンドウはフレーム数のしきい値であり、時間、スライディング履歴、保存するテクスチャの集合ではありません。

セッション ID のない推定規則です。遅れて届いた過去の0を再開と誤認する場合があり、再開時の0が欠落した場合や1ウィンドウ未満での再開はこの例外では検出できません。リセット受理後は大きな番号の過去フレームも新しく見える可能性があります。別ストリームは許可し、適用成功時に基準を置き換えますが、過去のストリーム履歴は保持しません。RPC イベントの重複判定は変更・初期化しません。skipDuplicateFrames を無効にすると重複・順序判定と再開規則をすべて迂回します。録画のシークに使えますが、過去の変数値も再適用されます。

データグラム互換性

データグラムとプロトコルバージョンは変更しません。ヘッダーは56バイト、payload形式も従来どおりです。20..23 は StreamId UInt32 LE、24..27 は FrameIndex UInt32 LE、28..31 は TimestampMs UInt32 LE で、この判定に時刻は使いません。予約領域 44..49 は引き続き0です。CRC32 は 0..51 を対象とし 52..55 に保存します。ウィンドウサイズもセッション ID も送信しません。他のフィールドはフレームレイアウトを参照してください。既存送信側の変更は不要で、受信側の採用規則のみが変わります。

ResetDecodeDiagnostics()

public void ResetDecodeDiagnostics()

エラーログの出力予算と予測 readback・フォールバック・結合出力・容量不足キャプチャのカウンターを初期化します。保留中のスロットの取り消しや、既存のフレーム・RPC カウンターと順序判定に使う最後の適用ストリーム・フレームの初期化は行いません。

診断

メンバー	意味
lastFrameValid	最後のフレームはすべてのデコード ステージを通過しました。
lastHeaderValid	ヘッダーはペイロードをデコードする前に有効でした。
lastError	最後のデコーダ エラーまたは警告テキスト。
lastNetworkMessageCount	デコードされたネットワーク フレーム内で見つかったメッセージの数。
lastAppliedVariableCount	動作に適用される変数の数。
lastRpcCallCount	ディスパッチされた RPC メッセージの数。
lastCodecId	最後の有効なヘッダーから読み取られたコーデック ID。
lastFrameIndex	ヘッダーから読み取られるフレーム インデックス。
lastPayloadBytes	デコーダによって使用されるペイロードのバイト数。

製本申請書

デコーダは、TSMPSetup によって生成されたバインディング配列を使用します。各バインディング マップは次のとおりです。

• networkId
• variableHash
• 値の型
• ターゲット行動
• 対象フィールド名
• 同期方向

変数メッセージが到着すると、デコーダーはそれを一致するバインディングにのみ適用します。 RPC メッセージが到着すると、デコーダはそれを一致する TSMPNetworkBehaviour にディスパッチします。

ランタイムルール

• ヘッダーは有効だがコーデック ID が不明なフレームは無視されます。
• ターゲット動作の ReceiveInterpolation.None は、その動作では受信した値が無視されることを意味します。
• RPC 呼び出しはイベントのようなものです。トランスポートがフレームをドロップする場合は、エンコーダでリピート フレームを使用します。
• アップロードされたワールドではインスペクター フィールドが表示されないため、デコーダーは重要な実行時エラーをログに記録します。