RenderScript カーネル呼び出し関数と型

概要

rsForEach() 関数を使用して、スクリプトのルートカーネルを呼び出すことができます。

他の関数は、ディメンションや現在のインデックスなど、実行中のカーネルの呼び出しの特性を取得するために使用されます。これらの関数は、引数として rs_kernel_context を取ります。

まとめ

rs_for_each_strategy_t セルの処理順序の候補
rs_kernel カーネル関数に対するハンドル
rs_kernel_context カーネル呼び出しコンテキストに対するハンドル
rs_script_call_t セルの反復処理に関する情報
関数
rsForEach カーネルを起動する
rsForEachInternal (内部 API)現在のスクリプトで(スロット番号を指定して)カーネルを起動する
rsForEachWithOptions オプションを指定してカーネルを起動する
rsGetArray0 指定されたカーネル コンテキストの Array0 ディメンションのインデックス
rsGetArray1 指定されたカーネル コンテキストの Array1 ディメンションのインデックス
rsGetArray2 指定されたカーネル コンテキストの Array2 ディメンションのインデックス
rsGetArray3 指定されたカーネル コンテキストの Array3 ディメンションのインデックス
rsGetDimArray0 指定されたカーネル コンテキストの Array0 ディメンションのサイズ
rsGetDimArray1 指定されたカーネル コンテキストの Array1 ディメンションのサイズ
rsGetDimArray2 指定されたカーネル コンテキストの Array2 ディメンションのサイズ
rsGetDimArray3 指定されたカーネル コンテキストの Array3 ディメンションのサイズ
rsGetDimHasFaces 指定されたカーネル コンテキストに複数の顔が存在する
rsGetDimLod 指定されたカーネル コンテキストの詳細レベル数
rsGetDimX 指定されたカーネル コンテキストの X ディメンションのサイズ
rsGetDimY 指定されたカーネル コンテキストの Y ディメンションのサイズ
rsGetDimZ 指定されたカーネル コンテキストの Z ディメンションのサイズ
rsGetFace 指定されたカーネル コンテキストの顔の座標
rsGetLod 指定されたカーネル コンテキストの詳細レベル ディメンションのインデックス

rs_for_each_strategy_t : 推奨されるセル処理順序

次の値を持つ列挙型:

RS_FOR_EACH_STRATEGY_SERIAL = 0連続したメモリ領域を優先します。
RS_FOR_EACH_STRATEGY_DONT_CARE = 1設定は不要。
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2DST を優先します。
RS_FOR_EACH_STRATEGY_TILE_SMALL = 3小さい長方形の領域の処理を優先します。
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4処理対象となる中程度の長方形の領域を優先します。
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5大きい長方形領域の処理を優先します。

この型は、呼び出されたカーネルが割り当てのセルを反復する方法を提案するために使用されます。これは単なるヒントです。実装が提案どおりに機能しない場合があります。

この仕様は、実行中のカーネルのキャッシュ動作に役立ちます。たとえば、処理が複数のコアに分散された場合のキャッシュの局所性です。

rs_kernel : カーネル関数に対するハンドル

void*     の typedef。API レベル 24 で追加されました。

kernel 属性で定義された関数の不透明型。この型の値は、カーネルを起動するための rsForEach 呼び出しで使用できます。

rs_kernel_context : カーネル呼び出しコンテキストへのハンドル

typedef: const struct rs_kernel_context_t *     API レベル 23 で追加

カーネル コンテキストには、ディメンションなど、反復される割り当てに共通の特性が含まれます。また、Array0 インデックスや現在の詳細レベルなど、現在処理されているセルのめったに使用されていないインデックスも含まれます。

カーネル コンテキストにアクセスするには、rs_kernel_context タイプの context という特別なパラメータをカーネル関数に追加します。例については、rsGetDimX() と rsGetArray0() をご覧ください。

rs_script_call_t : セルの反復処理に関する情報

次のフィールドを持つ構造:     

rs_for_each_strategy_t 戦略現在無視されています。将来的には、セルの反復処理戦略が提案される予定です。
uint32_t xStartX ディメンションの開始インデックス。
uint32_t xEndX ディメンションの終了インデックス(排他的)。
uint32_t yStartY ディメンションの開始インデックス。
uint32_t yEndY ディメンションの終了インデックス(排他的)。
uint32_t zStartZ ディメンションの開始インデックス。
uint32_t zEndZ ディメンションの終了インデックス(排他的)。
uint32_t arrayStartArray0 ディメンションの開始インデックス。
uint32_t arrayEndArray0 ディメンションの終了インデックス(排他的)。
uint32_t array1StartArray1 ディメンションの開始インデックス。
uint32_t 配列 1EndArray1 ディメンションの終了インデックス(排他的)。
uint32_t array2StartArray2 ディメンションの開始インデックス。
uint32_t array2EndArray2 ディメンションの終了インデックス(排他的)。
uint32_t array3StartArray3 ディメンションの開始インデックス。
uint32_t 配列 3EndArray3 ディメンションの終了インデックス(排他的)。

