C++ ライブラリに対する MATLAB インターフェイスの定義

ライブラリ定義ファイルの定義を完成させる方法

MATLAB^® インターフェイスは C++ 関数シグネチャを MATLAB 関数シグネチャに変換します。一部の C++ 言語構成要素は MATLAB 言語に一意の一致がありません。MATLAB は、パブリッシャーが不足情報を提供するために作成し変更する "ライブラリ定義ファイル" (拡張子は M) を使用します。パブリッシャーには、関数シグネチャを解釈して不足している情報を提供するだけの十分な C++ 言語スキルがなければなりません。

MATLAB では、これらの不完全な定義について、次の clibgen.generateLibraryDefinition 警告メッセージで通知します。

Warning: Some C++ language constructs in the files for generating interface file 
are not supported and not imported.

パブリッシャーが定義しなければならない情報の例は、関数にデータを渡す "ポインター" の使用に関係します。ポインターは、データのブロックの開始を示すメモリ内の場所です。このデータを MATLAB に安全に渡すために、パブリッシャーはデータのサイズを指定しなければなりません。データのサイズは関数のドキュメンテーションに (おそらく追加の入力引数として) 示されています。パブリッシャーが MATLAB 定義ファイルを使用して値を指定すると、MATLAB は同等の MATLAB 関数シグネチャを作成します。関数シグネチャを表示する場合は、C++ ライブラリに対する MATLAB インターフェイスのヘルプの表示を参照してください。

clibgen.generateLibraryDefinition を使用してライブラリ定義ファイル definelibName.m を作成した後、インターフェイスに機能を含めるために内容を変更しなければならない場合があります。MATLAB エディターを使用して定義ファイルを変更します。<DIRECTION>、<SHAPE>、および <MLTYPE> の各パラメーターを、不足している情報に置き換えます。これらのパラメーターは、次の場合に使用されます。

ポインター引数が読み取り専用の入力、出力のみ、変更可能な入力引数のいずれであるかを指定するには、DIRECTION パラメーターを使用します。
ポインター引数が配列データに使用される場合は、C++ と MATLAB の間で配列を変換するために次元の情報が必要です。この情報を指定するには、SHAPE パラメーターを使用します。
C++ には、文字列引数を表す多くの型があります。MATLAB が C++ 型を MATLAB の string 型に正しく変換できるように、MLTYPE 値と SHAPE 値を指定しなければならないことがあります。

MATLAB は、これらのパラメーターの値についてコードの候補を提供します。特定のパラメーターに対する候補を有効にするには、次を行います。

関数を定義するコードのコメントを解除する。セクションタイトルと C++ シグネチャのヘルプを含むコードセクションの最初の 2 行をコメント解除しない。
<> 文字を含めてパラメーター名を削除する。
一時停止してコードの候補を表示する。
候補が表示されない場合、definelibName.m ファイルが MATLAB パスにあることを確認する。

引数の自動定義

clibgen.generateLibraryDefinition と clibgen.buildInterface の名前と値の引数を使用して、特定の引数タイプの型および形状を自動定義するように MATLAB に指示できます。次のオプションがあります。

ライブラリ内のすべての const 文字ポインターを null で終了する C の文字列として扱うには、引数TreatConstCharPointerAsCStringを true に設定します。
ライブラリ内のすべてのオブジェクトポインターをスカラーとして扱うには、引数TreatObjectPointerAsScalarを true に設定します。

ライブラリ定義の検証時に、重複する MATLAB シグネチャに関するエラーが表示されることがあります。これらのエラーを解決するには、MATLAB シグネチャの競合の調整を参照してください。

MATLAB シグネチャの競合の調整

ライブラリ定義ファイルを生成して編集した後、同一の MATLAB シグネチャをもつ関数または他の構成要素が 2 つ以上存在することがあります。この競合をチェックするには、定義ファイルを検証します。たとえば、定義ファイル definelibname の場合は、次を入力します。

definelibname

競合がある場合、MATLAB はエラーと共に定義ファイル内のコードへのリンクを表示します。競合を解決するには、以下のいずれかを選択します。

defineArgument または defineOutput の引数を修正して、一意の MATLAB シグネチャを作成します。複数のオーバーロードされた関数があり、同じ引数のパラメーターが指定されたときに競合が発生します。ライブラリ定義ファイルの定義を完成させる方法を参照してください。
構成要素の定義をコメントアウトすることで、関数のいずれかを削除します。clibgen.generateLibraryDefinition の名前と値の引数のいずれかを使用して特定タイプのすべてのケースを変換するときに、競合が発生することがあります。オーバーロードされた関数を削除することもできます。

