vvvv-patching

vvvv パッチングパターン

データフローの基本

• サブグラフ内では上から下への依存関係の流れに従います。同階層のサブグラフは 2D キャンバス上で左から右へ読みます。位置は実行順序を決定しません。
• リンクはパッド（入力/出力の接続点）間でデータを運びます
• スプレッディング — Spread<T> を単一値の入力に接続すると、ノードが自動的に反復されます
• 毎フレーム、接続されたグラフ全体が評価されます。接続されていないサブグラフはスキップされます

ビジュアルパッチと C# ソースプロジェクトはどちらもライブ環境で動作します — プログラムの実行中に編集が即座に反映されます。パッチの変更はノードの状態を保持しますが、C# コードの変更はノードの再起動（Dispose → Constructor）を引き起こします。結果をリアルタイムで確認しながら、パラメーターの調整、接続の追加、パッチの再構成を行えます。

パッチと C# の使い分け

パッチ	コード（C#）
データフローのルーティング、ビジュアル接続	パフォーマンスが重要なアルゴリズム
プロトタイピングとパラメーター調整	複雑なステートマシン
UI の構成とレイアウト	.NET ライブラリとの相互運用
単純な変換	ネイティブリソースの管理

原則として：データフローはパッチ、アルゴリズムはコードで。

リージョン

実行可能な制御フローリージョンには評価セマンティクスがあります。ビジュアルなヘルプパッチの フレームは XML の Overlay であり、実行を制御せずに表示をグループ化するものです。

リージョンは実行フローを制御するビジュアルな構成要素です：

リージョン	目的	C# の相当機能
ForEach	Spread の要素を反復する	foreach ループ
If	条件付き実行	if/else
Switch	複数分岐の選択	switch
Repeat	N 回ループする	for ループ
Accumulator	累積的な集計	Aggregate/Fold

パッチ内の Process ノード

Process ノードはパッチに状態を追加する主要な方法です：

• Create リージョン（一度だけ実行）と Update リージョン（毎フレーム実行）を持ちます
• 内部状態はフレーム間で保持されます
• 複雑なロジックのためにサブパッチを含めることができます

チャンネル — リアクティブなデータフロー

チャンネルは双方向のデータバインディングを提供します：

• IChannel<T> — 監視可能な値のコンテナ
• .Value — 現在の値を読み書きします
• チャンネルはセッションをまたいで状態を保持します
• 明示的なリンクなしでリアクティブな更新を行うために、ノード間でチャンネルを接続します

イベント処理

• Bang — 1 フレームの true パルス（トリガー）
• Toggle — true と false を交互に切り替えます
• FrameDelay — 値を 1 フレーム遅延させます（循環依存を断ち切ります）
• Changed ノードを使用して、フレーム間で値が変化した時点を検出します

時間ベースのアニメーションを繰り返すには、ネイティブの LFO、GetSlice、CosineWave の配線を使用します。アニメーションパターンを参照してください。

パッチの構成

命名規則

• パッチ名とノード名には PascalCase を使用します
• 関連する操作を共通のカテゴリにまとめます
• 操作内容を示す説明的な名前（動詞 + 名詞）を使用します
• カスタムの Process およびノード登録名にはスペースを含めません。実際の 標準/インポートされた名前、ピンラベル、文章はそのまま保持し、定義と呼び出しを同期させます。

構造

• パッチは焦点を絞ります — 1 つのパッチにつき 1 つの目的
• 再利用可能なロジックはサブパッチに切り出します
• パラメーターを公開するには IOBox ノードを使用します
• パッチ境界に入出力ピンを作成するには Pad ノードを追加します

ローカルアクセスと人間が読めるグループ

共有されるセットアップと共通のシンク/レンダリングの背骨は、技術固有のビジュアルフレームの外に置いてください。レンダラーの Group がネストされた Group を受け入れる場合、ショーケースではデモンストレーション用のピアを 1 つの Group にまとめ、それをレンダラー付近の 2 つ目の Group 内で基本的なシーンコンテンツと組み合わせることができます。これは任意の可読性のための慣例です。Group がサポートする入力タイプとトラバーサル動作を確認してください。

各デモンストレーションのコントロール、機能ノード、結果は一緒に保ってください。共有入力の読み取りは、ヘルパー内も含め、その利用者のそばに置いてください。複数のキャンバス配置が、追加の入力を加えることなく同じシグネチャパラメータを参照することがあります。名前付き Slot は共有状態へのローカルアクセスを提供できますが、それらは見えない配線ではありません。初期化、読み書きの順序、null の扱い、リソースのライフタイムを確認してください。参照値の Slot は、それだけでフレーム遅延が安全になるわけではありません。

