Max 5 API Reference
Max 5 API Reference
この SDK ドキュメントには、Max エクスターナルオブジェクトのサンプルをコンパイルするための一連のプロジェクトが含まれています。これらのプロジェクトをビルドする方法についての詳細は、Mac と Windows の２つの場合に分けて後述します。
これらのプロジェクトのサンプルをビルドすると、プロジェクトのある階層から２つ上がった場所の、"sdk-build" というフォルダの中にMax のエクスターナルオブジェクトが作成されます。SDKのフォルダ構成を変更しなければ、この"sdk-build"フォルダは MaxSDK フォルダの中にあるはずです。
Max の File Preferences（ファイル初期設定）ウィンドウで、この sdk-build フォルダを Max のサーチパスに追加しておくことを推奨します。こうしておくと、MaxSDK フォルダを好きな場所に置き、ビルドを行なった後で開発したオブジェクトを Cycling' 74 フォルダにコピーしなくても Max に読み込ませることができます。
Mac の場合、Max のエクスターナルオブジェクトは Mach-O バンドル（ファイルとして表示されるフォルダ）になります。このファイル名の最後には .mxo という拡張子をつけなければなりません。サンプルのプロジェクトは Xcode 3.x のフォーマットになっています。Xcode をダウンロードするには、フリーの Apple Developer アカウントを作る必要があります。詳細はhttp://developer.apple.com/をご覧下さい。
サンプルのプロジェクトには Development と Deploymento という２つのビルドコンフィギュレーションが設定されています。Development コンフィギュレーションは最適化を行なわず、実際に使用しているプラットフォーム（すなわち、PPCマシンでは PPC、Intel マシンでは Intel）だけをターゲットにしています。Deployment コンフィギュレーションではユニバーサルバイナリが作成され、最適化が行なわれます。
このプロジェクトで必要なファイルは、次の２つのファイルを除いてプロジェクトのフォルダにあります。
これら２つのファイルは、XCodeプロジェクトがMax エクスターナルをビルドするために必要なもので、プロジェクトのフォルダから１階層上がったフォルダに置いてあります。
エクスターナルオブジェクトは、ダイナミックリンクにより、Max アプリケーションが提供する API 関数にアクセスします。オブジェクトが読み込まれる際、アプリケーション内部の関数の呼び出しは、オペレーティングシステムによって正しいメモリアドレスに解決されます。エクスターナルオブジェクトのXcode プロジェクトは、アプリケーションとのリンクを行なうために、個々にMaxAPI.framework を参照しなければなりません。フレームワーク（framework）はMaxAPIの中の関数を定義するライブラリです。Max がアプリケーションとしてだけでなく、作成されたスタンドアロンとして、あるいは他のアプリケーション内のライブラリとして存在することが可能であるということから、エクスターナルオブジェクトのための Max API の関数を定義するコードは、実際にはMaxAPI.frameworkには含まれていません。その代わりに、このフレームワークはエクスターナルオブジェクトを、実際のコードを含む特定のライブラリやアプリケーションの実装から分離させる働きを持っています。
これに対し、オーディオオブジェクトは MaxAudioAPI.framework に、そして Jitter オブジェクトは JitterAPI.frameworkにリンクしますが、これらのフレームワークは MaxAPI.framework とは違って、実際にライブラリです。フレームワークの最新のバージョンは、ご使用になっているアプリケーションの内部にあります（これらは、Contents/Frameworks の中のアプリケーションバンドルの内部で見つけることができます）。さらに、SDK の中の c74support フォルダの中にもこれらのフレームワークがありますが、これはオブジェクトをリンクさせるためだけに用いられ、実際に実行されることはありません。
Xcode は フレームワーク・サーチパス（Framweorks Search Path）と呼ばれるものを使って、リンクの際に用いられるフレームワークの場所を探します。SDK に付属するサンプルのプロジェクトではフレームワーク・サーチパスとして、Xcode プロジェクトが収められているフォルダより２階層上にある c74support フォルダが設定されています。SDK フォルダの構成を変更してしまうと、プロジェクトはフレームワークを見つけることができず、正確にリンクすることができなくなってしまう可能性があります。さらに、フレームワーク・サーチパスを指定した場合でも、Xcolde は /Librar/Frameworks を最初に見に行ってしまうようです。Max SDK の バージョン 4.6 以前のものがインストールされている場合、/Library/Frameworks 内に古いバージョンの MaxAPI.framework や MaxAudioAPI.framework が存在することが考えられます。最新の MaxAPI.frameworkの中でのみ定義されている関数への参照を持ったオブジェクトをリンクしようとすると、オブジェクトが古いフレームワークを使用するためにリンクに失敗してしまうでしょう。この問題を解決するためには、/Library/Frameworks フォルダから、Max frameworks を取り除く必要があります。もし、Max 4.6 用のオブジェクトと Max5 用のオブジェクトを同じマシンで開発したいという場合には、4.6 のプロジェクトを修正してフレームワーク・サーチパスを指定し、その指定した場所に 4.6 のフレームワークを移動させる必要があります。
Windows の Max エクスターナルオブジェクトはダイナミックリンクライブラリ（DLL）で、ファイル名の最後には .mxe という拡張子をつけなければなりません。この DLL は "main" という１つの関数をエクスポートします。この関数はエクスターナルオブジェクトが最初に読み込まれたときに、Max から呼び出されます。通常、これらの DLL はMaxAPI の関数を "MaxAPI.lib" というインポートライブラリからインポートします。このライブラリファイルは c74support\max-includes\ フォルダに置かれています。オーディオ機能を使用するエクスターナルオブジェクトの場合、関数を "MaxAudio.lib" というインポートライブラリからインポートしますが、このライブラリファイルは c74support\msp-includes フォルダに置かれています。
サンプルのプロジェクトはVisual C++ 2008 のフォーマットになっています。 Visual C++ のフリーバージョンは Microsoft の http://www.microsoft.com/express/ から手に入れることができます。これらのプロジェクトは デバッグ（Debug） と リリース（Release）という２つのコンフィギュレーション（ビルド環境設定）を持つように設定されています。デバッグというコンフィギュレーションでは最適化が行なわれないのに対し、リリースでは最適化が行なわれます。デバッグを行なう場合、オブジェクトを動作を試すことができるのは Max ランタイム環境だけであるという点に注意して下さい。これは、Max アプリケーションのコピープロテクトが、デバッガ上での実行に対して干渉してしまうためです。
もう１つの注意すべき点は、Max がMicrosoft C ランタイムライブラリのプライベートビルドを持っているということです。このバージョンの C ランタイムライブラリとリンクすることにより、配布されるエクスターナルが Microsoft の Cランタイムに依存してしまうのではないかという点を心配をせずにすみます。MaxAPI の "ext.h" をインクルードすると、ext_prefix.h がインクルードされます。これにより、リリースコンフィギュレーションによるビルドを行なった場合、オブジェクトが自動的に Max C ランタイムライブラリを使用するようになります。Microsoft C ランタイムを使用したい場合には、ext.h をインクルードする前に、C プリプロセッサマクロで MAXAPI_USE_MSCRT を定義することによって可能になります。
Cygwin を使って Windows 版の Max エクスターナルオブジェクトをコンパイルすることもできます。ここでは、Cygwin の gccコンパイラ（Gnu コンパイラコレクション）を使って MaxMSP SDK の simplemax プロジェクトをビルドする方法について順を追って示します。Windows 版の Cygwin Unix tools を使用することにより、高品質でフリーの C コンパイラを利用できます。
次の Cygwin パッケージをインストールします。お好みによって、他の Cygwin パッケージを追加しても構いません。Cygwin インストーラや、より詳しい情報は http://www.cygwin.com/ にあります。
ステップ 1:
gcc -c -mno-cygwin -DWIN_VERSION -DWIN_EXT_VERSION -I../../c74support/max-includes simplemax.c
gcc コマンドライン引数の説明:
"-c" はコンパイルを意味します。
"-mnocygwin" は、Cygwin の標準 C ライブラリの代わりに、Microsoft の標準 C ライブラリを使用することを意味します。Cygwin をインストールしていないかもしれないユーザに対してエクスターナルを配布する場合には、このステップは特に重要です。
"-DWIN_VERSION" および "-DWIN_EXT_VERSION" というコマンドライン上でのプリプロセッサ定義により、ヘッダファイルやソースファイルが、Macintosh ではなく、Windows マシン用にコンパイルされることを前提としているということを保証します。
"-I../../c74support/max-includes" は、必要なヘッダファイルを探し出すための、追加のディレクトリを指定します。
"simplemax.c" は、コンパイラへの入力ソースです。
ステップ 2:
gcc -shared -mno-cygwin -o simplemax.mxe simplemax.o simplemax.def -L../../c74support/max-includes -lMaxAPI
gcc のコマンドライン引数の説明:
"-shared" は、DLL を メイクするためのリンクファイルを意味します。
"-mnocygwin" は、Cygwin の標準 C ライブラリの代わりに、Microsoft の標準 C ライブラリを使用することを意味します。Cygwin をインストールしていないかもしれないユーザに対してエクスターナルを配布する場合には、このステップは特に重要です。
"-o simplemax.mxe" は出力ファイルのファイル名を指定します。
"simplemax.o" および "simplemax.def" はリンカへの入力です。main 関数が確実にエクスポートされるためには、.def ファイルが必要です。
"-I../../c74support/max-includes" は、ライブラリファイルを探し出すための、追加のディレクトリを指定します。
"-lMaxAPI" は、MaxAPI.dll のために MaxAPI.lib リンカライブラリにリンクするということを意味します。
ステップ 3: 作成したファイルを、サーチパス内のディレクトリにコピーします。次は、その例です。
cp minimum.mxe c:\Program Files\Common Files\Cycling '74\myexterns\
新しいエクスターナルを作成する最も簡単な方法は、SDK にあるサンプルの１つを選んでコピーし、変更する必要がある設定（プロジェクト名など）だけを変更するというやり方です。この方法を用いると、重要なプロジェクト設定が正しいものであることが保証されます。特に重要なプロジェクト設定について、以下に記述します。
Mac 上でのエクスターナルで特に重要な点は、info.plist を正しく設定し、「Force Package Info Generation」 を true に設定することです。これを行なっていないと、マシンによってはオブジェクトの読み込みに失敗する可能性があります。
Visual Studio プロジェクトのプリプロセッサ定義の中で、WIN_VERSION と EXT_WIN_VERSION を定義することが重要です。これによってヘッダが正しく設定されることが保証されます。
クロスプラットフォームのオブジェクトを書いていて、特定の１つのプラットフォームだけで行ないたいことがある場合には、Max API のヘッダが提供するいくつかの定義済みシンボルを使用することができます。
#ifdef MAC_VERSION // do something specific to the Mac #endif #ifdef WIN_VERSION // do something specific to Windows #endif
訳注1: 複数バイトのデータをメモリに格納する場合、上位バイトから格納する方法（ビッグエンディアン）と、下位バイトから格納する方法（リトルエンディアン）があります。これは、プラットフォームによって異なる場合があります。