VST3ホストを作ろう（４） 〜VST3 SDK のドキュメントについて〜

[目次](https://qiita.com/hotwatermorning/items/5ab2a687a4cbc73a0f56)

## はじめに

　VST3 SDK には HTML 形式のドキュメントが付属しています。しかし、使い勝手が悪く構成も分かりにくいため、最初はドキュメントの読み方が分からずに混乱します。今回はそんなドキュメントの読み方について解説します。

## ドキュメントの場所について

　VST3 SDK のドキュメントは、SDK の中の `doc` ディレクトリに含まれています。 `doc` ディレクトリと同じ階層にある `index.html` ディレクトリがドキュメントのトップページになっているので、このファイルをダブルクリックで開くとブラウザ上でドキュメントを開いて参照できます。

　このドキュメントはオンラインでもホスティングされていて、以下の URL から参照できます。

* https://steinbergmedia.github.io/vst3_doc/

　ただし、 VST3 SDK に含まれる `index.html` を手元で開いたときと比べて、いくつかの画像データへのリンクが正しく設定されていなかったり、 VSTGUI ライブラリのドキュメントが見れなかったりする問題があります。

　また、筆者も非公式に VST3 SDK のドキュメントをホスティングしていて、以下の URL から参照できます。こちらの方は、公式のオンラインドキュメントでは見られなかった画像データやVSTGUI ライブラリのドキュメントもオンラインで見れるようになっています。

* https://vst3sdk-doc.diatonic.jp/

## ドキュメントの構造について

　VST3 SDK のドキュメントは左側にメニュー画面、右側にコンテンツ画面が存在する 2 ペインの構造になっています。左側のメニュー画面にあるメニュー項目をクリックすると、それに対応するコンテンツが右側のコンテンツ画面に表示されます。

![スクリーンショット 2019-09-15 1.58.31.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/944/e7003afb-83c0-16d4-40df-7d73322dcfe0.png)

　VST3 SDK のドキュメントの大部分は [Doxygen](http://www.doxygen.jp/) で作成されているため、ほとんどのメニューの項目をクリックしたときには、以下のように、右側のコンテンツ画面に Doxygen 形式のドキュメントが表示されます。

![スクリーンショット 2019-09-15 2.06.10.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/944/86926c36-64ad-c333-b755-44aef6b97c54.png)

## ドキュメントのメニュー項目について

　各メニュー項目がどのようなドキュメントを表しているかは、以下の表のとおりです。

|項目名|内容|
|-----|---|
|Introduction|VST3 SDK の導入部分となるドキュメント。VST3 の特徴やライセンスに関する記載があったり、他のメニュー項目へのリンクなどある|
|VST 3 API|VST3 規格のコンセプトや、ホスト／プラグインそれぞれに関する仕様や、インターフェースクラスのAPIなどの解説|
|-> Base Module|VST3 SDK で使われる基本ライブラリについての解説|
|-> VST-MA|VST3 SDK の設計のベース部分に使われている VST Module Architecture (VST-MA) についての解説|
|SDK Helper Classes|ホスト／プラグイン開発に使用できるヘルパークラスの解説|
|Plug-ins Examples|VST3 SDK に含まれるサンプルプラグインの解説|
|Test Applications|プラグインの動作を検証するためのテストアプリケーションの解説|
|VSTGUI 4|プラグイン開発用の GUI ライブラリ VSTGUI の解説|
|Package File Structure|VST3 SDK のファイル／ディレクトリ構造の解説|
|Version History|VST3 SDK のバージョン履歴|
|Licensing Issues|VST3 のライセンスに関する解説|
|FAQs|VST3 SDKに関するよくある質問と回答|
|Locations / Format|VST3 プラグインのファイル構造やインストールパス等に関する仕様の解説|
|Workflow Diagrams|ホスト-プラグイン間での関数呼び出し順の図解|
|Help > SDK Forum|Steinberg が提供している開発者向けフォーラムへのリンク|

　一つ注意点として、 VST3 SDK は Doxygen 形式のドキュメントを何種類か含んでいますが、それらがすべて個別に左側のメニュー項目に対応しているわけではありません。つまり、いくつかのメニュー項目は同じ Doxygen ドキュメントの別のページを指しているだけということがあります。

## ドキュメントの読み方（ホスト開発時）

　VST3 SDK のドキュメントは構成が分かりにくく、どのドキュメントを読めばいいか分からない状態になりやすいため、筆者がよく利用するドキュメントについて以下に解説します。

　ホスト開発時には、主に `VST 3 API` のドキュメントを参照します。このドキュメントには VST3 プラグインの基本設計に関する解説や、 VST3 規格におけるプラグインパラメータ、オートメーション、プログラムリストなどの仕様の解説が含まれています。また、ホストアプリケーション／プラグインそれぞれが継承するべきインターフェースクラスの解説も含まれています。

　VST3 規格は、設計のベース部分に VST Module Architecture (VST-MA) という仕組みを採用していて、 VST3 SDK の中でも VST-MA の仕組みを実装したコードが使用されています。そのため、 VST-MA の仕組みを理解しようとしたり VST-MA を利用したコードを読み書きするためには、 `VST-MA` のドキュメントを参照します。

　`Base Module` のドキュメントは、筆者の所感ではあまり参照することがありません。ただし、Base Module に含まれる `Steinberg::String` クラスや `Steinberg::IBStream` インターフェースクラスなどはホスト開発時にも利用するケースがあるため、これらのクラスに関するドキュメントも必要に応じて参照することになるでしょう。

　`Locations / Format` のドキュメントには、ホストアプリケーションからプラグインを探索するために用意された定義済みパスの仕様が記載されているため、そのあたりを実装しようとする場合にこのドキュメントを参照します。

　`FAQs` には、もとのドキュメントの箇所ではっきり書かれていなくて分かりにくい部分について、ここでもう少し詳しく補足されていることがあるので、一度目を通しておくのが良いでしょう。

## ドキュメントの問題点

　VST3 SDK のドキュメントにはいくつか問題点があって、利用する際に難儀することがあります。 VST3 SDK の利用者が最初にドキュメントを見て面食らってしまわないように、その問題点について記載しておきます。

1. 利便性が低い
    * VST3 SDK のドキュメントは、フレームで分けられた 2 ペインの HTML ドキュメントになっています。これによって、ページ遷移がうまく処理できなかったり、モバイルでの利用がしにくい問題があります。
    * また、ドキュメントが複数個の Doxygen ドキュメントに分かれているため、それらの間の横断的な参照がしにくい問題があります。
2. ドキュメントの作りが雑
    * 構造体や定数のドキュメントに対するリンクが正しく設定されていなくて、それらの定義に飛べないことがいくらかあります。
    * 他には、変な箇所に記述が混ざっていてそれが放置されていることがあります。（`VST 3 API Documentation`の冒頭箇所など）
3. 導入に関する解説が足りない
    * VST3 SDK のドキュメントには、インターフェースクラスの解説などはある程度充実していますが、 VST3 プラグインやホストアプリケーションを作るための導入となる解説がほとんどありません。そのため、最初に VST3 SDK を利用しようとしてもどこからどう手を付けていいか分からない問題があります。

## おわりに

　今回は、VST3 SDK のドキュメントについて解説しました。 [次回](https://qiita.com/hotwatermorning/items/76fe2efd147d8bf78c95) は VST3 SDK のライセンスについて解説します。