同一の配線処理は小さな Process ヘルパーに抽出するか、インスタンスが本当に 1 つのトポロジーを共有している場合はループを使用してください。ステートフルな呼び出しには、呼び出しまたは反復ごとの永続的な状態が必要です。1 つの可変レンダラーを繰り返し更新して、その出力のエイリアスを収集しないでください。本当に異なる技術は明示的に保ってください。

人間が作成した位置、幅、コメントを保持してください。新しい要素はローカルに配置してください。スペースが必要な場合は、パッチ全体をリフローするのではなく、既存のまとまったグループをそのまま平行移動してください。ヘルパーキャンバスはルートとは独立にレビューしてください。意図的な人間の編集から学んでください。コントロールは宛先ピン順に並べ、高さをずらし、共有値は最も早い利用者の上に置き、明確なヘルパーレーンを残してください。相対的なジオメトリは、値をコピーしたり模範例を乱したりすることなく、明示的に対象とされたセマンティックなピアに転送してください。ジオメトリとトポロジーは、エディタ保存時のメタデータとは別に比較してください。テキスト差分のサイズから意図を推測しないでください。 ユーザーがこの慣例を 1 つのドキュメント全体に適用するよう明示的に求めた場合は、ヘルパーや Application を含むすべての実行可能なキャンバスを棚卸ししてください。一致するロールに対してレイアウトを実装し、固有のサブグラフは意図的に適応させ、各キャンバスを独立に監査してください。diff の調査やスキルの更新は、その実装ではありません。模範例、すでに正しい人間のグループ、その他のドキュメントを保持してください。非ジオメトリの XML が変更されていないことを証明し、2 回目の適用でずれが生じないことを検証してください。残存する共有ファンアウト/コレクションの交差は、ジオメトリ指標を改善するためだけにピンを並べ替えたりリンクを変更したりすることなく、正直に報告してください。

明示的に独立したレンダラーピアのコレクションでは、source-X の順序がその Group での交差を減らすことがあります。子を順番にトラバースする実装では、コレクションスロットが実行順序も決定します。producer-before-consumer の GPU ステージを保持し、すべての Group をグローバルにソートしないでください。これが機能を明確にする場合は、ヒーロー/デモのレンダラーとユーティリティジオメトリを視覚的に区別してください。各デモのコントロールとローカルヘルパー入力を近くに保ってください。 ローカル配置と Slot の背後にある XML 契約については、local access を参照してください。

よくあるアンチパターン

1. 循環依存 — FrameDelay を使って循環を断ち切ってください
2. 1 つのパッチにノードが多すぎる — サブパッチを抽出してください
3. リアクティブではなくポーリング — リアクティブな更新には Channels を使用してください
4. Nil の無視 — null/空のコレクション入力は常に適切に処理してください

よくあるパターンのリファレンスについては、patterns.md を参照してください。

このナレッジを育て続けましょう

次にパッチを当てる人の謎を1つ減らしましょう。このコレクション内のスキルを初めて使用する際、7日以内に成功したチェックがない場合は、ソースを tebjan/vvvv-skills と比較してください。記録が存在しない場合は、一度だけチェックしてください。 これらのスキル全体で、ローカルのチェックのタイムスタンプ/リビジョンを1つ共有してください。呼び出しごとにポーリングしないでください。 ローカルの拡張機能と固定されたプロジェクトバージョンは保持してください。チェックすることは、更新をインストールする許可ではありません。オフラインの場合は、延期されたチェックを記録し、タスクを続行してください。

実際の作業でギャップが明らかになった場合は、テスト済みの vvvv/パッケージのバージョン、最小限の再現または信頼できる情報源、および観察された結果を記録してください。他のユーザーの報告は、検証されるまでは事実ではなく手がかりとして扱ってください。最も小さく関連する指示を改善してください。1つの例を普遍的なルールにしないでください。プライベートデータを編集で除去し、アップストリームに提出する前に公開の許可を取得してください。 コントリビューションポリシーをご覧ください。 マージされた改善は、ローカルの編集や全員のスキルの自動上書きではなく、ユーザーのインストーラー/アップデートワークフローを通じてユーザーに届きます。