Visual Module

Visual Moduleは、複数のエフェクトをノードでつなぎ、一まとまりの画像処理として使うための仕組みです。「素材を読み込む → 色を変える → 変形する」のような処理を組み、LIVEで動かしたり、タイムラインのレイヤーとして使ったりできます。

外から操作するパラメータも用意できます。内部の構成を毎回開かずに、加工の強さや色だけを配置先から変える、といった使い方に向いています。

ノードと接続

ノードは、一つの処理や入出力を表します。エフェクトノードの出力を別のノードの入力へつなぐと、前の処理結果を次の処理に渡せます。

In（外部からの入力）→ エフェクト → エフェクト → Out（外部への出力）

入力なしで画像を生成する構成なら、Inを使わず、生成するノードから始められます。一つの出力を複数の入力へ分岐させたり、複数の入力を持つエフェクトへ別々の結果を渡したりもできます。

Nodes タブの Add Effect Node... からエフェクトを追加します。各ノードには、値を受け取るパラメータと、処理結果を渡す出力があります。ノード下部の出力行には、出力名・型・右端の出力ポートが表示されます。複数の出力を持つエフェクトでは、使いたい出力を選んで接続します。

ドラッグで配線する

1. 接続先のノードを展開し、入力したいパラメータを表示します。ノードを無効にしている場合は、有効に戻します。
2. 接続元の出力ポート、または出力名がある行を押したままドラッグします。
3. 接続先の入力ポート、またはパラメータ行へ動かします。ドロップ候補の行が強調表示されます。
4. 指を離す、またはマウスボタンを離すと接続され、配線が表示されます。

入力ポートの小さな円だけを狙う必要はなく、パラメータ行全体にドロップできます。固定値を設定していたパラメータでも、接続できる型なら、ドロップによって入力方式がNodeへ切り替わります。

Inノードの出力からエフェクトへ渡す場合も、同じ手順です。最後の結果は、エフェクトの出力からOutノードの該当する入力行へドラッグして接続します。

ドラッグを取り消すにはEscapeを押すか、接続先ではない場所で離します。接続は同じVisual Moduleエディター内で行い、別のエディターに表示されているノードへは配線できません。

リストから接続する

ドラッグの代わりに、接続元をリストから指定することもできます。

1. 接続先のパラメータのラベルをクリックします。
2. Input source → Node を選びます。
3. 表示される選択欄から、接続元のノードと出力を選びます。

選択肢にはノード名・識別用のID・出力名が表示されます。同じエフェクトを複数使う場合は、ノードの歯車ボタンから Settings → Name で名前を付けると区別しやすくなります。Outノードでも、各入力行の選択欄から接続元を指定できます。

差し替え・分岐・切断

一つの入力に接続できる出力は一つです。接続済みの入力へ別の出力をドラッグするか、選択欄を変更すると、接続元を差し替えます。エフェクトノードの入力では、差し替え前のFit・Wrap・Filterの設定を保持します。

一つの出力を複数の入力へ渡す場合は、同じ出力からそれぞれへ配線します。分岐先ごとに別の読み取り設定を使えます。複数の画像を一つに混ぜたい場合は、複数入力を扱うエフェクトに渡して合成します。同じ入力へ何本もつなぐ操作では混ざりません。

エフェクトノードの接続を切るには、入力ポート、または接続先選択欄の横の … を押し、Disconnect を選びます。切断後はNode入力の未接続状態になるので、スライダーなどで固定値を設定したい場合は、ラベルのメニューから Literal に切り替えます。Outの接続を切る場合は、選択欄で なし（None） を選びます。

ノードの並びと処理の順序

ノードの見出しをドラッグすると、表示上の並びを整理できます。処理の依存関係を決めるのは配線です。ノードの上下を入れ替える操作と、入力の接続元を変える操作は別なので、順序を変えて加工したい場合は配線を確認します。

自分自身への接続はできません。また、AからBへ、BからAへ戻すような循環した構成は描画時にエラーになります。入力から最終出力へ、循環しない流れを作ってください。

