Tipos y funciones de invocación del kernel de RenderScript

Descripción general

La función rsForEach() se puede usar para invocar el kernel raíz de una secuencia de comandos.

Las otras funciones se usan para obtener las características de la invocación de un kernel en ejecución, como las dimensiones y los índices actuales. Estas funciones toman un rs_kernel_context como argumento.

Resumen

Tipos
rs_for_each_strategy_t Orden de procesamiento de celda sugerido
rs_kernel Cómo controlar una función de kernel
rs_kernel_context Controla el contexto de invocación de un kernel
rs_script_call_t, Información de iteración de celdas
Funciones
rsForEach Inicia un kernel.
rsForEachInternal (API interna) Inicia un kernel en la secuencia de comandos actual (con el número de ranura)
rsForEachWithOptions Inicia un kernel con opciones.
rsGetArray0 Índice en la dimensión Array0 para el contexto de kernel especificado
rsGetArray1 Índice en la dimensión Array1 para el contexto de kernel especificado
rsGetArray2 Índice en la dimensión Array2 para el contexto de kernel especificado
rsGetArray3 Índice en la dimensión Array3 para el contexto de kernel especificado
rsGetDimArray0 Tamaño de la dimensión Array0 para el contexto de kernel especificado
rsGetDimArray1 Tamaño de la dimensión Array1 para el contexto de kernel especificado
rsGetDimArray2 Tamaño de la dimensión Array2 para el contexto de kernel especificado
rsGetDimArray3 Tamaño de la dimensión Array3 para el contexto de kernel especificado
rsGetDimHasFaces Presencia de más de una cara para el contexto de kernel especificado
rsGetDimLod Cantidad de niveles de detalle para el contexto de kernel especificado
rsGetDimX Tamaño de la dimensión X para el contexto de kernel especificado
rsGetDimY Tamaño de la dimensión Y para el contexto de kernel especificado
rsGetDimZ Tamaño de la dimensión Z para el contexto de kernel especificado
rsGetFace Coordenada de la cara para el contexto del kernel especificado
rsGetLod Índice en la dimensión Niveles de detalle para el contexto de kernel especificado

Tipos

rs_for_each_strategy_t : Orden sugerido de procesamiento de celdas

Una enumeración con los siguientes valores:     

RS_FOR_EACH_STRATEGY_SERIAL = 0Opta por regiones de memoria contiguas.
RS_FOR_EACH_STRATEGY_DONT_CARE = 1Sin preferencias.
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2Preferir horario de verano
RS_FOR_EACH_STRATEGY_TILE_SMALL = 3Prefiere procesar regiones rectangulares pequeñas.
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4Prefiere procesar regiones rectangulares medianas.
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5Prefiere procesar regiones rectangulares grandes.

Este tipo se usa para sugerir cómo el kernel invocado debe iterar sobre las celdas de las asignaciones. Esta es solo una pista. Es posible que las implementaciones no sigan la sugerencia.

Esta especificación puede ayudar con el comportamiento del almacenamiento en caché del kernel en ejecución, p.ej., la localidad de la caché cuando el procesamiento se distribuye en varios núcleos.

rs_kernel : Control a una función de kernel

Se agregó un typedef de: void*     Se agregó en el nivel de API 24.

Es un tipo opaco para una función que se define con el atributo del kernel. Se puede usar un valor de este tipo en una llamada rsForEach para iniciar un kernel.

rs_kernel_context : Control de un contexto de invocación de kernel

A typedef de: const struct rs_kernel_context_t *     Se agregó en el nivel de API 23

El contexto del kernel contiene características comunes de las asignaciones sobre las que se itera, como las dimensiones. Además, contiene índices de uso poco frecuente de la celda procesada en este momento, como el índice Array0 o el nivel de detalle actual.

Para acceder al contexto del kernel, agrega un parámetro especial llamado "context" del tipo rs_kernel_context a la función del kernel. Consulta rsGetDimX() y rsGetArray0() para ver ejemplos.

rs_script_call_t : Información de iteración de celdas

Una estructura con los siguientes campos:     

estrategia rs_for_each_strategy_tIgnorada actualmente. En el futuro, se sugerirá la estrategia de iteración de celdas.
uint32_t xStartÍndice inicial en la dimensión X.
uint32_t xFinÍndice final (exclusivo) en la dimensión X.
uint32_t yComenzarÍndice inicial en la dimensión Y.
uint32_t yFinalizarÍndice final (exclusivo) en la dimensión Y.
uint32_t zStartÍndice inicial en la dimensión Z.
uint32_t zEndÍndice final (exclusivo) en la dimensión Z.
uint32_t arrayStartÍndice inicial en la dimensión Array0.
uint32_t arrayEndÍndice final (exclusivo) en la dimensión Array0.
uint32_t array1InicioÍndice inicial en la dimensión Array1.
uint32_t array1EndÍndice final (exclusivo) en la dimensión Array1.
uint32_t array2InicioÍndice inicial en la dimensión Array2.
uint32_t array2EndÍndice final (exclusivo) en la dimensión Array2.
uint32_t array3InicioÍndice inicial en la dimensión Array3.
uint32_t array3EndÍndice final (exclusivo) en la dimensión Array3.

