Maya の特長は、固有のイメージ ファイル トランスレータ機能を作成できる外部プラグイン モジュール機構です。これは Maya に新しいイメージを追加するためのシステムであり、Maya API とは異なります。これらのプラグイン モジュールは、アプリケーションを開始するときにいつでも使用可能です。イメージ ファイルにアクセスする場合に表示されるイメージ ファイル タイプのリストからこれらにアクセスできます。
プラグイン イメージ モジュールは動的な共有オブジェクトとして実装され(DSO または DLL)、C または C++ で記述できます。この場合、イメージ ファイルの読み取りと書き込みを行うアルゴリズムを実装するだけです。ユーザ インタフェースとフロー制御は Maya によって暗黙的に処理されます。
この文書では、イメージ プラグイン モジュールを記述するためのプロトコルについて説明します。複数のフレームまたはムービー ファイルのサポート方法については説明しません。サンプル コードは Developer Kit の image サブフォルダに収められています。
このセクションでは次の項目について説明します。
イメージ ファイル フォーマット プラグインを書き込むと、これをコンパイルして、Maya にロードできる共有オブジェクトを作成する必要があります。gcc コンパイラを使用したサンプルを構築するための、Makefile と buildconfig が Developer Kit に用意されています。Windows では、Visual C++ でイメージ プラグインを構築するためのソリューションとプロジェクト ファイルが用意されています。イメージ プラグインのサンプルを構築する前に、最初に MAYA_LOCATION を設定する必要があります。構築するプラグインは、Maya が新しいイメージ フォーマットにアクセスする前に、$MAYA_LOCATION/bin/plug-ins/image フォルダにコピーしてください。イメージ プラグインは、Maya にロードできるように用意されたコンパイラとリンカーのフラグを使用して構築する必要があります。
Maya は、主にイメージ ファイルの読み取りと書き込みのためにイメージ プラグインから関数を起動します。これが発生する場所には、レンダリング ウィンドウなどがあります。このウィンドウでは、特定のフォーマットとしてイメージを保存することを選択できます。さらに、このウィンドウに既存のレンダリング イメージをロードすることも可能です。このウィンドウの読み取り操作および書き込み操作用に定義したカスタム フォーマットを選択することができます。
各プラグインには、定義数のエントリ ポイントがあります。Maya はこれらのエントリ ポイントを使用して、イメージ プラグインがサポートする機能を定義します。
エントリ ポイントは変数や関数などです。たとえば、プラグインの名前は変数エントリ ポイント imageName で定義され、読み取り用のイメージ ファイルを開く関数は、関数エントリ ポイント imageReadOpen で定義されます。
エントリ ポイントには必須とオプションのものがあります。必須のエントリ ポイントについては次のセクションで説明します。オプションのエントリ ポイントについては「オプション エントリ ポイント」で説明します。
ヒント: 作成するプラグインに Maya との互換性を持たせる場合、必須のエントリ ポイントを実装するだけです。作成するプラグインのオプションのエントリ ポイントは、Maya で起動できない場合があるため、必須ではありません。
次のエントリ ポイントは定義する必要があります。
必須のエントリ ポイントが削除されると、プラグインがロードされないため、その名前はメニューに表示されません。
定義
char *program
説明
このエントリ ポイントは、プラグインを使用できるアプリケーションを指定します。すべてのアプリケーションがこのプラグインでサポートされるイメージ ファイルの読み取りと書き込みを実行できるようにするには、これに Wavefront を設定します。
注: このエントリ ポイントの定義は必須です。
例
char *program = "Wavefront";
定義
char *type
修正される問題
このエントリ ポイントは、構築するプラグインのタイプを示します。Maya のイメージ ファイル プラグインのタイプは、image です。
注: このエントリ ポイントの定義は必須です。
例
char *type = "image";
定義
char *version
説明
このエントリ ポイントは、プラグインを記述したプロトコルのバージョンを示します。常に IMF_PROTOCOL_CURRENT を使用します。
注: このエントリ ポイントの定義は必須です。
例
char *version = IMF_PROTOCOL_CURRENT;
定義
char *imageKey
説明
このエントリ ポイントは、プラグインを特定するための固有のキーを指定します。
注: このエントリ ポイントの定義は必須です。
例
char *imageKey = "myFormat";
定義
char *imageName
説明
このエントリ ポイントは、メニューに表示されるプラグインの名前を定義します。ユーザが区別できるように固有の名前を定義する必要があります。
注: このエントリ ポイントの定義は必須です。
例
char *imageName = "My Image Format";
定義
int imageReadOpen
(
IMF_OBJECT *imf
}
パラメータ | 型 | 修正される問題 |
---|---|---|
imf |
Modified |
イメージ ファイル ヘッダ |
戻り値 |
IMF_C_NORMAL イメージが正常に開かれた場合。IMF_C_ エラーが発生した場合。 |
修正される問題
この関数は、読み取り用にファイルを開くときにコールされます。
imf パラメータには、ファイルの読み取りに必要なすべての情報が含まれます。imageReadOpen を呼び出す前に、ここにファイル名を含めます。このルーチンの実行後、ここにファイルにアクセスするルーチンへのポインタ、サイズの情報、読み取るイメージの他のアトリビュート、イメージの走査線を読み込むバッファなども含める必要があります。
この関数を記述する基本手順を以下に示します。
複数のイメージ(フル イメージやサムネール表示など)を含むイメージ ファイルもあります。ここでは、ファイルからメイン イメージのみを読み取る場合について説明しています。
詳細な手順を次に示します。
``` imf->info.count = 1; imf->info.image = malloc( sizeof( IMF_IMAGE ) ); (void) imf__init_ifd( imf );
```
``` private = malloc( sizeof( PRIVATE ) ); private->... = ...; imf->data = malloc( sizeof( POINTER ) ); imf->data[0] = private;
```
imf->info 構造では、イメージがルックアップ テーブルを含むかどうかに応じて、lut_exists fieldを設定します。
program、machine、user、date、time、frame 番号、job_num、および色度情報(red_pri、green_pri、blue_pri、white_pt)がファイル自体に格納されている場合は、これらも設定できます。
また、imf->info.image[0] ですべてのフィールドを設定する必要があります。aux_format、aux_count、aux_type、および aux_bits フィールドは z チャネル情報を示します。curve.gamma フィールドには、ファイル内で定義したガンマを設定するか、または IMF_def_input_gamma を呼び出して既定のガンマを設定する必要があります。
``` private_data_ptr->buffer = IMF_chan_alloc( imf->info.image, image_width, imf->info.key, NULL );
```
注: このエントリ ポイントの定義は必須です。
定義
int your_scan_read_func
(
POINTER data,
int scan,
POINTER **line_buff
)
修正される問題
この関数は Maya によってコールされ、イメージ ファイルからスキャンラインを読み取ります。イメージ ファイルはイメージの方向に基づいて、下から上または上から下のいずれかの方向に読み取られます。
以下の手順に従って、スキャンライン読み取り関数を作成します。
スキャンラインの各成分は個別の隣接しているバッファに格納されます。これらは、割り当てられた成分へのポインタの配列であるパラメータ line_buff に格納されて返されます。
/*
* Unsigned char's are used for 1 to 8-bit values;
* unsigned short's, for 8 to 16-bit values;
* unsigned long's, for 17 to 32-bit values.
*/
*line_buff = data->buffer;
pr = (unsigned char *) data->buffer[0];
pg = (unsigned char *) data->buffer[1];
pb = (unsigned char *) data->buffer[2];
pm = (unsigned char *) data->buffer[3];
for ( i = 0; i < data->image_width; ++i )
{
*(pr++) = red_values[i];
*(pg++) = green_values[i];
*(pb++) = blue_values[i];
*(pm++) = matte_values[i];
}
ファイルにルックアップ テーブルが含まれている場合は、line_buff でルックアップ テーブルにインデックスではなく、RGB データを返す必要があります。
スキャンライン読み取り関数は、イメージの最新のスキャンラインを読み取るとは限りません。これは Maya が読み取る必要のない最新のスキャンラインをスキップする場合があるためです。プラグインでは、imageReadOpen の呼び出し後に Maya が いつでも終了関数を呼び出せるように許可する必要があります。
定義
int your_close_func
(
IMF_OBJECT *imf
)
パラメータ | 型 | 修正される問題 |
---|---|---|
imf |
Modified |
イメージ ファイル記述子 |
戻り値 |
IMF_C_NORMAL ファイルが閉じられ、メモリの再配分が成功した場合。IMF_C_failure_code エラーが発生した場合(IMF_C_WRITE_ERR など)。 |
この関数は、Maya でイメージ ファイルの読み取りまたは書き込みが完了するたびにコールされます。以下の手順に従って、終了関数を作成します。
定義
int imageWriteOpen
(
IMF_OBJECT *imf
)
パラメータ | 型 | 修正される問題 |
---|---|---|
imf |
Modified |
イメージ ファイル記述子 |
戻り値 |
TRUE イメージが正常に開かれた場合。FALSE エラーが発生した場合。 |
修正される問題
この関数は、書き込み用にファイルを開くときにコールされます。
imf パラメータには、ファイルの書き込みに必要なすべての情報が含まれます。imageWriteOpen を呼び出す前に、ここにファイル名を含めます。このルーチンの実行後、ファイルにアクセスするルーチンのポインタ、サイズの情報、および書き込むイメージの他のアトリビュートなども含める必要があります。
この関数を作成する基本手順を以下に示します。
詳細な手順を次に示します。
``` private = malloc( sizeof( PRIVATE ) ); private->... = ...; imf->data = malloc( sizeof( POINTER ) ); imf->data[0] = private;
```
イメージ ファイルを開こうとして失敗した場合、Maya は imf__free_obj( imf ) を呼び出して、imageWriteOpen に渡された IMF_OBJECT を解放します。したがって、エラー処理コードで imf__free_obj を呼び出さないでください。
注: このエントリ ポイントの定義は必須です。
定義
int your_scan_write_func
(
POINTER data,
int scan,
POINTER *line_buff
)
修正される問題
この関数は Maya によってコールされ、スキャンラインをイメージ ファイルに書き込みます。イメージ ファイルはイメージの方向に基づいて、下から上または上から下のいずれかの方向に書き込まれます。
以下の手順に従って、スキャンライン書き込み関数を作成します。
``` pr = (unsigned char ) line_buff[0]; pg = (unsigned char ) line_buff[1]; pb = (unsigned char ) line_buff[2]; pm = (unsigned char ) line_buff[3]; for ( i = 0; i < data->image_width; ++i ) { red_values[i] = (pr++); green_values[i] = (pg++); blue_values[i] = (pb++); matte_values[i] = (pm++); }
```
ファイル フォーマットで使用されるフォーマットに値を変換して、スキャンラインをファイルに書き込みます。
いくつかの追加のエントリ ポイントが存在します。オプションのエントリ ポイントが定義されていない場合、既定値が使用されます。使用するファイル フォーマットが機能をサポートしていない場合、無視されるオプションのエントリ ポイントもあります。
定義
unsigned int imageAccess
説明
この変数はプラグインがサポートする読み取りおよび書き込みメソッドを指定します。記述する定数はビット フィールドです。
既定値は IMF_C_READ|IMF_C_WRITE です。
例
この例は、ルックアップ テーブルをサポートするファイル用です。
``` unsigned int imageAccess = IMF_C_LUT_READ | IMF_C_LUT_WRITE | IMF_C_READ | IMF_C_WRITE;
```
イメージ プラグインの追加の詳細については、引き続き、付録 E のパート 2 で説明します。