画像以外のデータ

出力には画像・色だけでなく、数値やベクトルもあります。

型	主な用途
Color	画像や、赤・緑・青・アルファを持つ色
Scalar	一つの数値、または位置ごとに数値が変わるスカラー場
Vector	2成分の値、または位置ごとに向きや量が変わるベクトル場
Any	接続するデータの型を限定しない入出力

例えば、位置ごとに値が違うScalar出力を加工の強さに使えば、画面内の場所によって強さを変えられます。Vector出力は変形方向などの制御に使えます。これらのデータは、最終映像に直接表示する必要はありません。

ポートや配線の色は型を見分ける手掛かりになります。基本は同じ型同士をつなぎ、Anyは異なる型の入出力にも接続できます。型安全の設定が有効な場合は型が合わない接続が禁止され、無効な場合は警告付きで接続できます。警告が出た場合は、接続元の出力と受け取り側の用途を確認してください。パラメータの記事でも型と入力方式の違いを説明しています。

入力ごとに読み取り方を設定する

エフェクトノードの入力は、接続元の画像をどのように読み取るかを個別に設定できます。この設定を**サンプリング（Sampling）**と呼びます。

接続済みの入力ポート、または接続先選択欄の横の … をクリックすると、Samplingの項目が表示されます。

設定	決めること	新しい接続の初期値
Fit Mode	入力と出力で縦横比が違うときの収め方	Cover
Wrap Mode	入力画像の範囲外を読むときの扱い	Repeat (Mirrored)
Filter Mode	画素と画素の間を読むときの補間方法	Linear

これらは受け取る側の各入力の設定です。同じ画像出力を二つの入力へ分岐して、一方をContain、もう一方をCoverにできます。一方の設定を変えても、接続元の画像やほかの接続先は変わりません。複数入力を持つノードや、配列・構造体の内部にある接続可能な項目でも、それぞれ設定します。

Fit Mode：縦横比を合わせる

Fit Modeは、入力画像と、受け取るエフェクトの出力サイズの縦横比をどう合わせるかを決めます。

選択肢	動作	向いている用途
Stretch（stretch）	縦と横を別々に伸縮して出力領域に合わせる。入力と出力の縦横比が違うと図形や人物も伸び縮みする	画像やデータを出力領域いっぱいに引き伸ばす
Cover（cover）	縦横比を保ったまま出力領域を埋める。はみ出す部分は通常の画面範囲から外れる	背景など、画面を埋めたい画像
Contain（contain）	縦横比を保ったまま入力画像の全体を出力領域に収める。縦横比が違うと余白ができる	ロゴや写真の全体を見せる

例えば16:9の横長画像を1:1の正方形へ渡すと、Stretchでは円が縦長になり、Coverでは左右が画面からはみ出し、Containでは上下に余白ができます。

この図は、エフェクト固有の変形を加えずに入力を読む場合の模式図です。市松模様は透明部分を表し、Containの例ではWrap ModeをTransparentにしています。

Containだけでは余白は透明にならない

Fit Modeは画像を読む位置の対応を決めます。画像の外側に当たる余白を何で埋めるかはWrap Modeの設定に従います。画像全体を収め、余白を透明にしたい場合は、ContainとTransparentを組み合わせます。 初期値のRepeat (Mirrored)のままなら、余白にも反転した画像が現れます。

Wrap Mode：画像の外側を読む

変形などで画像の外側を参照したときや、Containによって余白ができたときに使う設定です。

選択肢	範囲外の扱い	見た目・使いどころ
Clamp（clamp）	最も近い端の画素を使い続ける	画像の端の色を外側へ引き延ばす
Repeat（repeat）	同じ向きの画像を繰り返す	模様をタイル状に並べる。左右・上下の端の色が違うと継ぎ目が見える
Repeat (Mirrored)（repeatMirrored）	隣り合う画像を交互に反転して繰り返す	端で折り返すようにつながる。文字や図柄も反転する
Transparent（transparent）	画像の外側を透明にする	余白を残して重ねる、画像の外側に模様を出さない