Esta estructura se usa para proporcionar información de iteración a una llamada rsForEach. Actualmente, se usa para restringir el procesamiento a un subconjunto de celdas. En versiones futuras, también se usará para proporcionar sugerencias sobre cómo iterar mejor en las celdas.

Los campos Start son inclusivos, mientras que los campos End son exclusivos. P.ej., para iterar en las celdas 4, 5, 6 y 7 en la dimensión X, establece xStart en 4 y xEnd en 8.

Funciones

rsForEach : Inicia un kernel

void rsForEach(rs_kernel, kernel, ... ...); Se agregó en el nivel de API 24.
void rsForEach(rs_script, entrada rs_allocation, salida rs_allocation); Nivel de API 14 a 23
void rsForEach(rs_script script, entrada rs_allocation, salida rs_allocation, const void* usrData); Se quitó del nivel de API 14 y versiones posteriores.
void rsForEach(rs_script script, entrada rs_allocation, salida rs_allocation, const void* usrData, const rs_script_call_t* sc); Se quitó del nivel de API 14 y versiones posteriores.
void rsForEach(rs_script script, entrada rs_allocation, salida rs_allocation, const void* usrData, size_t usrDataLen); Nivel de API 14 a 20
void rsForEach(rs_script script, entrada rs_allocation, entrada rs_allocation, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); Nivel de API 14 a 20
Parámetros
secuencia de comandosGuion para la llamada.
inputAsignación desde la que provienen los datos de origen.
outputAsignación en la que se escribe la fecha.
Datos de usuarioDatos definidos por el usuario para pasar a la secuencia de comandos. Puede ser NULL.
scInformación de control adicional que se usa para seleccionar una subregión de la asignación que se procesará o para sugerir una estrategia de caminata. Puede ser NULL.
usrDataLenTamaño de la estructura userData. Esto se usará para realizar una copia superficial de los datos si es necesario.
memoriaEl designador de función es una función que se define con el atributo del kernel.
Asignaciones de entrada y salida

Ejecuta el kernel en cero o más asignaciones de entrada. Se pasan después del argumento rs_kernel. Si el kernel especificado muestra un valor, se debe especificar una asignación de salida como el último argumento. Todas las asignaciones de entrada, y la asignación de salida (si existe), deben tener las mismas dimensiones.

Esta es una función síncrona. Una llamada a esta función solo se muestra después de que se haya completado todo el trabajo para todas las celdas de las asignaciones de entrada. Si la función del kernel muestra algún valor, la llamada espera hasta que se escriban todos los resultados en la asignación de salida.

Hasta el nivel de API 23, el kernel se especifica implícitamente como el kernel llamado "root" en la secuencia de comandos especificada, y solo se puede usar una asignación de entrada. A partir del nivel de API 24, se puede usar una función de kernel arbitraria, según lo especificado por el argumento del kernel. Se quita el argumento de la secuencia de comandos. El kernel debe definirse en la secuencia de comandos actual. Además, se puede usar más de una entrada.

P.ej.,
float __attribute__((kernel)) square(float a) {
  return a * a;
}

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

rsForEachInternal : (API interna) Inicia un kernel en la secuencia de comandos actual (con el número de ranura)

void rsForEachInternal(int slot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); Se agregó en el nivel de API 24.
Parámetros
horario disponible
Opciones
hasOutputIndica si el kernel genera resultados.
numInputsCantidad de asignaciones de entrada
asignarAsignaciones de entrada y salida

API interna para iniciar un kernel

rsForEachWithOptions : Inicia un kernel con opciones.

void rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* opciones, ... ...); Se agregó en el nivel de API 24.
Parámetros
memoriaEl designador de función es una función que se define con el atributo del kernel.
OpcionesOpciones de lanzamiento
Asignaciones de entrada y salida

Inicia el kernel de manera similar a rsForEach. Sin embargo, en lugar de procesar todas las celdas en la entrada, esta función solo procesa las celdas en el subespacio del espacio de índice especificado en las opciones. Con el espacio de índice especificado de forma explícita por las opciones, no se requiere ninguna asignación de entrada o salida para un lanzamiento de kernel con esta API. Si se pasan asignaciones, deben coincidir con la cantidad de argumentos y el valor que espera la función del kernel. La asignación de salida solo está presente si el kernel tiene un valor de retorno no vacío.

P.ej.,
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 : Índice en la dimensión Array0 para el contexto de kernel especificado.

