Funções e tipos de invocação do kernel do RenderScript

Visão geral

A função rsForEvery() pode ser usada para invocar o kernel raiz de um script.

As outras funções são usadas para conseguir as características da invocação de um kernel em execução, como dimensões e índices atuais. Essas funções usam um rs_kernel_context como argumento.

Resumo

Tipos
rs_for_each_strategy_t (link em inglês) Ordem sugerida de processamento de células
rs_kernel Processar uma função do kernel
rs_kernel_context (em inglês) Processar um contexto de invocação do kernel
rs_script_call_t (em inglês) Informações de iteração da célula
Funções
rsForEvery (em inglês) Inicia um kernel
rsForEachInternal (em inglês) (API interna) Inicie um kernel no script atual (com o número do slot)
rsForEachWithOptions (em inglês) Inicia um kernel com opções
rsGetArray0. Índice na dimensão Array0 para o contexto do kernel especificado
rsGetArray1. Índice na dimensão Array1 para o contexto do kernel especificado
rsGetArray2. Índice na dimensão Array2 para o contexto do kernel especificado
rsGetArray3. Índice na dimensão Array3 para o contexto do kernel especificado
rsGetDimArray0. Tamanho da dimensão Array0 para o contexto do kernel especificado
rsGetDimArray1. Tamanho da dimensão Array1 para o contexto do kernel especificado
rsGetDimArray2. Tamanho da dimensão Array2 para o contexto do kernel especificado
rsGetDimArray3. Tamanho da dimensão Array3 para o contexto do kernel especificado
rsGetDimHasFaces Presença de mais de uma face para o contexto do kernel especificado
rsGetDimLod (em inglês) Número de níveis de detalhes para o contexto especificado do kernel
rsGetDimX (em inglês) Tamanho da dimensão X para o contexto do kernel especificado
rsGetDimY (em inglês) Tamanho da dimensão Y para o contexto do kernel especificado
rsGetDimZ (link em inglês) Tamanho da dimensão Z para o contexto do kernel especificado
rsGetFace (link em inglês) Coordenada da face para o contexto especificado do kernel
rsGetLod (em inglês) Índice na dimensão "Níveis de detalhes" para o contexto do kernel especificado

Tipos

rs_for_each_strategy_t : ordem sugerida de processamento de células

Um tipo enumerado com os seguintes valores:     

RS_FOR_EACH_STRATEGY_SERIAL = 0Prefira regiões de memória contíguas.
RS_FOR_EACH_STRATEGY_DONT_CARE = 1Nenhuma preferência.
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2Prefira o horário de verão.
RS_FOR_EACH_STRATEGY_TILE_small = 3Prefere o processamento de regiões retangulares pequenas.
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4Prefere processar regiões retangulares médias.
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5Prefere o processamento de regiões retangulares grandes.

Esse tipo é usado para sugerir como o kernel invocado precisa iterar nas células das alocações. Isso é apenas uma dica. As implementações podem não seguir a sugestão.

Essa especificação pode ajudar no comportamento de armazenamento em cache do kernel em execução, por exemplo, a localidade do cache quando o processamento é distribuído por vários núcleos.

rs_kernel : gerenciamento para uma função do kernel

Um typedef de: void*     Adicionado no nível 24 da API

Um tipo opaco para uma função definida com o atributo do kernel. Um valor desse tipo pode ser usado em uma chamada rsForEach para iniciar um kernel.

rs_kernel_context : processamento para um contexto de invocação do kernel

Um typedef de: const struct rs_kernel_context_t *     Adicionado na API de nível 23

O contexto do kernel contém características comuns das alocações que estão sendo iteradas, como dimensões. Também contém índices raramente usados da célula processada atualmente, como o índice Array0 ou o nível de detalhe atual.

É possível acessar o contexto do kernel adicionando um parâmetro especial chamado "context" do tipo rs_kernel_context à função do kernel. Consulte rsGetDimX() e rsGetArray0() para ver exemplos.

rs_script_call_t : informações de iteração de células

Uma estrutura com os seguintes campos:     

estratégia rs_for_each_strategy_tIgnorado no momento. No futuro, será sugerida estratégia de iteração de células.
uint32_t xStartÍndice inicial na dimensão X.
uint32_t xEndÍndice final (exclusivo) na dimensão X.
uint32_t yStartÍndice inicial na dimensão Y.
uint32_t yEndÍndice final (exclusivo) na dimensão Y.
uint32_t zStartÍndice inicial na dimensão Z.
uint32_t zEndÍndice final (exclusivo) na dimensão Z.
uint32_t matrizStartÍndice inicial na dimensão Array0.
uint32_t matrizEndÍndice final (exclusivo) na dimensão Array0.
uint32_t matriz1StartÍndice inicial na dimensão Array1.
uint32_t matriz1EndÍndice final (exclusivo) na dimensão Array1.
uint32_t matriz2StartÍndice inicial na dimensão Array2.
uint32_t matriz2EndÍndice final (exclusivo) na dimensão Array2.
uint32_t matriz3StartÍndice inicial na dimensão Array3.
uint32_t matriz3EndÍndice final (exclusivo) na dimensão Array3.

