ZgeViz用エフェクト開発の手引き

「ZgeViz: effect development documentation(original Postby VilleK » Fri Jul 02, 2010 11:22 am)」

の翻訳。関連して「undocumented stuff」というドキュメントもあるようですがまだあんまり見ていません。
ShaderToyからの移植については「ZgeViz用エフェクト開発の手引き/Shadertoy」も参照。

---

ZgeViz用エフェクト開発の手引き

ZgeViz用のエフェクトを開発する第一歩は最新版の「ZGameEditor開発環境」をダウンロードすることです。

「ZGameEditor」開発環境にまだ慣れていないなら、「Kjellsのビデオチュートリアル」と「ドキュメント」に目を通しておくことを強くお勧めします。

(訳注：ビデオはImage-lineのZgeVizのマニュアルにあるビデオリストと同じもののようです。ドキュメントの方はReferenceまで入れるとボリュームがとんでもないので「目を通しておく」レベルの段階では「General Info」と「Getting started」の最初のチュートリアルあたりまでで良いと思います)
(くどい訳注：ビデオもドキュメントも、「開発環境」という概念自体になじみがない人だと、端的に言って「かなりヘビー」です。なだらかな道を探すなら、思いっきり遠回りですが「Unityみたいな日本語情報が充実した開発環境」のチュートリアルプロジェクトから挑戦して何週間後かにここに戻ってきてビデオを見直す、ぐらいの覚悟をした方がよいかも知れません。Unityのチュートリアルプロジェクトを完了してたらZgeVizのチュートリアルビデオは充分理解できるはずです)

プロジェクトのテンプレート

ZGameEditorで新規プロジェクトを作成したら、プロジェクトツリーに以下のコードをコピー＆ペーストしてください。

ZZDC<?xml version="1.0" encoding="iso-8859-1" ?>
<Group>
  <Children>
    <DefineArray Name="SpecBandArray" SizeDim1="32"/>
    <DefineArray Name="AudioArray" SizeDim1="32"/>
    <DefineVariable Name="SongPositionInBeats"/>
    <DefineArray Name="Parameters" SizeDim1="32"/>
    <DefineConstant Name="ParamHelpConst" Type="2"/>
  </Children>
</Group>

これらの要素が定義されていると、FL Studio上のZgeVizが、FL Studioから流れてくるデータを受け取ることができるようになります。

(訳注：2018年現在では、この手順は必要ない＋この手順はあんまり簡単ではないです。さしあたって、「最新版のZGameEditor開発環境」であるZGameEditor4.0betaには「File > New Project > Visualizer FgBg Effect」とかいうコマンドがあるので、それを使えばこの手順と同等の(実際は同等以上に適切な)設定ができるようになっています)
(訳注：「伊達や酔狂や学習の為に、敢えてこの手順に近いことをやる」なら、「ZGame Editorのバージョン4.0beta以上」で、

• ZGE4.0を起動。
• メニューコマンド「File->New Project->(empty project)」で、何も定義されていないプロジェクトを新規作成。
• 「Project tree」の「Content」をクリックして選択。
• Project treeの右に現れるコンポーネントリストで、「Group」をクリックして、Project treeに「Groupコンポーネント」を追加。
• メニューコマンド「Edit->Edit Project as XML」でプロジェクトソースコードを表示。
• ソースコード中、「<Group/>」とだけ書かれた行があるはずなので、その行を、
• 上記ソースコードの「<Group>」から「</Group>」の部分に書き換える(クセのあるエディタですが「Windowsのテキストペースト操作のCtrl-V」とかはフツウに使えます)。レイアウトとかインデントとか余分な空白とかは保存時に勝手にどうにかなるので、原則気にしなくていい。
• ソースコードダイアログの「OKボタン」をクリックして、プロジェクトソースコードを更新。
• で、「Project tree」のContent->Group->Children以下に「何か５つぐらい」追加されているのを確認する。

という感じになるかと思います。
「ZGEのチュートリアルを乗り越え、よくぞここまで辿り着いた勇者」であれば、もしかしたらコードを見れば想像がつくかもしれませんが、この手順でやってるのは「ZGEで開発したものを、FL Studio上で動かす時に使う変数、を、宣言している」だけです。これ以外の「ZGEで開発する」部分、つまり「画面にアレコレする要素」は一切触れていません。それは「ZGEのチュートリアル」で学習する話かなと思います)

ZgeViz用プロジェクトで使用される変数

