Maya の特長は、固有のイメージ ファイル トランスレータ機能を作成できる外部プラグイン モジュール機構です。これは Maya に新しいイメージを追加するためのシステムであり、Maya API とは異なります。これらのプラグイン モジュールは、アプリケーションを開始するときにいつでも使用可能です。イメージ ファイルにアクセスする場合に表示されるイメージ ファイル タイプのリストからこれらにアクセスできます。
プラグイン イメージ モジュールは動的な共有オブジェクトとして実装され（DSO または DLL）、C または C++ で記述できます。この場合、イメージ ファイルの読み取りと書き込みを行うアルゴリズムを実装するだけです。ユーザ インタフェースとフロー制御は Maya によって暗黙的に処理されます。
この文書では、イメージ プラグイン モジュールを記述するためのプロトコルについて説明します。複数のフレームまたはムービー ファイルのサポート方法については説明しません。サンプル コードは Developer’s Kit の image サブディレクトリに収められています。
イメージ ファイル フォーマット プラグインを書き込むと、これをコンパイルして、Maya にロードできる共有オブジェクトを作成する必要があります。gcc コンパイラを使用したサンプルを構築するための、Makefile と buildconfig が Developer’s Kit に用意されています。Windows では、Visual C++ でイメージ プラグインを構築するためのソリューションとプロジェクト ファイルが用意されています。イメージ プラグインのサンプルを構築する前に、最初に MAYA_LOCATION を設定する必要があります。構築するプラグインは、Maya が新しいイメージ フォーマットにアクセスする前に、$MAYA_LOCATION/bin/plug-ins/image ディレクトリにコピーしてください。イメージ プラグインは、Maya にロードできるように用意されたコンパイラとリンカのフラグを使用して構築する必要があります。
Maya は、主にイメージ ファイルの読み取りと書き込みのためにイメージ プラグインから関数を起動します。これが発生する場所には、レンダリング ウィンドウなどがあります。このウィンドウでは、特定のフォーマットとしてイメージを保存することを選択できます。さらに、このウィンドウに既存のレンダリング イメージをロードすることも可能です。このウィンドウの読み取り操作および書き込み操作用に定義したカスタム フォーマットを選択することができます。
各プラグインには、定義数のエントリ ポイントがあります。Maya はこれらのエントリ ポイントを使用して、イメージ プラグインがサポートする機能を定義します。
エントリ ポイントは変数や関数などです。たとえば、プラグインの名前は変数エントリ ポイント imageName で定義され、読み取り用のイメージ ファイルを開く関数は、関数エントリ ポイント 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 );
スキャンラインの各成分は個別の隣接しているバッファに格納されます。これらはパラメータ line_buff に返され、配分した成分へのポインタの配列になります。
* 符号なし char は 1 ～ 8 ビットの値に使用されます。
* 符号なし short は 8 ～ 16 ビットの値に使用されます。
* 符号なし long は 17 ～ 32 ビットの値に使用されます。
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 )
ファイルにルックアップ テーブルが含まれる場合は、line_buff でルックアップ テーブルにインデックスではなく、RGB データを返す必要があります。
スキャンライン読み取り関数は、イメージの最新のスキャンラインを読み取るとは限りません。これは Maya が読み取る必要のない最新のスキャンラインをスキップする場合があるためです。プラグインでは、imageReadOpen のコール後、いつでも終了関数のコールが許可される必要があります。
private = malloc( sizeof( PRIVATE ) );
private->... = ...;
imf->data = malloc( sizeof( POINTER ) );
imf->data[0] = private;
イメージ ファイルを開くのに失敗した場合、imf__free_obj( imf ) がコールされ、imageWriteOpen に渡された IMF_OBJECT が解放されます。したがって、エラー処理コードで imf__free_obj をコールしないでください。
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++);
}
いくつかの追加のエントリ ポイントが存在します。オプションのエントリ ポイントが定義されていない場合、デフォルト値が使用されます。使用するファイル フォーマットが機能をサポートしていない場合、無視されるオプションのエントリ ポイントもあります。
この関数は、Maya でメニューに表示する機能を定義する場合、初期化時にコールされます。機能の詳細については、 IMF_CAPABILITY を参照してください。
この汎用コード フラグメントは、機能のプラグインのリストをループします。
*capabilities = your_capabilities;
for ( *num_input = *num_output = *total = i = 0;
i < number_elements_in( your_capabilities );
if ( your_capabilities[i].imc_when_avail
if ( your_capabilities[i].imc_when_avail
& IMF_CAPABILITY_WHEN_OUTPUT )
if ( your_capabilities[i].imc_when_avail
これらは目的のファイル名を生成するために、自由に組み合わせることができます。名前、フレーム番号、および拡張子はそれぞれ 1 回しか使用されませんが、# は繰り返してフレーム番号のゼロ パディングに使用できます。
if ( ( *imf_lut = IMF_lut_alloc(
data->your_color_map_size ) ) == NULL )
{return( FALSE );
}
この関数は、スキャンライン データを Maya とスキャンラインの読み取りおよび書き込み関数間で渡すために使用されるスキャンライン バッファ セットを配分します。このバッファは、スキャンライン バッファのポインタの配列としてセットアップされます。1 番目の行にはカラー チャンネル データ（赤、緑、青）、続いてマット チャンネルおよび z チャンネル（プラグインで定義されている場合）が含まれます。この関数は、imageReadOpen ルーチンからコールします。
IMF_chan_alloc は、プラグイン コードの上部に定義する imageBitsPerPaletteEntry、imageBitsPerChannel、imageBitsPerMatte、および imageBitsPerZChannel エントリ ポイントに応じて異なります。エントリ ポイントがチャンネル単位に 1 ～ 8 ビットを定義する場合、バイト サイズのピクセルが配分されます。チャンネル単位に 9 ～ 16 ビットを定義する場合、16 ビットのショート ピクセルが配分されます。チャンネル単位に 17 ～ 32 ビットを定義する場合、32 ビットのロング ピクセルが配分されます。すべての値は符号なし形式です。スキャンラインの読み取り関数と書き込み関数には、チャンネル データの解釈を 8 ビットの符号なし文字、16 ビットのショート、あるいは 32 ビットのロングのどれで行うかを知らせておく必要があります。
このサンプル コード フラグメントはスキャンライン バッファを配分し、IMF_chan_alloc によって配分されたスキャンライン バッファにアクセスする方法を示します。ピクセル単位に 8 ビットのカラー チャンネルが 3 つ、ピクセル単位に 12 ビットのマット チャンネルが 1 つ、ピクセル単位に 32 ビットの z チャンネルが 1 つ存在します。imf は IMF_OBJECT 構造であり、imageReadOpen 関数に渡されます。imageWriteOpen は IMF_chan_alloc をコールしません。これは、Maya アプリケーションでスキャンライン書き込み関数に渡されるスキャンライン バッファが配分されるためです。
p_buffer = IMF_chan_alloc( imf->info.image,
image_width, imf->info.key, NULL);
スキャンライン読み取り関数では、以下のようにデータをバッファに格納します。
unsigned char *p_red = p_buffer[0];
unsigned char *p_blue = p_buffer[1];
unsigned char *p_green = p_buffer[2];
unsigned short *p_matte = p_buffer[3];
unsigned long *p_z = p_buffer[4];
この関数は、IMF_OBJECT 構造によって占有された空間の配分を解除します。この関数は終了関数でコールします。
imf->data が NULL でない場合、imf__free_obj は imf->data[0] によって示される空間を解放し、imf->data を解放します。したがって、imf->data[1] または他の追加の空間を配分した場合、imageReadOpen と imageWriteOpen の終了関数およびエラー処理ルーチンはこの空間の配分を解除して、メモリ リークを防止する必要があります。
イメージ ファイルを開くのに失敗した場合、imf__free_obj( imf ) がコールされ、imageReadOpen に渡された IMF_OBJECT が解放します。したがって、エラー処理コードで imf__free_obj をコールしないでください。終了関数をコールしてエラー処理とクリーンアップを実行する場合、終了関数はファイルを開くのに失敗した後の閉じる処理と、イメージ ファイルの読み取りに成功したあとの閉じる処理を区別する必要があります。終了関数は、イメージ ファイルが正常に読み取られた場合にのみ imf__free_obj をコールする必要があります。
イメージ プラグインを実装する場合、プラグインがサポートするファイル フォーマット機能を定義し、ユーザがイメージ ファイルにアクセスするためにファイル ブラウザでこれらの機能を指定できるようにするか、およびその指定方法を定義する必要があります。Maya はファイルにアクセスするときに、これらの機能を自動的にイメージ プラグインに渡します。これは機能設定と呼ばれます。たとえば、ディスクにイメージを書き込むとき、ユーザは使用する圧縮タイプを選択できます。ファイル フォーマットに特別な機能がなく、機能設定が必要でない場合もあります。
ユーザ インタフェースは次の 2 つの定義済み機能タイプをサポートします。
詳細については、 imageCapabilityおよび IMF_CAPABILITYを参照してください。
capabilities は汎用パラメータです。imageReadOpen または imageWriteOpen がコールされると、機能の特定のユーザ定義インスタンスが settings として渡されます。このサンプル コード フラグメントはこれらの設定の意味を抽出する方法を示します。
static BOOLEAN your_get_capability_settings
(
IMF_OBJECT *imf,
int *mode
)
{IMF_CAPABILITY *capability;
IMF_CAP_SETTING *setting;
IMF_CAP_SETTING **settings;
if ( ( settings = imf->info.settings ) == NULL )
{return( TRUE );
}
for ( /* Nothing */; setting = *settings; ++settings )
{/*
* Lookup the capability by code.
*/
for ( capability = your__capabilities; capability->imc_name_msg.mcd_set!= 0; ++capability )
{if ( capability->imc_code == setting->imcs_code )
{break;
}
}
if ( capability->imc_name_msg.mcd_set == 0 )
{ERR_printf( "Bad capability found." );
return( FALSE );
}
switch ( capability->imc_code )
{case YOUR_CAPABILITY_IMC_CODE:
*mode =setting->imcs_value.imcs_list;
break;
case ANOTHER_CAPABILITY_IMC_CODE:
...;
break;
case ...:
default:
ERR_printf( "Bad capability found.");
return( FALSE );
}
}
return( TRUE );
}
icn_minimum_dfnd と icn_maximum_dfnd が両方とも TRUE である場合、テキスト フィールドの横にスライダが表示されます。それ以外は、サムホイールが表示されます。
イメージ ファイル フォーマット プラグインを書き込むと、これをコンパイルして、Maya にロードできる共有オブジェクトを作成する必要があります。gcc コンパイラを使用したサンプルを構築するための、Makefile と buildconfig が Developer’s Kit に用意されています。Windows では、Visual C++ でイメージ プラグインを構築するためのソリューションとプロジェクト ファイルが用意されています。イメージ プラグインのサンプルを構築する前に、最初に MAYA_LOCATION を設定する必要があります。構築するプラグインは、Maya が新しいイメージ フォーマットにアクセスする前に、$MAYA_LOCATION/bin/plug-ins/image ディレクトリにコピーしてください。イメージ プラグインは、Maya にロードできるように用意されたコンパイラとリンカのフラグを使用して構築する必要があります。