付録 E、パート 3

付録 E、パート 2」の続きです。

ライブラリ関数

imf__build_handle

定義

char *imf__build_handle

(

char *path,

char *handle,

char *ext

)

パラメータ修正される問題
path

入力

使用する検索パス

handle入力

ファイル名

ext入力

ファイル名の拡張子

戻り値 

完全なファイル名

説明

この関数は、pathhandle、および ext からファイル名を構築します。ファイルを開くときに返される文字列を使用します。

char *filename;

FILE *fp = NULL;

...

*info = &imf->info;

if ( info->handle_complete )

{

filename = info->handle;

}

else

{

filename = imf__build_handle( NULL, info->handle,

info->ext );

if ( ( fp = fopen( filename, "rb" ) ) == NULL )

{

filename = imf__build_handle( getenv(

"WF_IMG_DIR" ),

info->handle, info->ext );

}

}

if ( fp == NULL )

{

fp = fopen( filename, "rb" );

}

IMF_chan_alloc

定義

POINTER *IMF_chan_alloc

(

IMF_IMAGE *image,

int res,

char *key,

int *size

)

パラメータ修正される問題
image

入力

イメージ情報は、配分されるチャネル数、たとえば、カラー チャネル数、マット チャネル数、Z チャネル数などを指定します。

res入力

ピクセル単位のスキャンラインの幅

key入力

プラグインのキー。エラー メッセージに使用します。

size出力

配分されるスキャンラインのサイズ

戻り値 

メモリが不足している場合は NULL、それ以外は、スキャンライン バッファのポインタが返されます。

修正される問題

この関数は、スキャンライン データを Maya とスキャンラインの読み取りおよび書き込み関数間で渡すために使用されるスキャンライン バッファ セットを配分します。このバッファは、スキャンライン バッファのポインタの配列としてセットアップされます。1 番目の行にはカラー チャネル データ(赤、緑、青)、続いてマット チャネルおよび z チャネル(プラグインで定義されている場合)が含まれます。この関数は、imageReadOpen ルーチンから呼び出します。

IMF_chan_alloc は、プラグイン コードの上部で定義する imageBitsPerPaletteEntryimageBitsPerChannelimageBitsPerMatte、および imageBitsPerZChannel エントリ ポイントに応じて異なります。エントリ ポイントがチャネル単位に 1 ~ 8 ビットを定義する場合、バイト サイズのピクセルが配分されます。チャネルごとに 9 ~ 16 ビットが定義されている場合は、16 ビットの short ピクセルが割り当てられます。チャネルごとに 17 ~ 32 ビットが定義されている場合は、32 ビットの long ピクセルが割り当てられます。すべての値は unsigned 形式です。スキャンラインの読み取り関数と書き込み関数には、チャネル データの解釈を 8 ビットの符号なし文字、16 ビットのショート、あるいは 32 ビットのロングのどれで行うかを知らせておく必要があります。

このサンプル コード フラグメントはスキャンライン バッファを割り当てる方法、および IMF_chan_alloc によって割り当てられたスキャンライン バッファにアクセスする方法を示します。ピクセル単位に 8 ビットのカラー チャネルが 3 つ、ピクセル単位に 12 ビットのマット チャネルが 1 つ、ピクセル単位に 32 ビットの z チャネルが 1 つ存在します。imfIMF_OBJECT 構造であり、imageReadOpen 関数に渡されます。imageWriteOpenIMF_chan_alloc を呼び出ししません。これは、Maya アプリケーションでスキャンライン書き込み関数に渡されるスキャンライン バッファが割り当てられるためです。

POINTER *p_buffer;

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];

for ( i = 0; i < image_width; ++i )

{

p_red[i] = red_values[i];

p_blue[i] = blue_values[i];

p_green[i] = green_values[i];

p_matte[i] = matte_values[i];

p_z[i] = z_values[i];

}

スキャンライン書き込み関数では、同様の方法でバッファにアクセスします。

関連関数

IMF_chan_free

IMF_chan_free

定義

int IMF_chan_free

(

POINTER *chan_data

)

パラメータ修正される問題
chan_data

Modified

IMF_chan_alloc によって配分されるスキャンライン バッファのポインタのアドレス

戻り値 

未使用

説明

この関数は、以前に IMF_chan_alloc によって割り当てられたスキャンライン バッファ セットの割り当てを解除します。

data->buffer がスキャンライン バッファを示す場合、次を使用してバッファを解放します。

IMF_chan_free( data->buffer );

関連関数

IMF_chan_alloc

imf__free_obj

定義

int imf__free_obj

