エントリポイント関数の入力のプロパティの指定

入力プロパティを指定しなければならない理由

C および C++ は静的型付き言語であるため、MATLAB^® Coder™ ではコンパイル時に MATLAB ファイル内の変数すべてのプロパティを決定しなければなりません。MATLAB ファイル内の変数のプロパティを推定するために、MATLAB Coder は、"基本" 関数 ("最上位" 関数または "エントリポイント" 関数としても知られる) への入力のプロパティを特定できなければなりません。そのため、基本関数に入力がある場合は、これらの入力のプロパティを MATLAB Coder に指定しなければなりません。基本関数が入力パラメーターをもたない場合は、MATLAB Coder では MATLAB ファイルを修正せずにコンパイルできます。基本関数から呼び出されるローカル関数または外部関数に対する入力のプロパティは指定する必要はありません。

メモ

基本関数をパッケージ内に含めることはできません。パッケージ外にラッパー関数を基本関数として作成します。新しい関数内で望ましい関数を基本関数として呼び出します。

チルダ (~) 文字を使用して未使用の関数入力を指定する場合は、以下を行います。

MATLAB Coder プロジェクトで、生成されるコードに異なる型を表示させる場合は、その型を指定します。それ以外の場合は、入力は既定で実数のスカラーの double になります。
codegen を使用してコードを生成する場合は、-args オプションを使用してこれらの入力の型を指定しなければなりません。

指定するプロパティ

基本関数が入力をもつ場合は、入力ごとに次のプロパティを指定しなければなりません。

対象	指定するプロパティ
	クラス	サイズ	実数/複素数	numerictype	fimath
固定小数点入力
構造体の入力の各フィールド	クラスに応じた各フィールドのプロパティの指定基本入力が構造体のときは、コードジェネレーターは各フィールドを個別の入力として扱います。そのため、基本構造体入力のすべてのフィールドに対して、構造体の定義で指定されている順番で、プロパティを指定しなければなりません。入力構造体の各フィールドに、クラス、サイズおよび実数/複素数を指定します。また、固定小数点クラスである各フィールド、`numerictype` と `fimath` を指定します。
その他の入力

既定のプロパティ値

MATLAB Coder では基本関数入力のプロパティに対して次の既定値が割り当てられます。

プロパティ	既定値
クラス	`double`
サイズ	`scalar`
実数/複素数	`real`
`numerictype`	既定値なし
`fimath`	MATLAB 既定の `fimath` オブジェクト

構造体フィールドに対する既定値の指定. ほとんどの場合、プロパティに対して明示的に値が指定されていないときは、MATLAB Coder では、構造体フィールドを除き、既定値が使用されます。構造体内のフィールドに名前を付けるには、そのプロパティの少なくとも 1 つを設定することが唯一の方法です。したがって、構造体フィールドのプロパティに対しては既定値を指定しなければならない場合があります。例については、スカラー構造体のクラスとサイズの指定と構造体配列のクラスとサイズの指定を参照してください。

MEX 関数に対する既定の fimath 値の指定. MATLAB Coder を使用して生成された MEX 関数は、実際にはコンパイル時に既定の fimath 値を使用します。既定の fimath 値を指定しない場合、MATLAB Coder は、MATLAB の既定の fimath を使用します。MATLAB 出荷時の既定のプロパティは以下のとおりです。

RoundingMethod: Nearest
OverflowAction: Saturate
ProductMode: FullPrecision
SumMode: FullPrecision
CastBeforeSum: true

詳細は、fimath による演算規則の共有 (Fixed-Point Designer)を参照してください。

既定の fimath 値に依存する MEX 関数を実行しているときは、MATLAB セッション中にこの値を変更しないでください。変更すると、コンパイル時と実行時の fimath の値が一致していないという警告を受け取ります。

たとえば、次の MATLAB 関数 test を定義するとします。

function y = test %#codegen
y = fi(0);

関数 test は、fimath オブジェクトを明示的に指定することなく fi オブジェクトを構築します。したがって、test は、実際にはコンパイル時に既定の fimath オブジェクトに依存することになります。MATLAB プロンプトで、MEX 関数 text_mex を生成して MATLAB の既定の fimath の工場出荷時の設定を使用します。

codegen test
% codegen generates a MEX function, test_mex, 
% in the current folder

次に、test_mex を実行して MATLAB の既定の fimath 値を表示します。

test_mex
 
ans =
 
     0

          DataTypeMode: Fixed-point: binary point scaling
            Signedness: Signed
            WordLength: 16
        FractionLength: 15

ここで、ローカルの MATLAB の fimath 値を作成します。これ以降は既定値は使用しません。

F = fimath('RoundingMethod','Floor');

