總覽
rsForEach() 函式可用來叫用指令碼的根核心。
其他函式可用於取得叫用執行中的核心的特性，例如維度和目前的索引。這些函式會將 rs_kernel_context 做為引數使用。
摘要
| 類型 | |
|---|---|
| rs_for_each_strategy_t | 建議的儲存格處理順序 |
| rs_kernel | 核心函式處理 |
| rs_kernel_context | 處理核心叫用結構定義 |
| rs_script_call_t | 儲存格疊代資訊 |
| 函式 | |
|---|---|
| rsForEvery | 啟動核心 |
| rsForEveryInternal | (內部 API) 在目前的指令碼中啟動核心 (包含運算單元編號) |
| rsForEveryWithOptions | 使用選項啟動核心 |
| 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 | 指定核心結構定義的 Face 座標 |
| 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 = 2 | 偏好使用 DST。 |
| RS_FOR_EACH_STRATEGY_TILE_SMALL = 3 | 偏好處理小型矩形區域。 |
| RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4 | 偏好處理中矩形區域。 |
| RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 | 偏好處理大矩形區域。 |
這個類型可用來建議叫用的核心應如何疊代配置儲存格。這只是提示。可能未採用建議。
這項規格有助於對執行中的核心的快取行為提供協助，例如：將處理分散至多個核心時的快取位置。
rs_kernel ：處理核心函式
已在 API 級別 24 中新增 typedef*。
使用核心屬性定義的函式不透明類型。此類型的值可以在 rsForEvery 呼叫中使用，以啟動核心。
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 xStart | 開始在 X 維度中的索引。 |
| uint32_t xEnd | X 維度的結束索引 (不含)。 |
| uint32_t yStart | 開始於 Y 維度中的索引。 |
| uint32_t yEnd | Y 維度中的結束索引 (不含)。 |
| uint32_t zStart | 開始在 Z 維度中建立索引。 |
| uint32_t zEnd | Z 維度的結尾索引 (不含)。 |
| uint32_tArrayStart | 從 Array0 維度開始索引。 |
| uint32_t 陣列 End | Array0 維度的結尾索引 (不含)。 |
| uint32_t 陣列 1 開始 | 從 Array1 維度開始索引。 |
| uint32_t 陣列 1End | Array1 維度的結尾索引 (不含)。 |
| uint32_t 陣列 2 開始 | 從 Array2 維度開始索引。 |
| uint32_t 陣列 2End | Array2 維度的結尾索引 (不含)。 |
| uint32_t 陣列 3 開始 | 在 Array3 維度中開始索引。 |
| uint32_t 陣列 3End | Array3 維度的結尾索引 (不含)。 |
這個結構是用來向 rsForEvery 呼叫提供疊代資訊。目前僅用於限定部分儲存格的處理程序。在日後的版本中，這也會用來提示如何有效進行儲存格疊代。
「Start」欄位會納入「Start」欄位，「End」欄位則不包含「End」欄位。舉例來說，如要疊代 X 維度中的 4、5、6 和 7 儲存格，請將 xStart 設為 4，並將 xEnd 設為 8。
函式
rsForEvery ：啟動核心
| void rsForEvery(rs_kernel核心, ... ...); | 已在 API 級別 24 中新增。 |
| void rsForEvery(rs_script 指令碼、rs_allocation 輸入內容、rs_allocation 輸出)； | API 級別 14 - 23 |
| void rsForEvery(rs_script 指令碼、rs_allocation 輸入、rs_allocation 輸出、 const void* usrData); | 已從 API 級別 14 以上移除 |
| void rsForEvery(rs_script 指令碼, rs_allocation 輸入, rs_allocation 輸出, const void* usrData, const rs_script_call_t* sc); | 已從 API 級別 14 以上移除 |
| void rsForEvery(rs_script 指令碼、rs_allocation 輸入、rs_allocation 輸出、 const void* usrData、size_t usrDataLen); | API 級別 14 - 20 |
| void rsForEvery(rs_script 指令碼, rs_allocation 輸入, rs_allocation 輸出, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); | API 級別 14 - 20 |
參數
| 指令碼 | 要呼叫的指令碼。 |
|---|---|
| 輸入 | 分配到來源資料的來源。 |
| output | 要寫入日期的分配。 |
| usrData | 要傳送至指令碼的使用者定義資料。可以是空值。 |
| sc | 額外的控制資訊，用於選取要處理的分配作業子區域，或建議步行策略。可以是空值。 |
| usrDataLen | userData 結構的大小。這將用於視需要執行淺層資料副本。 |
| 核心 | 使用核心屬性定義的函式的函式設計器。 |
| ... | 輸入和輸出分配 |
以零或多個輸入分配方式執行核心。這些函式會在 rs_kernel 引數後方傳遞。如果指定的核心傳回值，則須將輸出分配指定為最後一個引數。所有輸入配置和輸出分配 (如有) 都必須具有相同的維度。
這是一個同步函式。只有在所有輸入分配儲存格完成工作後，系統才會傳回此函式的呼叫。如果核心函式傳回任何值，呼叫會等到所有結果寫入輸出分配為止。
在 API 級別 23 以下的指定指令碼中，系統會以隱含方式將核心指定為名為「root」的核心，而且只能使用單一輸入分配。從 API 級別 24 開始，您可以按照核心引數指定的方式使用任意核心函式。已移除指令碼引數。您必須在目前的指令碼中定義核心。此外，您也可以使用多個輸入。
例如：
float __attribute__((kernel)) square(float a) {
return a * a;
}
void compute(rs_allocation ain, rs_allocation aout) {
rsForEach(square, ain, aout);
}
rsForEveryInternal ：(Internal API) 在目前的指令碼中啟動核心 (附上運算單元編號)
| void rsForEveryInternal(intSlot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); | 已在 API 級別 24 中新增。 |
參數
| 時段 | |
|---|---|
| 選項 | |
| 有輸出內容 | 指出核心是否產生輸出內容 |
| numInputs | 輸入分配數量 |
| 分配 | 輸入和輸出分配 |
用來啟動核心的內部 API。
rsForEveryWithOptions ：透過選項啟動核心
| void rsForEveryWithOptions(rs_kernel核心, rs_script_call_t* 選項, ... ...); | 已在 API 級別 24 中新增。 |
參數
| 核心 | 使用核心屬性定義的函式的函式設計器。 |
|---|---|
| 選項 | 啟動選項 |
| ... | 輸入和輸出分配 |
以類似 rsForEach 的方式啟動核心。但是，這個函式只會處理選項中指定的索引空間子空間中的儲存格，而非處理輸入中的所有儲存格。有了選項明確指定的索引空間後，使用這個 API 啟動核心時就不需要輸入或輸出分配。如果傳入配置，這些配置必須與核心函式預期的引數數量和回傳值相符。只有在核心具有非空值回傳值時，才會顯示輸出分配情形。
例如：
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 索引。
您可以藉由在核心函式中新增名為「context」的 rs_kernel_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。