(

IMF_OBJECT *imf

)

パラメータ修正される問題
imf

Modified

幅や高さなどのイメージ特性を格納する構造

戻り値 

未使用

説明

この関数は、IMF_OBJECT 構造によって占有された空間の割り当てを解除します。この関数は終了関数でコールします。

imf->dataNULL でない場合、imf__free_objimf->data[0] によって示される空間を解放してから、imf->data を解放します。したがって、imf->data[1] または他の追加の空間を割り当てた場合、imageReadOpenimageWriteOpen の終了関数およびエラー処理ルーチンはこの空間の割り当てを解除して、メモリ リークを防止する必要があります。

イメージ ファイルを開こうとして失敗した場合、Maya は imf__free_obj( imf ) を呼び出して、imageReadOpen に渡された IMF_OBJECT を解放します。したがって、エラー処理コードで imf__free_obj を呼び出さないでください。終了関数をコールしてエラー処理とクリーンアップを実行する場合、終了関数はファイルを開くのに失敗した後の閉じる処理と、イメージ ファイルの読み取りに成功したあとの閉じる処理を区別する必要があります。終了関数は、イメージ ファイルが正常に読み取られた場合にのみ imf__free_obj を呼び出す必要があります。

imf__free_obj( imf );

関連関数

imf__init_ifd

imf__init_ifd

定義

int imf__init_ifd

(

IMF_OBJECT *imf

)

パラメータ修正される問題
imf

Modified

幅や高さなどのイメージ特性を格納する構造

戻り値 

未使用

説明

この関数は imf->info.image によって示されるイメージ ファイル記述子の構造を初期化します。この関数は imageReadOpen 関数で呼び出します。imf->info.image フィールドは imf__init_ifd を起動する前に、関数によって割り当てておく必要があります。

次のように、IMF_IMAGE 構造の既定値を定義します。

imf__init_ifd( imf );

関連関数

imf__free_obj

機能設定

イメージ プラグインを実装する場合、プラグインがサポートするファイル フォーマット機能を定義し、ユーザがイメージ ファイルにアクセスするためにファイル ブラウザでこれらの機能を指定できるようにするか、およびその指定方法を定義する必要があります。Maya はファイルにアクセスするときに、これらの機能を自動的にイメージ プラグインに渡します。これは機能設定と呼ばれます。たとえば、ディスクにイメージを書き込むとき、ユーザは使用する圧縮タイプを選択できます。ファイル フォーマットに特別な機能がなく、機能設定が必要でない場合もあります。

ユーザ インタフェースは次の 2 つの定義済み機能タイプをサポートします。

詳細については、imageCapabilityIMF_CAPABILITY を参照してください。

データ構造

IMF_CAPABILITY

定義

typedef struct imf_capability

{

U_SHORT imc_code;

char *imc_name;

MSGCAT_DEFN imc_name_msg;

U_CHAR imc_type;

POINTER imc_value;

U_CHAR imc_when_avail;

} IMF_CAPABILITY;

用途

特別なタイプ固有のパラメータを持つイメージ ファイルでは、IMF_CAPABILITY 構造を使用してドライバのタイプ固有の機能を定義します。機能は配列として格納され、機能単位に 1 つのエントリが含まれます。たとえば、SGI ドライバは 2 つの機能を備えています。1 つは圧縮モード用(未処理と RGB)で、もう 1 つは、ファイルにマット チャネルを作成するかどうかを定義するための機能です。

修正される問題

次の表は、各フィールドについて説明したものです。

フィールド修正される問題
imc_code

IMF_CAPABILITY 配列に定義されるすべての機能の中で固有の 16 ビット数

imc_name

機能を説明するユーザ インタフェースに表示される文字列

imc_name_msg

imc_name の国際化バージョン

imc_type

機能タイプ。現在、IMF_CAPABILITY_TYPE_LIST または IMF_CAPABILITY_TYPE_NUMBER のいずれかです。

imc_value

IMF_CAPABILITY_LIST または IMF_CAPABILITY_NUMBER 構造のいずれかのポインタ。imc_type に応じて異なります。

imc_when_avail

この機能が有効な場合に定義します。イメージの読み取りと書き込みの両方を行う場合は、IMF_CAPABILITY_WHEN_ALWAYS に設定します。イメージの読み取りを行う場合は、IMF_CAPABILITY_WHEN_INPUT に設定します。イメージの書き込みを行う場合は、IMF_CAPABILITY_WHEN_OUTPUT に設定します。

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 );
}

イメージ プラグインの追加の詳細については、引き続き、付録 E のパート 4 で説明します。