Essa estrutura é usada para fornecer informações de iteração para uma chamada rsForEvery. No momento, ele é usado para restringir o processamento a um subconjunto de células. Em versões futuras, ele também será usado para dar dicas sobre como iterar melhor nas células.

Os campos Início são inclusivos e os campos Fim são exclusivos. Por exemplo, para iterar nas células 4, 5, 6 e 7 na dimensão X, defina xStart como 4 e xEnd como 8.

Funções

rsForEvery : inicia um kernel

void rsForEvery(rs_kernel do kernel, ... ...); Adicionado no nível 24 da API.
void rsForEach(rs_script script, rs_allocation entrada, rs_allocation output); Nível 14 a 23 da API
void rsForEach(rs_script script, rs_allocation entrada, rs_allocation output, const void* usrData); Removido da API de nível 14 e mais recentes.
void rsForEach(rs_script script, rs_allocation entrada, rs_allocation output, const void* usrData, const rs_script_call_t* sc); Removido da API de nível 14 e mais recentes.
void rsForEach(rs_script script, rs_allocation entrada, rs_allocation output, const void* usrData, size_t usrDataLen); Nível 14 a 20 da API
void rsForEvery(rs_script script, rs_allocation entrada, rs_allocation output, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); Nível 14 a 20 da API
Parâmetros
roteiroScript a ser chamado.
inputAlocação de origem dos dados.
outputAlocação para gravar a data.
DadosDados definidos pelo usuário a serem transmitidos para o script. Pode ser NULL.
sc.Informações de controle extra usadas para selecionar uma sub-região da alocação a ser processada ou sugerir uma estratégia de caminhada. Pode ser NULL.
usrDataLenTamanho da estrutura userData. Ele será usado para executar uma cópia superficial dos dados, se necessário.
memóriaDesignador de função para uma função definida com o atributo do kernel.
Alocações de entrada e saída

Executa o kernel em zero ou mais alocações de entrada. Eles são transmitidos depois do argumento rs_kernel. Se o kernel especificado retornar um valor, uma alocação de saída precisará ser definida como o último argumento. Todas as alocações de entrada e a alocação de saída, se houver, precisam ter as mesmas dimensões.

Esta é uma função síncrona. Uma chamada para essa função só retorna depois que todo o trabalho é concluído em todas as células das alocações de entrada. Se a função do kernel retornar algum valor, a chamada aguardará até que todos os resultados tenham sido gravados na alocação de saída.

Até o nível 23 da API, o kernel é explicitamente especificado como o kernel chamado "root" no script especificado, e apenas uma única alocação de entrada pode ser usada. A partir do nível 24 da API, uma função arbitrária do kernel pode ser usada, conforme especificado pelo argumento do kernel. O argumento do script foi removido. O kernel precisa ser definido no script atual. Além disso, mais de uma entrada pode ser usada.

Por exemplo,
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 um kernel no script atual (com o número do slot)

void rsForEveryInternal(int slot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); Adicionado no nível 24 da API.
Parâmetros
horário
opções
hasOutputIndica se o kernel gera
numInputNúmero de alocações de entrada
alocaçõesAlocações de entrada e saída

API interna para iniciar um kernel.

rsForEveryWithOptions : inicia um kernel com opções

void rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ... ...); Adicionado no nível 24 da API.
Parâmetros
memóriaDesignador de função para uma função definida com o atributo do kernel.
opçõesOpções de inicialização
Alocações de entrada e saída

Inicia o kernel de maneira semelhante a rsForEvery. No entanto, em vez de processar todas as células na entrada, essa função processa apenas células no subespaço do espaço de índice especificado nas opções. Com o espaço de índice explicitamente especificado por opções, nenhuma alocação de entrada ou saída é necessária para uma inicialização do kernel usando essa API. Se as alocações forem transmitidas, elas precisarão corresponder ao número de argumentos e retornar o valor esperado pela função do kernel. A alocação de saída estará presente somente se o kernel tiver um valor de retorno não nulo.

Por exemplo,
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 na dimensão Array0 para o contexto do kernel especificado

uint32_t rsGetArray0(rs_kernel_context); Adicionado no nível 23 da API.

Retorna o índice na dimensão Array0 da célula que está sendo processada, conforme especificado pelo contexto do kernel fornecido.

O contexto do kernel contém características comuns das alocações que estão sendo iteradas e índices raramente usados, como o índice Array0.

Você pode acessar o contexto do kernel adicionando um parâmetro especial chamado "context" do tipo rs_kernel_context à função do kernel. Por exemplo:
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);
  //...
}

Essa função retornará 0 se a dimensão Array0 não estiver presente.