最後に、メモリから MEX 関数をクリアして、再度実行します。

clear test_mex
test_mex

不一致が検出され、エラーが発生します。

??? This function was generated with a different default
fimath than the current default.

Error in ==> test_mex

MEX 関数に対する複数のシグネチャの指定. エントリポイント関数から複数シグネチャの MEX 関数を生成するには、同じエントリポイント関数に対して複数の -args を指定します。生成された MEX 関数は、コード生成中に指定した複数のシグネチャで動作します。複数シグネチャの MEX の詳細については、複数のシグネチャに対する 1 つの MEX 関数の生成を参照してください。

サポートされているクラス

以下の表に MATLAB Coder でサポートされているクラス名を示します。

クラス名	説明
`logical`	真および偽の値の論理配列
`char`	文字配列
`int8`	8 ビット符号付き整数配列
`uint8`	8 ビット符号なしの整数配列
`int16`	16 ビット符号付き整数配列
`uint16`	16 ビット符号なしの整数配列
`int32`	32 ビット符号付き整数配列
`uint32`	32 ビット符号なしの整数配列
`int64`	64 ビット符号付き整数配列
`uint64`	64 ビット符号なしの整数配列
`single`	単精度浮動小数点または固定小数点の数値配列
`double`	倍精度浮動小数点または固定小数点の数値配列
`struct`	構造体配列
`embedded.fi`	固定小数点の数値配列

基本入力のプロパティの指定規則

基本入力のプロパティを指定するときは次の規則に従います。

cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。
MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。
MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。
クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictype と fimath プロパティを指定します。
クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

基本入力のプロパティの定義方法

方法	利点	短所
アプリを使用したエントリポイント関数の入力のプロパティの指定	MATLAB Coder プロジェクトで作業している場合は、使用が簡単。元の MATLAB コードを変更しない。 MATLAB Coder は、プロジェクトファイル内に定義を保存する。	大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
コマンドラインでの例による入力プロパティの定義メモ MATLAB ファイルでプログラムによって入力プロパティを定義する場合は、この方法は使用できません。	使いやすい。元の MATLAB コードを変更しない。少数の基本入力をもつ関数のプロトタイプを作成するために設計されている。	`codegen` を起動するたびにコマンドラインで指定しなければならない (スクリプトを使用しない場合)。大規模な構造体や配列など、大量のメモリを使用する入力を指定する場合は効率的でない。
MATLAB ファイル内でのプログラムによる入力プロパティの定義	MATLAB コードと統合されているため、MATLAB Coder を呼び出すたびにプロパティを再定義する必要がない。 MATLAB コード内にプロパティ指定のドキュメンテーションが提供されている。大きな構造体などメモリを大量に使用する入力を指定する場合に効率的である。	複雑な構文を使用する。 MATLAB Coder プロジェクトファイルは、現在、プログラムで定義されたプロパティを認識しない。プロジェクトを使用する場合は、入力の型をプロジェクトに再入力しなければならない。

コマンドラインオプション -args

関数 codegen には、基本 (エントリポイント) 関数の入力のプロパティを、値または型の例の cell 配列で指定する -args コマンドラインオプションがあります。cell 配列は、可変またはリテラル配列の一定値を使用できます。このオプションを使用することで、codegen を使用して MATLAB 関数のコードを生成すると同時に、入力のプロパティを指定します。

あるエントリポイント関数の出力の型を別の関数の入力として渡すことができます。入力としてのエントリポイント関数出力の受け渡しを参照してください。cell 配列入力の指定の詳細は、コマンドラインでの cell 配列入力の指定を参照してください。

必要な型を使用してエントリポイント MATLAB 関数を呼び出すテスト関数またはスクリプトがある場合は、coder.getArgTypes を使用して、関数入力の型を決定できます。coder.getArgTypes は、coder.Type オブジェクトの cell 配列を返します。この cell 配列は -args オプションを使用して codegen に渡すことができます。codegen の詳細は、基本入力の一般的なプロパティの指定を参照してください。

coder.Type オブジェクトは、コード生成の型エディターを使用して対話形式で作成することもできます。コード生成の型エディターを使用した入力の型の作成と編集を参照してください。

-args オプションを使用する場合の規則

-args コマンドラインオプションを使用して、例によってプロパティを定義するには次の規則に従います。

cell 配列内の要素の順序は、基本関数シグネチャ内での入力の出現順に対応していなければなりません。たとえば、cell 配列内の最初の要素は、最初の基本関数入力のプロパティを定義します。
MATLAB 関数内で発生する引数よりも少ない数の引数を生成するには、生成された関数で使用する引数の数に対してのみプロパティを指定します。
MATLAB 関数に入力引数がある場合、入力引数をもたない関数を生成するには、空の cell 配列を -args に渡します。
クラスが固定小数点 (fi) である基本関数入力ごとに、入力の numerictype と fimath プロパティを指定します。
クラスが struct である基本関数入力ごとに、その各フィールドのプロパティを、構造体定義内での出現順に指定します。

