vvvv-fundamentals

vvvv gamma の基礎

vvvv gamma とは

vvvv gamma は .NET 8 向けのビジュアルプログラミング環境です。ノードベースのパッチングと C# コード生成を組み合わせ、Stride（3D エンジン）と .NET API をターゲットとしています。プログラムは、ビジュアルエディターでノードをリンクで接続することによって構築します。

vvvv はライブプログラミング環境です。プログラムは、あなたが構築している間も継続的に実行されます。ビジュアルパッチの編集と C# コードの変更はどちらも、再起動することなく即座に反映されます。vvvv は C# ソースファイルを Roslyn を介して自身でコンパイルし、保存のたびにインメモリのアセンブリに変換します。

ドキュメントの構造

• .vl ファイル — vvvv gamma のドキュメント（XML ベース、バージョン管理可能）
• 各ドキュメントには パッチ（ビジュアルプログラム）と 定義（型、オペレーション）が含まれます
• ドキュメントは NuGet パッケージや他の .vl ファイルを参照できます
• パッチエクスプローラーには、ドキュメントの型階層が表示されます

実行モデル

• フレームベースの評価 — メインループが毎フレーム、グラフ全体を評価します（約 60 FPS）
• 評価順序を決めるのはグラフの依存関係 — キャンバス上の座標ではありません
• サブグラフ内のビジュアルデータフローは上から下へ — ソースがコンシューマーの上にあります
• 兄弟サブグラフは左から右へ、2 次元キャンバス上で互いに並んで読み取られます
• プロセスノードはフレーム間で状態を保持します（コンストラクター → Update ループ → Dispose）
• オペレーションノードは毎フレーム評価される純粋関数です
• vvvv は接続されているすべてのノードを評価し、接続されていないサブグラフはスキップします

ライブコンパイルモデル

vvvv は、あなたが編集している間もプログラムを継続的に実行します。パッチとシェーダーには、編集・コンパイル・実行のサイクルはありません。C# の場合、ライブリロードはコードの参照方法によって異なります。

パッチの変更

• ビジュアルパッチへの編集は即座に反映されます
• ノードの状態（インスタンスフィールド）は編集をまたいで保持されます
• 新しいノードとリンクは次のフレームで有効になります

シェーダーの変更

• .sdsl シェーダーファイルは、保存すると常にライブリロードされます
• vvvv はバックグラウンドでシェーダーを再コンパイルし、実行中のプログラムに差し替えます

C# — 2 つのワークフロー

C# コードは、ソースプロジェクト参照またはプリコンパイル済みバイナリを介して統合できます。どちらを選ぶかは、プロジェクトの規模と開発フェーズによって異なります。

ソースプロジェクト参照（ライブリロード）:

.vl ドキュメントが .csproj ソースプロジェクトを参照している場合、vvvv は .cs ファイルを Roslyn を介して自身でコンパイルし、インメモリのアセンブリに変換します。dotnet build や外部ツールチェーンは関与しません。

• .cs ファイルを保存すると、vvvv が変更を検出し、バックグラウンドで再コンパイルします
• ステータスインジケーター: グレー = シンボルをビルド中、オレンジ = C# を出力中
• コンパイルが成功すると、影響を受けるノードはライフサイクルを再開します:
  1. 古いインスタンスで Dispose() が呼び出されます
  2. 新しいコンストラクターが実行されます（新しい NodeContext を使用）
  3. Update() が次のフレームで再開されます
• 静的フィールドはリロード時にリセットされます — インメモリのアセンブリ全体が置き換えられるためです
• コンパイルエラーが発生した場合、プログラムは最後に有効だったコードで実行を続けます

バイナリ参照（ライブリロードなし）:

.vl ドキュメントがプリコンパイル済みの DLL または NuGet パッケージを参照している場合、そのアセンブリは起動時に一度だけ読み込まれます。変更を反映するには、DLL を外部で再ビルドし（例: dotnet build）、vvvv を再起動する必要があります。このワークフローは、ライブリロードが不要な大規模プロジェクトや安定したライブラリで一般的です。