Wrapは、画像の外側を読む場合に違いが現れます。画像の範囲内だけを読む構成では、切り替えても結果が変わらないことがあります。

ここでのTransparentは入力画像の外側を透明として読む設定です。後段のエフェクトがその透明部分に色を描くことはあるため、Visual Moduleの最終出力が必ず透明になるわけではありません。ScalarやVectorのデータ画像では、範囲外の値が0になります。

Filter Mode：画素間を補間する

画像を拡大縮小・回転・移動すると、入力画像の画素のちょうど中間を読むことがあります。Filter Modeは、そのときの値の求め方を決めます。

選択肢	動作	向いている用途
Linear（linear）	周囲の画素を混ぜて、中間の色や値を求める	写真、滑らかな拡大縮小、連続したスカラー場・ベクトル場
Nearest（nearest）	最も近い画素の色や値をそのまま使う	ピクセルアート、画素の区切りやデータの段差を残したい場合

例えば小さなピクセルアートを拡大すると、Linearでは境界が滑らかになり、Nearestでは一つ一つの画素がブロック状に見えます。Nearestにしても、前段ですでに補間してぼけた画像が元の画素へ戻るわけではありません。

ScalarやVectorの入力でも、Linearでは隣り合う値が補間され、Nearestでは画素ごとに値が切り替わります。補間方法は色だけでなく、それを使う変形や強さの分布にも影響します。

TransparentとLinearの組み合わせでは、画像の端でも透明な外側との補間が行われます。Nearestでは、範囲外へ出たところで透明に切り替わります。

設定を組み合わせる例

目的	Fit Mode	Wrap Mode	Filter Mode
写真で画面を埋め、画像の外側には端の色を延ばす	Cover	Clamp	Linear
ロゴ全体を表示して周囲を透明にする	Contain	Transparent	Linear
ピクセルアート全体を収め、画素の境界を残す	Contain	Transparent	Nearest
変形で範囲外を読んだときにも模様を繰り返す	Stretch	Repeat	Linear

ピクセルアートを歪ませずに拡大するには、Filterだけでなく縦横比や拡大率も合わせます。整数倍の拡大では、画素の大きさをそろえやすくなります。

ノード出力が画像ではなく、空間全体で同じ値を表す定数の場合、どの位置を読んでも同じ値です。この場合はFit・Wrap・Filterを変更しても結果は変わりません。

解像度やレイヤー合成との違い

Fit Modeは画像の読み取り方を変える設定で、ノードの出力解像度そのものは変更しません。自動解像度が入力画像のサイズに追従していると、入力と出力の縦横比が同じになり、Fitの違いが見えない場合があります。比較したい場合は、受け取るノードの解像度をContext resolutionやCustom (Absolute)にして、異なる縦横比を指定します。

Outノードは内部の結果を外へ渡す出口です。上記のSamplingメニューは、エフェクトノードが入力を読むときに設定します。Visual Module全体をタイムラインの画面へどう収めるかは、配置先レイヤーのCompositing → Fitで設定します。

In・Outと主入出力

In は、外部から受け取るカスタムパラメータのうち、ノード接続を許可したものを出力ポートとして公開します。Out は、内部ノードの結果を外部へ渡します。

設定	役割
Input Defs	公開カスタムパラメータの型・初期値・表示方法を定義する
Primary input	タイムラインで、下層の合成映像を受け取る主画像入力を指定する
Primary audio input	タイムラインで、初期状態で下層音声を受け取る音声パラメータを指定する
Output Defs	外へ公開する出力を定義する
Primary output	LIVEやタイムラインで映像として使う主出力を指定する

主画像入力にできるのは、Color型で Allow node input を有効にしたパラメータです。主出力もColor型です。主画像入力・主音声入力・主出力は、それぞれ最大一つ指定します。

出力の定義を追加しただけでは、画像は流れません。NodesタブのOutで、その出力へ内部ノードを接続してください。何も表示されない場合は、Primary outputの指定とOutへの接続を確認します。

