Przegląd
Funkcja rsForEach() może służyć do wywołania głównego jądra skryptu.
Pozostałe funkcje służą do sprawdzania właściwości wywołania wykonywanego jądra, np. wymiarów i bieżących indeksów. Funkcje te przyjmują argument rs_kernel_context.
Podsumowanie
| Rodzaje | |
|---|---|
| rs_for_each_strategy_t | Sugerowana kolejność przetwarzania komórek |
| rs_kernel | Uchwyć do funkcji jądra |
| rs_kernel_context | Uchwyt do kontekstu wywołania jądra |
| rs_script_call_t | Informacje o iteracji komórki |
| Funkcje | |
|---|---|
| rsForEach | Uruchamia jądro |
| rsForEachInternal | (Wewnętrzny interfejs API) Uruchamianie jądra w bieżącym skrypcie (z numerem przedziału) |
| rsForEachWithOptions | Uruchamia jądro z opcjami |
| rsGetTrack0 | Indeks w wymiarze tablica0 dla określonego kontekstu jądra |
| rsGetSlate1 | Indeks w wymiarze tablica1 dla określonego kontekstu jądra |
| rsGetTrack2 | Indeks w wymiarze Tablica2 dla określonego kontekstu jądra |
| rsGetTrack3 | Indeks w wymiarze Array3 dla określonego kontekstu jądra |
| rsGetDimTrack0 | Rozmiar wymiaru tablica0 dla określonego kontekstu jądra |
| rsGetDimSlate1 | Rozmiar wymiaru tablica1 dla określonego kontekstu jądra |
| rsGetDimSlate2 | Rozmiar wymiaru tablica2 dla określonego kontekstu jądra |
| rsGetDimSlate3 | Rozmiar wymiaru Array3 dla określonego kontekstu jądra |
| rsGetDimHasFaces | Obecność więcej niż jednej twarzy w określonym kontekście jądra |
| rsGetDimLod | Liczba poziomów szczegółowości dla określonego kontekstu jądra |
| rsGetDimX | Rozmiar wymiaru X dla określonego kontekstu jądra |
| rsGetDimY | Rozmiar wymiaru Y dla określonego kontekstu jądra |
| rsGetDimZ | Rozmiar wymiaru Z dla określonego kontekstu jądra |
| rsGetFace | Współrzędne twarzy dla określonego kontekstu jądra |
| rsGetLod | Indeks w wymiarze Poziomy szczegółów dla określonego kontekstu jądra |
Rodzaje
rs_for_each_strategy_t : sugerowana kolejność przetwarzania komórek
enum z tymi wartościami:
| RS_FOR_EACH_STRATEGY_SERIAL = 0 | Preferuj przylegające regiony pamięci. |
|---|---|
| RS_FOR_EACH_STRATEGY_DONT_CARE = 1 | Brak uprzedzeń. |
| RS_FOR_EACH_STRATEGY_DST_LINEAR = 2 | Wolę czas letni. |
| RS_FOR_EACH_STRATEGY_TILE_SMALL = 3 | Preferuj przetwarzanie małych prostokątnych regionów. |
| RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4 | Preferuj przetwarzanie średnich prostokątnych regionów. |
| RS_FOR_EACH_STRATEGY_TILE_LARGE = 5 | Preferuj przetwarzanie dużych prostokątnych regionów. |
Ten typ służy do sugerowania sposobu, w jaki wywoływane jądro powtarza się na komórkach alokacji. To tylko podpowiedź. Implementacje mogą nie być zgodne z sugestią.
Ta specyfikacja może pomóc w zachowaniu buforowania w działającym jądrze, np. w lokalizacji pamięci podręcznej, gdy przetwarzanie jest rozłożone na wiele rdzeni.
rs_kernel : obsługa funkcji jądra
Element typedef: void* Dodano w poziomie interfejsu API 24.
Typ nieprzezroczysty dla funkcji zdefiniowanej za pomocą atrybutu jądra. Wartości tego typu można użyć w wywołaniu rsForEach, aby uruchomić jądro.
rs_kernel_context : obsługa kontekstu wywołania jądra
Element typedef: const struct rs_kernel_context_t * Dodano w poziomie interfejsu API 23
Kontekst jądra zawiera typowe cechy powtarzanych przydziałów, np. wymiary. Zawiera też rzadko używane indeksy obecnie przetwarzanej komórki, takie jak indeks tablica0 lub bieżący poziom szczegółowości.
Aby uzyskać dostęp do kontekstu jądra, dodaj do funkcji jądra specjalny parametr o nazwie „context” typu rs_kernel_context. Przykłady znajdziesz w sekcjach rsGetDimX() i rsGetArray0().
rs_script_call_t : informacje o iteracji komórki
strukturę z tymi polami:
| strategia rs_for_each_strategy_t | Obecnie ignorowane. W przyszłości pojawi się sugerowana strategia iteracji komórek. |
|---|---|
| uint32_t xStart | Indeks początkowy w wymiarze X. |
| uint32_t xEnd | Indeks końcowy (wyłącznie) w wymiarze X. |
| uint32_t yStart | Indeks początkowy w wymiarze Y. |
| uint32_t yEnd | Indeks końcowy (wyłącznie) w wymiarze Y. |
| uint32_t zStart | Indeks początkowy w wymiarze Z. |
| uint32_t zEnd | Indeks końcowy (wyłącznie) w wymiarze Z. |
| uint32_t Początek tablicy | Indeks początkowy w wymiarze tablica0. |
| uint32_t tableEnd | Indeks końcowy (wyłącznie) w wymiarze Tablica0. |
| uint32_t tablica1Start | Indeks początkowy w wymiarze tablica1. |
| uint32_t tablica1End | Indeks końcowy (wyłącznie) w wymiarze Tablica1. |
| uint32_t tablica2Start | Indeks początkowy w wymiarze tablica2. |
| uint32_t tablica2End | Indeks końcowy (wyłącznie) w wymiarze Tablica2. |
| uint32_t tablica3Start | Indeks początkowy w wymiarze Array3. |
| uint32_t tablica3End | Indeks końcowy (wyłącznie) w wymiarze Tablica3. |
Ta struktura służy do dostarczania informacji o iteracji do wywołania rsForEach. Obecnie używa się go do ograniczania przetwarzania do podzbioru komórek. W przyszłych wersjach będzie on też służyć jako wskazówka co do tego, jak najlepiej wykonać iterację w komórkach.
Pola „Początek” uwzględniają zarówno te pola, jak i końcowe. Aby np. iterować komórki 4, 5, 6 i 7 w wymiarze X, jako xStart ustaw wartość 4, a xEnd na 8.
Funkcje
rsForEach : uruchamia jądro
| void rsForEach(kernel rs_kernel, ... ...); | Dodano do poziomu interfejsu API 24. |
| void rsForEach(skrypt rs_script, dane wejściowe rs_allocation, dane wyjściowe rs_allocation); | Poziom API 14–23 |
| void rsForEach(skrypt rs_script, dane wejściowe rs_allocation, dane wyjściowe rs_allocation, const void* usrData); | Usunięto z interfejsu API na poziomie 14 lub wyższym. |
| void rsForEach(skrypt rs_script, dane wejściowe rs_allocation, dane wyjściowe rs_allocation, const void* usrData, const rs_script_call_t* sc); | Usunięto z interfejsu API na poziomie 14 lub wyższym. |
| void rsForEach(skrypt rs_script, dane wejściowe rs_allocation, dane wyjściowe rs_allocation, const void* usrData, size_t usrDataLen); | Poziom API 14–20 |
| void rsForEach(skrypt rs_script, dane wejściowe rs_allocation, dane wyjściowe rs_allocation, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); | Poziom API 14–20 |
Parametry
| skrypt | Skrypt do wywołania. |
|---|---|
| wejście | Przydział do danych źródłowych. |
| output | Przydział zapisu daty. |
| dane usrData | Dane zdefiniowane przez użytkownika, które mają zostać przekazane do skryptu. Może zawierać wartość NULL. |
| sc | Informacje dodatkowe używane do wyboru podregionu przydziału do przetworzenia lub zaproponowania strategii dotyczącej spacerów. Może zawierać wartość NULL. |
| usrDataLen | Rozmiar struktury userData. W razie potrzeby będzie to umożliwiało utworzenie niewielkiej kopii danych. |
| jądro | Oznaczenie funkcji dla funkcji zdefiniowanej za pomocą atrybutu jądra. |
| … | Przydziały danych wejściowych i wyjściowych |
Uruchamia jądro przy zerowym lub większej liczbie przydziałów wejściowych. Są one przekazywane po argumencie rs_kernel. Jeśli określone jądro zwraca wartość, przydział danych wyjściowych musi być określony jako ostatni argument. Wszystkie przydziały wejściowe i przydział danych wyjściowych (jeśli istnieje) muszą mieć te same wymiary.
Jest to funkcja synchroniczna. Wywołanie tej funkcji zwraca się dopiero po zakończeniu pracy dotyczącej wszystkich komórek alokacji wejściowych. Jeśli funkcja jądra zwraca dowolną wartość, wywołanie czeka, aż wszystkie wyniki zostaną zapisane w alokacji wyjściowej.
Do poziomu interfejsu API 23 jądro jest domyślnie określone jako jądro o nazwie „root” w określonym skrypcie i może być używany tylko jeden przydział danych wejściowych. Od poziomu interfejsu API 24 można używać dowolnej funkcji jądra, zgodnie z wartością argumentu jądra. Argument skryptu zostanie usunięty. Jądro musi być zdefiniowane w bieżącym skrypcie. Można też użyć więcej niż 1 danych wejściowych.
Na przykład:
float __attribute__((kernel)) square(float a) {
return a * a;
}
void compute(rs_allocation ain, rs_allocation aout) {
rsForEach(square, ain, aout);
}
rsForEachInternal : (wewnętrzny interfejs API) uruchom jądro w bieżącym skrypcie (z użyciem numeru przedziału)
| void rsForEachInternal(int slot, rs_script_call_t* options, int hasoutput, int numInputs, rs_allocation* allocs); | Dodano do poziomu interfejsu API 24. |
Parametry
| przedział czasu | |
|---|---|
| Opcje | |
| hasoutput | Wskazuje, czy jądro generuje dane wyjściowe |
| Liczba wejść | Liczba przydziałów danych wejściowych |
| przydzielanie | Przydziały danych wejściowych i wyjściowych |
Wewnętrzny interfejs API umożliwiający uruchomienie jądra.
rsForEachWithOptions : uruchamia jądro z opcjami
| void rsForEachWithOptions(jądro rs_kernel, opcje rs_script_call_t*, ... ...); | Dodano do poziomu interfejsu API 24. |
Parametry
| jądro | Oznaczenie funkcji dla funkcji zdefiniowanej za pomocą atrybutu jądra. |
|---|---|
| Opcje | Opcje uruchamiania |
| … | Przydziały danych wejściowych i wyjściowych |
Uruchamia jądro w sposób podobny do rsForEach. Jednak zamiast przetwarzania wszystkich komórek w danych wejściowych ta funkcja przetwarza tylko komórki znajdujące się w podprzestrzeni przestrzeni indeksu określonej w opcjach. W przypadku przestrzeni indeksu wyraźnie określonej przez opcje do uruchomienia jądra za pomocą tego interfejsu API nie są wymagane żadne przydziały danych wejściowych ani wyjściowych. Jeśli alokacje są przekazywane, muszą być zgodne z liczbą argumentów i wartością oczekiwaną przez funkcję jądra. Przydział wyjściowy jest widoczny tylko wtedy, gdy jądro zawiera niepustą wartość zwracaną.
Na przykład:
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 : indeks w wymiarze Array0 dla określonego kontekstu jądra
| uint32_t rsGetTrack0(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca indeks w wymiarze tablica0 przetwarzanej komórki, zgodnie z podanym kontekstem jądra.
Kontekst jądra zawiera typowe cechy powtarzanych przydziałów i rzadko używane indeksy, takie jak indeks Array0.
Aby uzyskać dostęp do kontekstu jądra, dodaj do funkcji jądra specjalny parametr o nazwie „context” typu rs_kernel_context. Np.
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);
//...
}
Jeśli nie ma wymiaru Tablica0, ta funkcja zwraca wartość 0.
rsGetArray1 : indeks w wymiarze Array1 dla określonego kontekstu jądra
| uint32_t rsGetArray1(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca indeks w wymiarze tablica1 przetwarzanej komórki, zgodnie z podanym kontekstem jądra. Aby dowiedzieć się więcej o kontekście, zobacz funkcję rsGetArray0().
Zwraca wartość 0, jeśli nie ma wymiaru tablica1.
rsGetArray2 : indeks w wymiarze tablica2 dla określonego kontekstu jądra
| uint32_t rsGetArray2(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca indeks w wymiarze tablicy2 przetwarzanej komórki, zgodnie z podanym kontekstem jądra. Aby dowiedzieć się więcej o kontekście, zapoznaj się z funkcją rsGetArray0().
Zwraca wartość 0, jeśli nie ma wymiaru Tablica2.
rsGetArray3 : indeks w wymiarze Array3 dla określonego kontekstu jądra
| uint32_t rsGetArray3(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca indeks w wymiarze tablica3 przetwarzanej komórki, zgodnie z podanym kontekstem jądra. Aby dowiedzieć się więcej o kontekście, zobacz funkcję rsGetArray0().
Zwraca wartość 0, jeśli nie ma wymiaru Array3.
rsGetDimArray0 : rozmiar wymiaru Array0 dla określonego kontekstu jądra
| uint32_t rsGetDimTrack0(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru tablica0 dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru tablica0.
rsGetDimArray1 : rozmiar wymiaru Array1 dla określonego kontekstu jądra
| uint32_t rsGetDimArray1(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru tablica1 dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru tablica1.
rsGetDimArray2 : rozmiar wymiaru Array2 dla określonego kontekstu jądra
| uint32_t rsGetDimArray2(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru Tablica2 dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru Tablica2.
rsGetDimArray3 : rozmiar wymiaru Array3 dla określonego kontekstu jądra
| uint32_t rsGetDimArray3(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru Array3 dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru Array3.
rsGetDimHasFaces : obecność więcej niż 1 twarzy w określonym kontekście jądra
| bool rsGetDimHasFaces(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwroty
| Zwraca wartość „true”, jeśli występuje więcej niż jedna twarz. W przeciwnym razie zwraca wartość „false”. |
Jeśli jądro iteruje się na mapie sześcianu, funkcja zwraca wartość „prawda”, jeśli występuje więcej niż 1 twarz. W pozostałych przypadkach zwraca wartość „fałsz”. Objaśnienie kontekstu znajdziesz w sekcji rsGetDimX().
Funkcja rsAllocationGetDimFaces() jest podobna, ale zwraca 0 lub 1 zamiast wartości logicznej.
rsGetDimLod : liczba poziomów szczegółowości dla określonego kontekstu jądra
| uint32_t rsGetDimLod(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca liczbę poziomów szczegółów dla określonego kontekstu jądra. Jest to przydatne w przypadku mipmap. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie użyto parametru Poziom szczegółowości.
Funkcja rsAllocationGetDimLOD() jest podobna, ale zwraca rzeczywistą liczbę poziomów 0 lub 1.
rsGetDimX : rozmiar wymiaru X dla określonego kontekstu jądra
| uint32_t rsGetDimX(rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru X dla określonego kontekstu jądra.
Kontekst jądra zawiera typowe cechy powtarzanych przydziałów i rzadko używane indeksy, takie jak indeks Array0.
Aby uzyskać do niego dostęp, dodaj do funkcji jądra specjalny parametr o nazwie „context” typu rs_kernel_context. Np.
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
uint32_t size = rsGetDimX(context); //...
Aby uzyskać wymiar określonego przydziału, użyj funkcji rsAllocationGetDimX().
rsGetDimY : rozmiar wymiaru Y dla określonego kontekstu jądra
| uint32_t rsGetDimY(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru X dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru Y.
Aby uzyskać wymiar określonego przydziału, użyj funkcji rsAllocationGetDimY().
rsGetDimZ : rozmiar wymiaru Z dla określonego kontekstu jądra
| uint32_t rsGetDimZ(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca rozmiar wymiaru Z dla określonego kontekstu jądra. Aby poznać kontekst, zobacz funkcję rsGetDimX().
Zwraca wartość 0, jeśli nie ma wymiaru Z.
Aby uzyskać wymiar określonego przydziału, użyj funkcji rsAllocationGetDimZ().
rsGetFace : współrzędne twarzy w określonym kontekście jądra
| rs_allocation_cubemap_face rsGetFace(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca twarz, na której znajduje się przetwarzana komórka, zgodnie z podanym kontekstem jądra. Aby dowiedzieć się więcej o kontekście, zobacz funkcję rsGetArray0().
Jeśli wymiar twarzy nie jest podany, zwraca wartość RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X.
rsGetLod : indeks w wymiarze Poziomy szczegółów dla określonego kontekstu jądra.
| uint32_t rsGetLod(kontekst rs_kernel_context); | Dodano do poziomu interfejsu API 23. |
Zwraca indeks w wymiarze Poziomy szczegółów przetwarzanej komórki, zgodnie z podanym kontekstem jądra. Informacje o kontekście znajdziesz w opisie funkcji rsGetArray0().
Zwraca wartość 0, jeśli brakuje wymiaru Poziomy szczegółowości.