rsGetArray1 : índice na dimensão Array1 para o contexto do kernel especificado

uint32_t rsGetArray1(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o índice na dimensão Array1 da célula que está sendo processada, conforme especificado pelo contexto do kernel fornecido. Consulte rsGetArray0() para uma explicação do contexto.

Retorna 0 se a dimensão Array1 não estiver presente.

rsGetArray2 : índice na dimensão Array2 para o contexto do kernel especificado

uint32_t rsGetArray2(rs_kernel_context contexto); Adicionado no nível 23 da API.

Retorna o índice na dimensão Array2 da célula que está sendo processada, conforme especificado pelo contexto do kernel fornecido. Consulte rsGetArray0() para uma explicação do contexto.

Retorna 0 se a dimensão Array2 não estiver presente.

rsGetArray3 : índice na dimensão Array3 para o contexto do kernel especificado

uint32_t rsGetArray3(rs_kernel_context); Adicionado no nível 23 da API.

Retorna o índice na dimensão Array3 da célula que está sendo processada, conforme especificado pelo contexto do kernel fornecido. Consulte rsGetArray0() para uma explicação do contexto.

Retorna 0 se a dimensão Array3 não estiver presente.

rsGetDimArray0 : tamanho da dimensão Array0 para o contexto do kernel especificado

uint32_t rsGetDimArray0(rs_kernel_context contexto); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão Array0 para o contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Array0 não estiver presente.

rsGetDimArray1 : tamanho da dimensão Array1 para o contexto do kernel especificado

uint32_t rsGetDimArray1(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão Array1 para o contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Array1 não estiver presente.

rsGetDimArray2 : tamanho da dimensão Array2 para o contexto do kernel especificado

uint32_t rsGetDimArray2(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão Array2 para o contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Array2 não estiver presente.

rsGetDimArray3 : tamanho da dimensão Array3 para o contexto do kernel especificado

uint32_t rsGetDimArray3(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão Array3 para o contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Array3 não estiver presente.

rsGetDimHasFaces : presença de mais de um rosto no contexto especificado do kernel

bool rsGetDimHasFaces(contexto rs_kernel_context); Adicionado no nível 23 da API.
Returns
Retorna verdadeiro se mais de um rosto estiver presente. Caso contrário, retorna falso.

Se o kernel estiver iterando em um cubemap, essa função retornará "true" se houver mais de uma face presente. Em todos os outros casos, ele retorna "false". Consulte rsGetDimX() para uma explicação do contexto.

rsAllocationGetDimFaces() é semelhante, mas retorna 0 ou 1 em vez de um booleano.

rsGetDimLod : número de níveis de detalhes para o contexto do kernel especificado

uint32_t rsGetDimLod(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o número de níveis de detalhes para o contexto do kernel especificado. Isso é útil para mipmaps. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se o Nível de detalhamento não for usado.

rsAllocationGetDimLOD() é semelhante, mas retorna 0 ou 1, em vez do número real de níveis.

rsGetDimX : tamanho da dimensão X para o contexto do kernel especificado

uint32_t rsGetDimX(rs_kernel_context context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão X do contexto do kernel especificado.

O contexto do kernel contém características comuns das alocações que estão sendo iteradas e índices raramente usados, como o índice Array0.

Para acessá-lo, adicione um parâmetro especial chamado "context" do tipo rs_kernel_context à função do kernel. Por exemplo:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

Para ver a dimensão de uma alocação específica, use rsAllocationGetDimX().

rsGetDimY : tamanho da dimensão Y para o contexto do kernel especificado

uint32_t rsGetDimY(rs_kernel_context context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão X do contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Y não estiver presente.

Para ver a dimensão de uma alocação específica, use rsAllocationGetDimY().

rsGetDimZ : tamanho da dimensão Z para o contexto do kernel especificado

uint32_t rsGetDimZ(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o tamanho da dimensão Z para o contexto do kernel especificado. Consulte rsGetDimX() para uma explicação do contexto.

Retorna 0 se a dimensão Z não estiver presente.

Para ver a dimensão de uma alocação específica, use rsAllocationGetDimZ().

rsGetFace : coordenada da face para o contexto do kernel especificado

Retorna a face em que a célula que está sendo processada é encontrada, conforme especificado pelo contexto do kernel fornecido. Consulte rsGetArray0() para uma explicação do contexto.

Retorna RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X se a dimensão do rosto não estiver presente.

rsGetLod : índice na dimensão "Níveis de detalhes" para o contexto do kernel especificado

uint32_t rsGetLod(contexto rs_kernel_context); Adicionado no nível 23 da API.

Retorna o índice na dimensão "Níveis de detalhes" da célula que está sendo processada, conforme especificado pelo contexto do kernel fornecido. Consulte rsGetArray0() para uma explicação do contexto.

Retorna 0 se a dimensão "Níveis de detalhe" não estiver presente.