カスタムパラメータを公開する

Input Defs → Add Parameter から、外部に見せる操作項目を追加します。

項目	設定するもの
UI Label	画面上の表示名。例：加工の強さ
Reference Name	式から参照するときの名前。例：amount
Data Type	数値・色・ベクトル・文字列などの型
Control、Min/Max、Step	数値を編集するコントロールと操作範囲
Default Value	配置先で値を指定していないときに使う初期値
Allow node input	Inノードの出力として使うかどうか

通常の値として渡す

加工の強さのように一つの値を渡したいときは、Allow node inputを無効にします。内部のエフェクトの入力方式を Custom Parameter にして公開パラメータを選ぶか、式から参照します。

例えば、Reference Nameを amount とした数値パラメータは、内部の式で次のように使えます。

PARAM("amount") * 2

PARAM に渡すのはUI LabelではなくReference Nameです。この例では、外から渡した値の2倍を内部パラメータに使います。

Inノードから渡す

Allow node inputを有効にしたパラメータは、Inノードから配線して使います。PARAM やCustom Parameterによる直接参照の対象にはなりません。受け取るものが一様な色や数値であっても、この使い分けは同じです。

主画像入力を内部の加工ノードへつなぐと、タイムラインでは下層までの合成映像を加工できます。

音声を渡す

Audio型の公開パラメータは、内部ノードの Custom Parameter から受け取ります。Inへの画像配線やPARAM式では扱いません。Primary audio inputに指定すると、タイムライン配置時の初期入力が下層音声になります。

LIVEで確認する

Visual Moduleエディターの上部で対象を選び、LIVE を押すとリアルタイムの出力を確認できます。Preview Params では、公開パラメータに渡すプレビュー用の値を変更できます。

LIVEプレビューのヘッダーには、現在表示しているVisual Moduleの名前が表示されます。名前をクリックすると、Visual Module の一覧からLIVEの対象を切り替えられます。Scene の一覧から対象を選ぶと、タイムラインのプレビューに切り替わります。

画像はAssetsの素材を直接使い、LIVEの動画・音声・カメラなどはPlayerを通して利用します。Playerはメディアの再生状態を持つもので、タイムライン上の動画・音声クリップとは別です。

現在の作成UI

登録済みのVisual Moduleは上部のメニューから選択できますが、同メニューの New による新規作成は未実装です。新しいノード構成を作るには、タイムラインにインラインVisual Moduleレイヤーを追加できます。

名前を変更する

Visual Moduleエディターの Other → Name で表示名を変更できます。登録済みVisual Moduleでは上部の選択メニューにも反映され、インラインVisual Moduleではレイヤー名と共通です。変更はUndo/Redoで戻したり復元したりでき、.gsvmへの書き出しにも変更後の名前を使います。

エクスポート・インポート

Visual Moduleエディターの Other → Export Visual Module… から、編集中の構成を.gsvmファイルとして保存できます。登録済みVisual Moduleと、タイムラインのインラインVisual Moduleのどちらからも書き出せます。

ノード構成・配線・公開パラメータとその既定値・入出力・Automation Graph・内部のキーや式を保存します。参照している画像・動画・フォントなどのAsset原本と、Playerの定義も同梱するため、元の素材ファイルを別途コピーする必要はありません。無関係なAssetやPlayerは含めません。

LIVEのPreview Params、配置先レイヤーのパラメータ値・クリップ・合成設定は含めません。インラインVisual Moduleを書き出す場合、レイヤー名がファイル名と取り込み後の表示名になります。

取り込むには、ナビゲーションメニューの File → Import → Visual Module (.gsvm)、またはVisual Moduleエディター上部の選択メニューの Import Visual Module… を選び、.gsvmファイルを指定します。新しい登録済みVisual Moduleとして追加され、既存のVisual Moduleは上書きしません。素材・Playerも独立したコピーになり、取り込み全体を一回のUndo/Redoで戻したり復元したりできます。取り込んだVisual ModuleはLIVEや、タイムラインの参照方式で利用できます。