コマンドラインでの例による基本入力のプロパティの指定

2 つの入力を追加する MATLAB 関数を考えてみます。

function y = mcf(u,v)
%#codegen
y = u + v;

次の例では、コマンドラインで例によって基本入力 u と v で異なるプロパティを指定する方法を示します。

定数のリテラル cell 配列を使用して、両方の入力が実数スカラーの double であるように指定します。
```
codegen mcf -args {0,0}
```
定数のリテラル cell 配列を使用して、入力 u が符号なしの 16 ビットの 1 行 4 列のベクトル、入力 v がスカラーの double であるように指定します。
```
codegen  mcf -args {zeros(1,4,'uint16'),0}
```
サンプル値を cell 配列変数に代入し、両方の入力が実数で符号なし 8 ビットの整数ベクトルであるように指定します。
```
a = uint8([1;2;3;4])
b = uint8([5;6;7;8])
ex = {a,b}
codegen mcf -args ex
```

コマンドラインでの例による基本固定小数点入力のプロパティの指定

固定小数点 MATLAB コードの MEX 関数または C/C++ コードを生成するには、Fixed-Point Designer™ ソフトウェアをインストールしなければなりません。

固定小数点数の平方根を計算する MATLAB 関数を考えてみます。

%#codegen
function y = sqrtfi(x)
y = sqrt(x);

例によって基本固定小数点入力 x のプロパティを指定するには、以下の手順に従います。

次の例のように、x の numerictype プロパティを定義します。

T = numerictype('WordLength',32,...
                'FractionLength',23,...
                'Signed',true);

次の例のように、x の fimath プロパティを定義します。

F = fimath('SumMode','SpecifyPrecision',...
           'SumWordLength',32,...
           'SumFractionLength',23,...
           'ProductMode','SpecifyPrecision',...
           'ProductWordLength',32,...
           'ProductFractionLength',23);

次の例のように、先ほど定義した numerictype と fimath プロパティをもつ固定小数点変数を作成します。
```
myeg = { fi(4.0,T,F) };
```
次の例のように、codegen コマンドを使用して、変数 myeg を -args オプションの引数として渡して、関数 sqrtfi をコンパイルします。
```
codegen sqrtfi -args myeg;
```

コマンドラインでの定数入力の指定

基本入力が実行時に変化しないことがわかっている場合、基本入力を定数値として指定することで、生成されたコードのオーバーヘッドを削減できます。定数入力は、通常、アルゴリズムの実行方法を制御するフラグや、データのサイズや型を指定する値に使用されます。

入力に定数を指定するには、-args コマンドラインオプションを coder.Constant オブジェクトと共に使用します。入力に constant_input のサイズ、クラス、実数/複素数および値をもつ定数を指定するには、以下の構文を使用します。

-args {coder.Constant(constant_input)}

定数入力をもつ関数の呼び出し

コードジェネレーターでは、生成されるコードに関数への定数入力がコンパイルされます。生成された C または C++ コードでは、関数シグネチャに定数入力は含まれません。既定では、MEX 関数のシグネチャに定数入力を含めます。MEX 関数を呼び出す場合、コンパイル時の値と一致する値を指定しなければなりません。MEX 関数のシグネチャに定数入力が含まれているかどうかや、定数入力に指定する値を MEX 関数がチェックするかどうかを制御できます。MEX 関数での定数入力のチェックを参照してください。

定数入力として構造体を指定

次のように、MATLAB ワークスペースに構造体 tmp を定義することで行列の次元を指定するとします。

tmp = struct('rows', 2, 'cols', 3);

次の MATLAB 関数 rowcol は、構造体入力 p を受け取って行列 y を定義します。

function y = rowcol(u,p) %#codegen
y = zeros(p.rows,p.cols) + u;

次の例は、基本入力 u が double スカラー変数で、基本入力 p が定数構造体であることを指定する方法を示しています。

codegen rowcol -args {0,coder.Constant(tmp)}

コマンドラインでの可変サイズ入力の指定

可変サイズデータは実行時にサイズが変わる可能性のあるデータです。MATLAB では、コード生成に対して制限付きと制限なしの可変サイズデータがサポートされています。"制限付き可変サイズデータ" には上限が設定されています。このデータはスタックで静的に割り当てることも、ヒープで動的に割り当てることもできます。"制限なしの可変サイズデータ" には上限が設定されていません。このデータはヒープで割り当てなければなりません。-args オプションと関数 coder.typeof を使用すると、入力が 1 つ以上の可変サイズの次元をもつように定義し、その上限を指定できます。

