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 = 0 | Prefira regiões de memória contíguas. |
|---|---|
| RS_FOR_EACH_STRATEGY_DONT_CARE = 1 | Nenhuma preferência. |
| RS_FOR_EACH_STRATEGY_DST_LINEAR = 2 | Prefira o horário de verão. |
| RS_FOR_EACH_STRATEGY_TILE_small = 3 | Prefere o processamento de regiões retangulares pequenas. |
| RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4 | Prefere processar regiões retangulares médias. |
| RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 | Prefere 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_t | Ignorado 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
| roteiro | Script a ser chamado. |
|---|---|
| input | Alocação de origem dos dados. |
| output | Alocação para gravar a data. |
| Dados | Dados 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. |
| usrDataLen | Tamanho da estrutura userData. Ele será usado para executar uma cópia superficial dos dados, se necessário. |
| memória | Designador 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 | |
| hasOutput | Indica se o kernel gera |
| numInput | Número de alocações de entrada |
| alocações | Alocaçõ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ória | Designador de função para uma função definida com o atributo do kernel. |
|---|---|
| opções | Opçõ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
| rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); | Adicionado no nível 23 da API. |
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.