この構造体は、rsForEach 呼び出しに反復情報を提供するために使われます。現在、このパラメータは、処理をセルのサブセットに制限するために使用されています。今後のバージョンでは、セルを反復処理するためのヒントを提供するのにも使用されます。

[開始] フィールドは包括的であり、[終了] フィールドは含まれません。たとえば、X ディメンションのセル 4、5、6、7 を反復処理するには、xStart を 4 に、xEnd を 8 に設定します。

関数

rsForEach : カーネルを起動します

void rsForEach(rs_kernel kernel, ... ...); API レベル 24 で追加されました
void rsForEach(rs_script script, rs_allocation 入力, rs_allocation output); API レベル 14 ~ 23
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData); API レベル 14 以降から削除
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, const rs_script_call_t* sc); API レベル 14 以降から削除
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen); API レベル 14 ~ 20
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); API レベル 14 ~ 20
パラメータ
スクリプト呼び出すスクリプト。
inputソースデータへの割り当て。
output日付を書き込む割り当て。
usr データスクリプトに渡すユーザー定義のデータ。NULL でもかまいません。
sc処理する割り当てのサブリージョンの選択や、ウォーキング戦略の提案に使用される追加のコントロール情報。NULL でもかまいません。
usr データ LenuserData 構造のサイズ。これは、必要に応じてデータのシャローコピーを実行するために使用されます。
カーネルカーネル属性で定義された関数を指す関数指定子。
入力と出力の割り当て

ゼロ個以上の入力割り当てでカーネルを実行します。これらは rs_kernel 引数の後に渡されます。指定されたカーネルが値を返す場合、出力割り当てを最後の引数として指定する必要があります。すべての入力割り当てと出力割り当て(存在する場合)は、同じディメンションでなければなりません。

これは同期関数です。この関数の呼び出しは、入力割り当てのすべてのセルに対するすべての処理が完了した後にのみ戻ります。カーネル関数が任意の値を返した場合、すべての結果が出力割り当てに書き込まれるまで待機します。

API レベル 23 までは、カーネルは、指定されたスクリプトで「root」という名前のカーネルとして暗黙的に指定され、単一の入力割り当てしか使用できません。API レベル 24 以降では、kernel 引数で指定されたように、任意のカーネル関数を使用できます。スクリプト引数が削除されました。 カーネルは現在のスクリプトで定義する必要があります。また、複数の入力を使用できます。

例:
float __attribute__((kernel)) square(float a) {
  return a * a;
}

void compute(rs_allocation ain, rs_allocation aout) {
  rsForEach(square, ain, aout);
}

rsForEachInternal : (内部 API)現在のスクリプトでカーネルを起動します(スロット番号を指定して)。

void rsForEachInternal(int slot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); API レベル 24 で追加されました
パラメータ
時間枠
オプション
hasOutputカーネルが出力を生成するかどうかを示します。
numInputs入力割り当て数
割り当て入力と出力の割り当て

カーネルを起動するための内部 API。

rsForEachWithOptions : オプションを指定してカーネルを起動します

void rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ... ...); API レベル 24 で追加されました
パラメータ
カーネルカーネル属性で定義された関数を指す関数指定子。
オプション起動オプション
入力と出力の割り当て

rsForEach と同様の方法でカーネルを起動します。ただし、この関数は入力内のすべてのセルを処理するのではなく、オプションで指定されたインデックス空間のサブスペース内のセルのみを処理します。オプションによってインデックス空間が明示的に指定されている場合、この API を使用してカーネルを起動するときに、入力または出力の割り当てを行う必要はありません。割り当てを渡す場合は、カーネル関数が期待する引数の数と戻り値と一致させる必要があります。出力割り当ては、カーネルに void 以外の戻り値がある場合にのみ存在します。

例:
rs_script_call_t opts = {0};
opts.xStart = 0;
opts.xEnd = dimX;
opts.yStart = 0;
opts.yEnd = dimY / 2;
rsForEachWithOptions(foo, &opts, out, out);

rsGetArray0 : 指定されたカーネル コンテキストの Array0 ディメンション内のインデックス