-args {coder.typeof(example_value, size_vector, variable_dims)}

可変サイズ入力を次のように指定します。

example_value と同じクラスと実数/複素数
size_vector と同じサイズと上限
variable_dims によって指定された可変次元

動的メモリ割り当てが有効な場合は、コンパイル時に、上限が不明な次元のサイズベクトルで Inf を指定できます。

variable_dims がスカラーの場合は、次の例外を除き、すべての次元に適用されます。

次元が 1 または 0 の場合は、固定
次元が制限なしの場合は、常に可変サイズ

詳細は、「coder.typeof」および可変サイズデータのためのコード生成を参照してください。

可変サイズベクトル入力の指定

ベクトル A の各 n 要素の平均を計算し、ベクトル B に格納する関数を作成します。

function B = nway(A,n) %#codegen
% Compute average of every N elements of A and put them in B.

coder.extrinsic('error');
if ((mod(numel(A),n) == 0) && (n>=1 && n<=numel(A)))
    B = ones(1,numel(A)/n);
    k = 1;
    for i = 1 : numel(A)/n
         B(i) = mean(A(k + (0:n-1)));
         k = k + n;
    end
else
    B = zeros(1,0);
    error('n <= 0 or does not divide number of elements evenly');
end

最初の入力 A を double 値のベクトルとして指定します。最初の次元のサイズは固定ですが、2 番目の次元は上限 100 まで増やせます。2 番目の入力 n を double スカラーとして指定します。
```
codegen -report nway -args {coder.typeof(0,[1 100],1),1} 
```
また、この代わりに、coder.typeof の式を MATLAB 変数に代入し、この変数を -args に引数として渡すこともできます。
```
vareg = coder.typeof(0,[1 100],1)
codegen -report nway -args {vareg, 0}
```

入力の型の指定と `arguments` ブロック

関数の引数の検証 (arguments ブロック) を使用してエントリポイント関数の入力の型を指定することはサポートされていません。エントリポイント関数に入力引数を検証する arguments ブロックが含まれている場合も、基本入力のプロパティの定義方法に示す 3 つの方法のいずれかを使用して、それらの入力引数のプロパティを指定する必要があります。

生成コード内のエントリポイント関数の入力の既定値

arguments ブロックを使用すると、1 つ以上の位置入力引数の既定値を指定できます。引数の宣言で既定値を指定すると、関数呼び出しで値を渡さない場合に MATLAB で既定値を使用できるため、位置引数はオプションになります。codegen コマンドを使用してコードを生成する場合や fiaccel (Fixed-Point Designer) コマンドを使用して固定小数点コードを高速化する場合に、一定の既定値をもつ 1 つ以上のオプションの位置引数について、そのプロパティを指定しないように選択できます。このような場合、それらのオプションの引数の既定値が生成コードにハードコードされ、それらの引数は生成コードのインターフェイスに表示されません。例については、次の表を参照してください。

MATLAB コード	生成コード
function out = useDefaults_1(a,b,c) arguments a (1,1) double = 3 b (1,1) double = 5 c (1,1) double = 7 end out = a + b + c; end	`codegen` コマンド: codegen -config:lib -c useDefaults_1 -args {} -report 生成コード: double useDefaults_1(void) { return 15.0; }
function out = useDefaults_2(a,b,c) arguments a (1,1) double b (1,1) double = 5 c (1,1) double = 7 end out = a + b + c; end	`codegen` コマンド: codegen -config:lib -c useDefaults_2 -args 0 -report 生成コード: double useDefaults_2(double a) { return (a + 5.0) + 7.0; }
`codegen` コマンド: codegen -config:lib -c useDefaults_2 -args {0,0} -report 生成コード: double useDefaults_2(double a, double b) { return (a + b) + 7.0; }

MATLAB コード

生成コード

function out = useDefaults_1(a,b,c)
arguments
    a (1,1) double = 3
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen コマンド:

codegen -config:lib -c useDefaults_1 -args {} -report

生成コード:

double useDefaults_1(void)
{
  return 15.0;
}

function out = useDefaults_2(a,b,c)
arguments
    a (1,1) double
    b (1,1) double = 5
    c (1,1) double = 7
end
out = a + b + c;
end

codegen コマンド:

codegen -config:lib -c useDefaults_2 -args 0 -report

生成コード:

double useDefaults_2(double a)
{
  return (a + 5.0) + 7.0;
}

codegen コマンド:

codegen -config:lib -c useDefaults_2 -args {0,0} -report

生成コード:

double useDefaults_2(double a, double b)
{
  return (a + b) + 7.0;
}