ノードのカテゴリ

プロセスノード

• Create（コンストラクター）、Update（毎フレーム）、Dispose のライフサイクルを持ちます
• [ProcessNode] 属性を付けて C# で記述します
• フレーム間で内部状態を保持します
• 変更検出を使用して無駄な処理を避けます

オペレーションノード

• 純粋関数: 同じ入力は常に同じ出力を生成します
• 静的 C# メソッドとして記述します（vvvv が自動的に検出します）
• フレーム間で状態を持ちません
• [ProcessNode] 属性は不要です

アダプティブノード

• 接続された入力の型に基づいて実装を適応させるノードです
• 例: + は int、float、Vector3、string などで動作します
• 実行時ではなく、リンク時に解決されます

ピン、パッド、リンク

• ピン — ノードおよびリージョン上の入力と出力
• パッド — オペレーションパッチ内でプロパティを読み書きするためのビジュアルノード。同じ名前を持つすべてのパッドは同じプロパティを参照します
• リンク — データフローと実行順序を定義する、ピン間の接続
• スプレッディング — Spread<T> が単一値の入力に接続されると、ノードが自動的にイテレーションします

パッチと C# の記述、どちらを使うべきか

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

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

• IChannel<T> — 監視可能な値のコンテナー
• IChannel<T>.Value — 現在の値の読み書き
• Channel.IsValid() — 接続されているかどうかの確認
• チャンネルはセッションをまたいで状態を保持します
• UI とパッチ間の双方向データバインディングを可能にします

C# のチャンネル統合パターン（IChannelHub、PublicChannelHelper、[CanBePublished]）については、vvvv-channels を参照してください。

主要なデータ型

型	C# の相当型	用途
Spread<T>	ImmutableArray<T>	vvvv のイミュータブルコレクション
SpreadBuilder<T>	ImmutableArray<T>.Builder	スプレッドを効率的に構築
Float32、Int32 など	float、int	プリミティブ
Vector2/3/4	Stride.Core.Mathematics	空間演算
Color4	Stride.Core.Mathematics	RGBA カラー

ファイルの種類

拡張子	目的
.vl	vvvv gamma ドキュメント（XML ベース）
.sdsl	Stride シェーダーファイル（SDSL 言語）
.cs	カスタムノード用の C# ソースファイル
.csproj	.NET プロジェクトファイル
.nuspec	NuGet パッケージ仕様

エコシステムの概要

vvvv の機能は、.vl ドキュメント、C# ノード、シェーダーをバンドルした NuGet パッケージを通じて拡張されます。

領域	主要なパッケージ
3D レンダリング	VL.Stride（Stride エンジン）、VL.Fuse（GPU ビジュアルプログラミング）
2D レンダリング	VL.Skia、ImGui、Avalonia、CEF/HTML
ハードウェア I/O	DMX/Art-Net、ILDA レーザー、デプスカメラ（Azure Kinect、ZED）、ロボティクス（KUKA、Spot）、Ultraleap、LiDAR
ネットワーキング	OSC、MIDI、MQTT、Redis、WebSocket、HTTP、TCP/UDP、ZeroMQ、Modbus、Ableton Link
コンピュータビジョン	OpenCV、MediaPipe、YOLO（v8～v11）、ONNX Runtime
オーディオ	NAudio、VST ホスティング、SuperCollider ブリッジ
汎用 .NET	.csproj 参照経由で 100,000 以上ある標準 NuGet パッケージのいずれか

パッケージを追加するには、.vl ドキュメントの Dependencies で参照するか、.csproj に <PackageReference> を追加します。.csproj の詳細については、vvvv-dotnet を参照してください。

AppHost とランタイムの検出

// Detect if running as exported .exe vs editor
bool isExported = nodeContext.AppHost.IsExported;

// Register per-app singleton services
nodeContext.AppHost.Services.RegisterService(myService);

詳細なリファレンスについては、reference.md を参照してください。

このナレッジを育て続ける

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

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