uint32_t rsGetArray0(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストで指定されたとおりに、処理されるセルの Array0 ディメンションのインデックスを返します。

カーネル コンテキストには、反復される割り当てに共通する特性と、ほとんど使用されていないインデックス(Array0 インデックスなど)が含まれます。

カーネル コンテキストにアクセスするには、rs_kernel_context タイプの context という特別なパラメータをカーネル関数に追加します。例:
short RS_KERNEL myKernel(short value, uint32_t x, rs_kernel_context context) {
  // The current index in the common x, y, z dimensions are accessed by
  // adding these variables as arguments. For the more rarely used indices
  // to the other dimensions, extract them from the kernel context:
  uint32_t index_a0 = rsGetArray0(context);
  //...
}

Array0 ディメンションが存在しない場合、この関数は 0 を返します。

rsGetArray1 : 指定されたカーネル コンテキストの Array1 ディメンション内のインデックス

uint32_t rsGetArray1(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストで指定された、処理されるセルの Array1 ディメンションのインデックスを返します。コンテキストについては、rsGetArray0() をご覧ください。

Array1 ディメンションが存在しない場合は 0 を返します。

rsGetArray2 : 指定されたカーネル コンテキストの Array2 ディメンション内のインデックス

uint32_t rsGetArray2(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストで指定されたとおりに、処理されるセルの Array2 ディメンションのインデックスを返します。コンテキストについては、rsGetArray0() をご覧ください。

Array2 ディメンションが存在しない場合は 0 を返します。

rsGetArray3 : 指定されたカーネル コンテキストの Array3 ディメンション内のインデックス

uint32_t rsGetArray3(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストで指定された、処理されるセルの Array3 ディメンションのインデックスを返します。コンテキストについては、rsGetArray0() をご覧ください。

Array3 ディメンションが存在しない場合は 0 を返します。

rsGetDimArray0 : 指定されたカーネル コンテキストの Array0 ディメンションのサイズ

uint32_t rsGetDimArray0(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの Array0 ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Array0 ディメンションが存在しない場合は 0 を返します。

rsGetDimArray1 : 指定されたカーネル コンテキストの Array1 ディメンションのサイズ

uint32_t rsGetDimArray1(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの Array1 ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Array1 ディメンションが存在しない場合は 0 を返します。

rsGetDimArray2 : 指定されたカーネル コンテキストの Array2 ディメンションのサイズ

uint32_t rsGetDimArray2(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの Array2 ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Array2 ディメンションが存在しない場合は 0 を返します。

rsGetDimArray3 : 指定されたカーネル コンテキストの Array3 ディメンションのサイズ

uint32_t rsGetDimArray3(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの Array3 ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Array3 ディメンションが存在しない場合は 0 を返します。

rsGetDimHasFaces : 指定されたカーネル コンテキストに複数の顔が存在する

bool rsGetDimHasFaces(rs_kernel_context context); API レベル 23 で追加されました
戻り値
複数の顔がある場合は true を、そうでない場合は false を返します。

カーネルがキューブマップに対して反復処理を行っている場合、複数の顔が存在する場合、この関数は true を返します。それ以外の場合は false を返します。コンテキストの説明については、rsGetDimX() をご覧ください。

rsAllocationGetDimFaces() も同様ですが、ブール値ではなく 0 または 1 を返します。

rsGetDimLod : 指定されたカーネル コンテキストの詳細レベル数

uint32_t rsGetDimLod(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの詳細レベル数を返します。これは mipmap で役立ちます。このコンテキストについては、rsGetDimX() をご覧ください。

詳細レベルを使用しない場合は 0 を返します。

rsAllocationGetDimLOD() も同様ですが、代わりに実際のレベル数の代わりに 0 または 1 を返します。

rsGetDimX : 指定されたカーネル コンテキストの X ディメンションのサイズ

uint32_t rsGetDimX(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの X ディメンションのサイズを返します。

カーネル コンテキストには、反復される割り当てに共通する特性と、ほとんど使用されていないインデックス(Array0 インデックスなど)が含まれます。

このツールにアクセスするには、カーネル関数に rs_kernel_context タイプの「context」という特別なパラメータを追加します。例:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

特定の割り当てのディメンションを取得するには、rsAllocationGetDimX() を使用します。

rsGetDimY : 指定されたカーネル コンテキストの Y ディメンションのサイズ

uint32_t rsGetDimY(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの X ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Y ディメンションが存在しない場合は 0 を返します。

特定の割り当てのディメンションを取得するには、rsAllocationGetDimY() を使用します。

rsGetDimZ : 指定されたカーネル コンテキストの Z ディメンションのサイズ

uint32_t rsGetDimZ(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの Z ディメンションのサイズを返します。 このコンテキストについては、rsGetDimX() をご覧ください。

Z ディメンションが存在しない場合は 0 を返します。

特定の割り当てのディメンションを取得するには、rsAllocationGetDimZ() を使用します。

rsGetFace : 指定されたカーネル コンテキストの顔の座標

rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストの指定に従って、処理対象のセルが見つかった面を返します。コンテキストについては、rsGetArray0() をご覧ください。

顔のディメンションが存在しない場合は、RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X を返します。

rsGetLod : 指定されたカーネル コンテキストの詳細レベル ディメンションのインデックス

uint32_t rsGetLod(rs_kernel_context context); API レベル 23 で追加されました

指定されたカーネル コンテキストで指定されたとおりに、処理されるセルの詳細レベル ディメンションのインデックスを返します。このコンテキストについては、rsGetArray0() をご覧ください。

詳細レベル ディメンションが存在しない場合は 0 を返します。