uint32_t rsGetArray0(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el índice en la dimensión Array0 de la celda que se procesa, como lo especifica el contexto de kernel proporcionado.

El contexto del kernel contiene características comunes de las asignaciones que se repiten y los índices que se usan con muy poca frecuencia, como el índice Array0.

Para acceder al contexto del kernel, agrega un parámetro especial llamado "context" del tipo rs_kernel_context a la función del kernel. P.ej.,
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);
  //...
}

Esta función muestra 0 si la dimensión Array0 no está presente.

rsGetArray1 : Índice en la dimensión Array1 para el contexto de kernel especificado.

uint32_t rsGetArray1(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el índice en la dimensión Array1 de la celda que se procesa, como lo especifica el contexto de kernel proporcionado. Consulta rsGetArray0() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array1 no está presente.

rsGetArray2 : Índice en la dimensión Array2 para el contexto de kernel especificado.

uint32_t rsGetArray2(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el índice en la dimensión Array2 de la celda que se procesa, según lo especificado en el contexto de kernel proporcionado. Consulta rsGetArray0() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array2 no está presente.

rsGetArray3 : Índice en la dimensión Array3 para el contexto de kernel especificado.

uint32_t rsGetArray3(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el índice en la dimensión Array3 de la celda que se procesa, como lo especifica el contexto de kernel proporcionado. Consulta rsGetArray0() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array3 no está presente.

rsGetDimArray0 : Es el tamaño de la dimensión Array0 para el contexto de kernel especificado.

uint32_t rsGetDimArray0(rs_kernel_context context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión Array0 para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array0 no está presente.

rsGetDimArray1 : Es el tamaño de la dimensión Array1 para el contexto de kernel especificado.

uint32_t rsGetDimArray1(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión Array1 para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array1 no está presente.

rsGetDimArray2 : Es el tamaño de la dimensión Array2 para el contexto de kernel especificado.

uint32_t rsGetDimArray2(rs_kernel_context context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión Array2 para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array2 no está presente.

rsGetDimArray3 : Es el tamaño de la dimensión Array3 para el contexto de kernel especificado.

uint32_t rsGetDimArray3(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión Array3 para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Array3 no está presente.

rsGetDimHasFaces : presencia de más de una cara para el contexto de kernel especificado

bool rsGetDimHasFaces(rs_kernel_context context); Se agregó en el nivel de API 23.
Devoluciones
Muestra true si hay más de un rostro presente; de lo contrario, muestra false.

Si el kernel itera en un cubemap, esta función muestra "true" si hay más de un rostro presente. En todos los demás casos, el resultado es falso. Consulta rsGetDimX() para obtener una explicación del contexto.

rsAllocationGetDimFaces() es similar, pero muestra 0 o 1 en lugar de un bool.

rsGetDimLod : cantidad de niveles de detalle para el contexto de kernel especificado

uint32_t rsGetDimLod(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra la cantidad de niveles de detalle para el contexto de kernel especificado. Esto es útil para mipmaps. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si no se usa Level of Detail.

rsAllocationGetDimLOD() es similar, pero muestra 0 o 1 en lugar de la cantidad real de niveles.

rsGetDimX : tamaño de la dimensión X para el contexto de kernel especificado

uint32_t rsGetDimX(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión X para el contexto de kernel especificado.

El contexto del kernel contiene características comunes de las asignaciones que se repiten y los índices que se usan con muy poca frecuencia, como el índice Array0.

Para acceder, agrega un parámetro especial llamado "context" del tipo rs_kernel_context a la función de tu kernel. P.ej.,
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

Para obtener la dimensión de la asignación específica, usa rsAllocationGetDimX().

rsGetDimY : Es el tamaño de la dimensión Y para el contexto de kernel especificado.

uint32_t rsGetDimY(rs_kernel_context context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión X para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Y no está presente.

Para obtener la dimensión de una asignación específica, usa rsAllocationGetDimY().

rsGetDimZ : tamaño de la dimensión Z para el contexto de kernel especificado

uint32_t rsGetDimZ(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el tamaño de la dimensión Z para el contexto de kernel especificado. Consulta rsGetDimX() para obtener una explicación del contexto.

Muestra 0 si la dimensión Z no está presente.

Para obtener la dimensión de la asignación específica, usa rsAllocationGetDimZ().

rsGetFace : Coordenada de la cara para el contexto del kernel especificado

rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); Se agregó en el nivel de API 23.

Muestra el rostro en el que se encuentra la celda que se procesa, según lo especificado en el contexto de kernel proporcionado. Consulta rsGetArray0() para obtener una explicación del contexto.

Muestra RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X si la dimensión del rostro no está presente.

rsGetLod : Índice en la dimensión Niveles de detalle para el contexto de kernel especificado

uint32_t rsGetLod(contexto rs_kernel_context); Se agregó en el nivel de API 23.

Muestra el índice en la dimensión Niveles de detalle de la celda que se procesa, según lo especificado en el contexto de kernel proporcionado. Consulta rsGetArray0() para obtener una explicación del contexto.

Muestra 0 si la dimensión Niveles de detalle no está presente.