ファイル由来のPlayerは素材も一緒に復元します。カメラなどの外部入力は未指定で取り込み、再指定が必要なPlayer名を表示します。カメラを利用する場合は、Playersの該当Playerのメニューで Webcam を選んでください。マイク・ライブストリームを入力にするPlayerは現在未対応です。再生位置や再生中の状態は引き継ぎません。

AssetやPlayerのIDを式・環境変数などから動的に返す構成は、同梱する素材を特定できないためエクスポートできません。素材を直接選択するか、公開パラメータ経由で指定してください。数値などを計算する式は保存できます。対応していない形式や、より新しいバージョンのGlitch Studioで作成されたファイルは読み込めません。

タイムラインで使う

タイムラインへの配置には、次の2種類があります。

配置方法	定義の置き場所	向いている用途
Visual Module（インライン）	そのレイヤーの中	一か所だけで使う専用の処理
Visual Module（参照）	プロジェクト内の登録済みVisual Module	同じ構成を複数か所で使う処理

どちらも、主画像入力には下層の合成映像が渡り、主出力の画像にレイヤーの変形・不透明度・合成方法が適用されます。背景がなくても使える生成系の構成なら、主画像入力は不要です。

透明背景の素材を生成して重ねるときは通常合成を使います。下層を加工して背景込みの画像を返すときは、Compositing → Blend mode を置き換え（replace）にします。Visual Moduleレイヤーの初期値は通常合成なので、構成に合わせて設定してください。

公開パラメータはレイヤーの Module Parameters から設定します。配置側のキーや式はシーン時刻、内部ノードの TIME / TIME_MS はクリップの内容時刻で動きます。詳細は時間と参照範囲を参照してください。

ノードの解像度

ノードの歯車ボタンから Settings → Resolution を開き、出力する画像の基準サイズを指定できます。

選択肢	使うサイズ
Auto	素材や、エフェクトが解像度の基準に使う入力画像のサイズを優先する。それらがなければ描画先のサイズ
Context resolution	LIVEではプロジェクト、タイムラインでは所属シーンのサイズ
Custom (Absolute)	WidthとHeightに指定した幅と高さ

実際に描画するサイズには、プレビューや書き出しの解像度倍率も適用されます。処理状態を取得できている出力は、出力行で幅と高さを確認できます。

ノードごとに異なるサイズを使えます。例えば小さい解像度で作った模様を大きい解像度のノードに渡すと、その接続のFit・Wrap・Filterに従って読み取られます。拡大しても元にない細部が増えるわけではないので、見た目に応じて生成元の解像度も調整してください。

困ったときの確認点

状況	確認すること
ドラッグしても接続できない	出力側からドラッグしているか、接続先が展開・有効化されているか、ノード接続に対応するパラメータか、同じエディター内かを確認する
型の警告が出る	出力行と入力の型を確認する。画像を使う入力にScalarなど別の型を渡していないかを確認する
ノードを追加しても何も見えない	出力がOutまでつながっているか、Primary outputを指定しているか、入力素材があるかを確認する
Containなのに余白に画像が出る	Wrap Modeを確認する。透明な余白が必要ならTransparentにする
Fitを変えても見た目が変わらない	入力と受け取るノードの出力が同じ縦横比ではないか、定数入力ではないかを確認する
画像がぼける・画素が目立つ	入力側のFilter Modeと、生成元の出力解像度を確認する
描画エラーになる	ノードの警告アイコンから内容を確認し、循環した配線やパラメータの式を見直す

現在の制約

現在、Visual Moduleを別のVisual Moduleのノードとして入れ子にする使い方は未対応です。また、公開カスタムパラメータの配列・構造体・Any型を編集するUIには未対応の部分があります。

タイムラインではPlayerによるメディア入力を利用できません。動画・音声は専用のレイヤーで配置し、下層画像や音声入力を通して処理してください。過去の描画を蓄積するエフェクトでは、シークやクリップの切り替えによって結果が変わることがあります。