変数(及び定数)の意味は以下のとおりです。
（訳注：一部の変数の情報について、2018/05/21に「https://forum.image-line.com/viewtopic.php?f=1700&t=83695」の「Explanation of FL Studio variables 」あたりから追記。重複、冗長性は未チェック）

(訳注：ここに並んでいるのは「FL Studioとやりとりされるデータ」、言い換えれば「FL Studio(ZGEViz)側が特別扱いする特殊な変数名」と思われます。ParametersとParamHelpConstの２つは「エフェクト画面上のスライダの有無」に直結するので「ほぼ」必須と考えてよさそうですが、FL Studio添付の.zgeprojファイルを見てもほかの変数はあったりなかったりするようです)

(訳注：「File > New Project > Visualizer FgBg Effect」で生成したプロジェクトにはほかにも「いろいろ定義されていたり」、「使い方のヒントが書かれていたり」、「フォーラムに情報があったり」したような気もしますが、まだあまり読んでないので知りません)

(訳注：これらの変数は、慣習的に「App.Content以下に作られたどれかのGroup」、図で書けば…

App:ZApplication
+OnLoaded
+Status
+OnUpdate
+OnBeginRenderPass
+OnRender
+OnClose
+Lights
+Content
 +Group  <--このへん！

に置かれる(あるいはユーザが自分で置く)ようです。Group名はまちまちで「FL_Studio_Varialbes」だったり「values and such(ZGE4.0bのテンプレートの場合)」だったりするようです。この記事中の上に挙げたコード例ではGroupは「無名」です。Groupの下に置くことも必須ではなく、Content直下に置かれている場合もあります。ちなみに「言語的にGroup名が識別子として使われることはない(参考： http://www.zgameeditor.org/index.php/ComponentRef/Group )」ようで、上記の変数はいわゆるメンバ変数とか何とかスコープの変数とかじゃなくグローバル変数扱いと考えてよさそうです。いわゆる「ZGameEditorのツリー上のコンポーネント」じゃなく「ツリー上のZExpression上の変数」として書かれている場合もあったような気がしたんですが気のせいかだったかは未確認)

(訳注：「IMAGE SRCとかMESHとかで与えられるリソースをどうやって.zgeprojファイル中の変数に割り当てているのか」はまだよくわかってないんですが、観察した限り「かなりいい加減な書き方をしても自動割り当てが起こってる」ようなので、「MeshコンポーネントかBitmapコンポーネントがあったら片っ端から割り当てる」、「ソース中のコンポーネントの型と登場順しか見てない」という仕組みなのかも知れません。Bitmapコンポーネントに関しては、「undocumented stuff(というドキュメント)」の「NoCustom Bitmap Component Comment」節によると「Commentプロパティ」に「NoCustom」と書いておくと上書きされない(＝しなければ自動で上書きされる)仕組みらしいです)

訳注：開発

実際の開発の部分についてはこのドキュメントでは扱っていません。
ZGameEditorのチュートリアルで実際に「一通り手を動かしてみた」あとであれば、

• FL Studio添付の.zgeprojファイルがどこにあるか探す
• 既存エフェクトを「Zgeに読み込む」
• 既存エフェクトを「Zgeで実行する」
• 既存エフェクトが持ってたスライダの値を、ZExpressionを使って手で書いてみる
• 既存エフェクトのプロジェクトをがんばって読解する
• 既存エフェクトのプロジェクトを改造する

というあたりまでは多分(考えれば)できるようになってるはずなので、そこから手を付けるのが良いと思います。

余談１）
ZGEVizの画面でエフェクト名ドロップリストのところを右クリックすると「Edit Effect in ZGameEditor」というコマンドがあっていきなり開発環境が開けたりします。標準状態だとたぶんエラーが出るので、その場合はエラーメッセージの(大雑把な)指示に従って、

• ZGameEditorをインストールして
• ZGameEditorを起動して「Tools > Settings...コマンド」実行して
• 「Settingsダイアログ」で「File assosiation/Associate .zgeproj file extension with explorerトグル」をオン

する必要があります。ただ、この方法は「FL Studioのプラグインのプリセットを直接書き換える(のに近い)」ことをやってるので、結構危険です。いじりたいzgeprojの「バックアップを取っておく」とか「コピーしてコピーの方をいじる」とか、何がしかの対策をした方がよいです（操作と集中力に絶対の自信がないなら、そもそも「Edit Effect in ZGameEditor」コマンドは使わない方が安全、とか個人的には思います）。

余談２）
ちなみにScenesカテゴリあたりの「超かっこいいエフェクト群」は往々にして「GLSL」の技術を使っているんですが、それは一朝一夕に手を付けられるものでもないです。Web上で「WebGLのチュートリアル」とか「Shadertoyで遊ぶチュートリアル」とかを探せば手を付けられる(あるいは時間がかかりそうと理解できる)ようになるんじゃないかと思います。
逆に（？）、2018年05現在の世界では「GLSL入門できる環境(しかも無料で日本語の情報もそこそこ)」が「あちこちで実用レベルで提供されつつある」ようなので、「ZGEさっぱりわからない」けど「GLSLコーディングはわかる人」というのも一定数いるかと思います。そういう人向けの「専用のショートカット」もあります。いずれにせよZGEについて一定量の勉強は必要ですが「GLSLが書けて、何を書いたか意味がわかってる人」なら、ZGEVizエフェクト化は難しくないと思います。私はよく知りませんが。

完成したエフェクトの配布

エフェクトの定義が完了して.zgeprojファイルが完成したら、FL Studioのプラグインディレクトリにある「ZgeViz\Foreground\」ディレクトリにコピーします。便宜上Foreground、Backgroundという２つのフォルダがありますが、ZgeVizは両方のフォルダのエフェクトを対等に扱って両方からロードします。.zgeprojファイルを更新した場合、ZgeVizの「Reload」ボタンを押せばエフェクトがリロードされます。
「Clear」というフォルダに配置されたエフェクトは、他の２つのフォルダのエフェクトよりも先にロードされます。「フィードバック」型のエフェクトを開発する場合にはこれを選ぶと良いでしょう。
(訳注：フォルダがFgAndBgにまとめられていたりその下にカテゴリが作られてたり、ロード順が単純に画面上で「左から右へ」になっていたりと、細かい仕様はZgeViz2で変わってるようですが、このへんは「見ればわかる」、「やってみればわかる」と思います)

エフェクトでのMIDIの扱い

MIDIについては「MIDI-input」スレッドを参照。
（訳注：この話題は基本的に「演奏データ」の話なので、それとは「全然関係ない」のですが、「Fruity DanceのMIDIデータをFruityDanceLineエフェクトの制御に使いたい」とか、「TextTrueTypeエフェクトの行指定で、C4を押したら一行目が表示されるようにしたい」とかいった要件では、「Fruity Keyboard Controller」プラグインをロードしておいて、ZGEVizのスライダからオートメーションクリップを作るときにそこへリンクする、という使い方が現実的かなと思います。要はFL Studioの既存機能を使えば「MIDIでZGEVizを制御することはできる」ので、この説で話題にしている機能を使ってわざわざエフェクトを作り直さなくてもいい、場合が多い、はず、という話です）

エフェクトでのVideo texturesの扱い

エフェクトで「VideoTextureBitmap」という名前の「bitmapコンポーネント」を定義してある場合、そこには「選択中のビデオ、またはWebCamの入力」が入ります。ZgeVizとともに配布されているエフェクトの中で「Video...」で始まる名前のものはこれを利用しているので、参考にしてください。
(訳注：ZgeViz1でVideo...だったエフェクトはZgeViz2で軒並みImage...と名称変更されてたような気もします。未確認ですが。あと、上でも書いたように「プロジェクト中にBitmapコンポーネントが定義されていると画像でも何でも機械的自動的に割り当てられる」ように見えるので、もしかしたら仕様が変わっているとかこの変数はこの変数で特別扱いがあったりする可能性も？)

エフェクトでのUserTextArrayの扱い

エフェクトで「UserTextArray」という名前の「DefineArrayコンポーネント」が定義してある場合、ZgeVizの「custom content」画面(多分ZgeViz2では「Add Content > Text」画面に相当する)でユーザーが入力したテキストを利用することができます。

エフェクトでのEffect helpの定義

エフェクトで「ZApplicationコンポーネント」の「commentプロパティ」に書かれたテキストは、ZgeVizでエフェクトのヘルプ画面として表示されます。ZgeVizでヘルプを表示するには、ZgeViz画面上で右クリックメニューから「Show help for this effect」コマンドを実行します(訳注：ZgeViz2の場合、ヘルプが定義されているエフェクトではエフェクト画面上部に「？」ボタンが現れるのでこれも使用できます。FL12.4時点では「ヘルプが未定義」のエフェクトが多かったりもします)。

関連項目

【ZGameEditorビジュアライザの資料】