定義ファイルの修正後、ファイルを再実行して編集内容を検証します。

内容のカスタマイズ

MATLAB によって使用される名前変更方式を確認して、無効な名前を置き換えます。詳細については、MATLAB で無効な C++ 名を参照してください。

自動生成されたヘルプを確認します。MATLAB は一部の C++ コメントを Description および DetailedDescription の引数にコピーします。この内容は変更または置き換えることができ、これがエンドユーザー向けの doc コマンドの基礎になります。

関数テンプレートの名前のカスタマイズ

ライブラリ定義ファイル内の関数テンプレートから生成された一意の関数名を確認します。たとえば、このヘッダーファイル内のクラス A は関数テンプレート show を定義し、型 int、double、および const A のインスタンス化を提供します。

class A{}; // User type
template<typename T> void show(T a) {}
template void show<int>(int);
template void show<double>(double);
template<> void show<const A &>(const A& a){}

このライブラリにインターフェイス libname をビルドする場合、MATLAB はこれらのインスタンス化のためのシグネチャをもつオーバーロードされた関数を作成します。

summary(definelibname)

MATLAB Interface to libname Library

Class clib.libname.A

  Constructors:
    clib.libname.A(clib.libname.A)
    clib.libname.A()

  No Methods defined

  No Properties defined

Functions
clib.libname.show(int32)
clib.libname.show(double)
clib.libname.show(clib.libname.A)

C++ インターフェイスは、シグネチャの型に基づいて一意の関数名も生成します。その一意の名前を表示するには、TemplateUniqueName プロパティを使用します。

d = definelibname;
d.Functions(1:3).TemplateUniqueName

ans = "clib.libname.show_int_"
ans = "clib.libname.show_double_"
ans = "clib.libname.show_AConst__"

これらの名前をライブラリ定義ファイルでカスタマイズできます。たとえば、クラスオブジェクト clib.libname.show_AConst__ 用の関数の名前を変更します。MATLAB を再起動し、definelibname.m を編集します。関数 show_AConst__ についての addFunction ステートメントの位置を特定し、"TemplateUniqueName" の名前と値の引数を変更します。show_AConst__ を showObjectA などの新しい名前に置き換えます。clib.libname.show を新しい名前 clib.libname.showObjectA に置き換え、ヘルプテキストを Representation of C++ function show for class A と読み取れるように変更して、"Description" の名前と値の引数を更新します。

"Description", "clib.libname.showObjectA    Representation of C++ function show for class A.");

help clib.libname.showObjectA

 clib.libname.showObjectA    Representation of C++ function show for class A.

    Inputs
      a              read-only clib.libname.A

詳細については、Use Function and Member Function Templatesを参照してください。

次元のマッチング

MATLAB 引数の次元数がそれに対応する C++ パラメーターよりも大きい場合、MATLAB は次元数が互いに一致するまで大きさが 1 の次元を左から削除していきます。大きさが 1 の次元をすべて削除しても MATLAB 引数が C++ パラメーターよりも大きい場合、MATLAB は例外を生成します。

MATLAB 引数の次元数が C++ パラメーターよりも小さい場合、MATLAB は大きさが 1 の次元を追加します。既定では、MATLAB は引数の先頭に大きさが 1 の次元を挿入します。大きさが 1 の次元を引数の末尾に挿入するには、defineArgument の関数 defineArgument (ConstructorDefinition)、defineArgument (FunctionDefinition)、および defineArgument (MethodDefinition) で、AddTrailingSingletons を true に設定します。

たとえば、C++ ライブラリのインターフェイス libname には、次のように定義された入力引数をもつ 2 つの関数が含まれています。

void setImages(const uint8_t * images, int numOfImages, int height, int width);

% By default 'AddTrailingSingletons' is false
defineArgument(setImagesFunctionDefinition, "images", "uint8", "input", ...
    ["numOfImages", "height", "width"])

void setColorImage(const uint8_t * image, int height, int width, int colorDepth);

defineArgument(setColorImageFunctionDefinition, "image", "uint8", "input", ...
    ["height", "width", "colorDepth"], "AddTrailingSingletons", true)

MATLAB で、イメージ配列を次のように作成します。

size(myImage)

ans =
     768   1024

setImages を呼び出すと、MATLAB で myImage のサイズが [1, 768, 1024] に調整されます。

setImages(myImage)

setColorImage を呼び出すと、MATLAB で myImage のサイズが [768, 1024, 1] に調整されます。

setColorImage(myImage)

参考

clibgen.generateLibraryDefinition | clibgen.buildInterface