Các loại và hàm gọi hạt nhân RenderScript

Tổng quan

Bạn có thể dùng hàm rsForEach() để gọi hạt nhân gốc của một tập lệnh.

Các hàm khác dùng để lấy đặc điểm của lệnh gọi một hạt nhân thực thi, chẳng hạn như kích thước và chỉ mục hiện tại. Các hàm này lấy rs_kernel_context làm đối số.

Tóm tắt

Loại
rs_for_each_strategy_t Thứ tự xử lý ô được đề xuất
rs_kernel Xử lý một hàm hạt nhân
rs_kernel_context Xử lý ngữ cảnh gọi nhân hệ điều hành
rs_script_call_t Thông tin lặp lại của ô
Hàm
rsForEach Khởi chạy một hạt nhân
rsForEachInternal (API nội bộ) Khởi chạy một hạt nhân trong Tập lệnh hiện tại (với số vùng)
rsForEachWithOptions Khởi chạy hạt nhân với các tuỳ chọn
rsGetArray0 Chỉ mục trong phương diện Array0 cho ngữ cảnh hạt nhân được chỉ định
rsGetArray1 Chỉ mục trong phương diện Array1 cho ngữ cảnh hạt nhân được chỉ định
rsGetArray2 Chỉ mục trong phương diện Array2 cho ngữ cảnh hạt nhân được chỉ định
rsGetArray3 Chỉ mục trong phương diện Array3 cho ngữ cảnh hạt nhân được chỉ định
rsGetDimArray0 Kích thước của phương diện Array0 cho ngữ cảnh hạt nhân được chỉ định
rsGetDimArray1 Kích thước của phương diện Array1 cho ngữ cảnh hạt nhân được chỉ định
rsGetDimArray2 Kích thước của phương diện Array2 cho ngữ cảnh hạt nhân được chỉ định
rsGetDimArray3 Kích thước của phương diện Array3 trong ngữ cảnh hạt nhân được chỉ định
rsGetDimHasFaces Sự hiện diện của nhiều khuôn mặt trong ngữ cảnh kernel đã chỉ định
rsGetDimLod Số lượng mức chi tiết cho ngữ cảnh hạt nhân được chỉ định
rsGetDimX Kích thước của phương diện X trong ngữ cảnh hạt nhân được chỉ định
rsGetDimY Kích thước của phương diện Y trong ngữ cảnh hạt nhân được chỉ định
rsGetDimZ Kích thước của phương diện Z cho ngữ cảnh hạt nhân được chỉ định
rsGetFace Toạ độ của Khuôn mặt cho ngữ cảnh hạt nhân được chỉ định
rsGetLod Chỉ mục trong phương diện Cấp chi tiết cho ngữ cảnh hạt nhân được chỉ định

Loại

rs_for_each_strategy_t : Thứ tự xử lý ô được đề xuất

Một enum có các giá trị sau:     

RS_FOR_EACH_STRATEGY_SERIAL = 0Ưu tiên các vùng bộ nhớ liền kề.
RS_FOR_EACH_STRATEGY_DONT_CARE = 1Không có lựa chọn ưu tiên nào.
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2Ưu tiên DST.
RS_FOR_EACH_STRATEGY_TILE_NHỎ = 3Ưu tiên xử lý các vùng hình chữ nhật nhỏ.
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4Ưu tiên xử lý các khu vực hình chữ nhật trung bình.
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5Ưu tiên xử lý các vùng hình chữ nhật lớn.

Loại này dùng để đề xuất cách hạt nhân được gọi nên lặp lại các ô của quá trình phân bổ. Đây chỉ là gợi ý. Quy trình triển khai có thể không tuân theo đề xuất.

Thông số kỹ thuật này có thể giúp ích cho hành vi lưu vào bộ nhớ đệm của hạt nhân đang chạy, chẳng hạn như vị trí bộ nhớ đệm khi quá trình xử lý được phân phối trên nhiều lõi.

rs_kernel : Xử lý một hàm hạt nhân

Một typedef của: void*     Đã thêm vào API cấp 24

Kiểu mờ cho một hàm được xác định bằng thuộc tính hạt nhân. Bạn có thể dùng giá trị thuộc loại này trong lệnh gọi rsForEach để khởi chạy một hạt nhân.

rs_kernel_context : Xử lý ngữ cảnh gọi nhân

Một typedef của: const struct rs_kernel_context_t *     Đã thêm vào API cấp 23

Ngữ cảnh hạt nhân chứa các đặc điểm chung của các lượt phân bổ được lặp lại, chẳng hạn như kích thước. Lớp này cũng chứa các chỉ mục hiếm khi được sử dụng của ô đang được xử lý, chẳng hạn như chỉ mục Array0 hoặc mức độ chi tiết hiện tại.

Bạn có thể truy cập ngữ cảnh hạt nhân bằng cách thêm một tham số đặc biệt có tên là "context" thuộc loại rs_kernel_context vào hàm hạt nhân. Hãy xem rsGetDimX() và rsGetArray0() để biết ví dụ.

rs_script_call_t : Thông tin lặp lại của ô

Cấu trúc có các trường sau đây:     

Chiến lược rs_for_each_strategy_tHiện bị bỏ qua. Trong tương lai, chiến lược lặp lại ô sẽ được đề xuất.
uint32_t xStartChỉ mục bắt đầu trong phương diện X.
uint32_t xEndChỉ mục kết thúc (độc quyền) trong phương diện X.
uint32_t yStartChỉ mục bắt đầu trong chiều Y.
uint32_t yEndChỉ mục kết thúc (độc quyền) trong phương diện Y.
uint32_t zStartChỉ mục bắt đầu trong phương diện Z.
uint32_t zEndChỉ mục kết thúc (độc quyền) trong phương diện Z.
mảng uint32_tChỉ mục bắt đầu trong thứ nguyên Array0.
mảng uint32_tKết thúcChỉ mục kết thúc (độc quyền) trong thứ nguyên Array0.
uint32_t mảng1Bắt đầuChỉ mục bắt đầu trong thứ nguyên Array1.
uint32_t mảng1Kết thúcChỉ mục kết thúc (độc quyền) trong phương diện Array1.
uint32_t mảng2Bắt đầuChỉ mục bắt đầu trong thứ nguyên Array2.
uint32_t mảng2Kết thúcChỉ mục kết thúc (độc quyền) trong phương diện Array2.
uint32_t mảng3Bắt đầuChỉ mục bắt đầu trong thứ nguyên Array3.
uint32_t mảng3Kết thúcChỉ mục kết thúc (độc quyền) trong phương diện Array3.

Cấu trúc này dùng để cung cấp thông tin lặp lại cho lệnh gọi rsForEach. Hàm này hiện được dùng để hạn chế xử lý cho một tập hợp con các ô. Trong các phiên bản trong tương lai, dữ liệu này cũng sẽ được dùng để cung cấp gợi ý về cách lặp lại các ô hiệu quả nhất.

Các trường Bắt đầu có giá trị bao gồm và các trường Kết thúc là không bao gồm. Ví dụ: để lặp lại các ô 4, 5, 6 và 7 trong chiều X, hãy đặt xStart thành 4 và xEnd thành 8.

Hàm

rsForEach : Khởi chạy một hạt nhân

void rsForEach(rs_kernel kernel, ... ...); Đã thêm vào API cấp 24
void rsForEach(tập lệnh rs_script, dữ liệu đầu vào rs_allocation, đầu ra rs_allocation); API cấp 14 – 23
void rsForEach(tập lệnh rs_script, đầu vào rs_allocation, đầu ra rs_allocation, const void* usrData); Đã xoá khỏi API cấp 14 trở lên
void rsForEach(tập lệnh rs_script, dữ liệu đầu vào rs_allocation, đầu ra rs_allocation, const void* usrData, const rs_script_call_t* sc); Đã xoá khỏi API cấp 14 trở lên
void rsForEach(tập lệnh rs_script, dữ liệu đầu vào rs_allocation, đầu ra của rs_allocation, const void* usrData, size_t usrDataLen); API cấp 14 – 20
void rsForEach(tập lệnh rs_script, dữ liệu đầu vào rs_allocation, đầu ra rs_allocation, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); API cấp 14 – 20
Tham số
tập lệnhTập lệnh để gọi.
inputViệc phân bổ cho nguồn dữ liệu.
outputPhân bổ cần ghi ngày vào.
Dữ liệu usrDữ liệu do người dùng xác định để truyền đến tập lệnh. Có thể là giá trị NULL.
scThông tin kiểm soát bổ sung dùng để chọn một khu vực phụ trong khu vực phân bổ sẽ được xử lý hoặc đề xuất chiến lược đi bộ. Có thể là giá trị NULL.
usrDatalenKích thước của cấu trúc userData. Công cụ này sẽ được dùng để sao chép ít dữ liệu hơn nếu cần.
nhân hệ điều hànhChỉ định hàm cho một hàm được xác định bằng thuộc tính hạt nhân.
...Phân bổ đầu vào và đầu ra

Chạy hạt nhân mà không có hoặc có nhiều lượt phân bổ đầu vào. Các đối số này được truyền sau đối số rs_kernel. Nếu hạt nhân được chỉ định trả về một giá trị, thì mức phân bổ đầu ra phải được chỉ định làm đối số cuối cùng. Tất cả các lượt phân bổ đầu vào và mức phân bổ đầu ra nếu có, phải có cùng phương diện.

Đây là hàm đồng bộ. Lệnh gọi đến hàm này chỉ trả về sau khi tất cả công việc đã hoàn tất cho tất cả các ô của lượt phân bổ đầu vào. Nếu hàm hạt nhân trả về giá trị bất kỳ, lệnh gọi sẽ chờ cho đến khi tất cả kết quả được ghi vào hoạt động phân bổ đầu ra.

Lên đến API cấp 23, hạt nhân được ngầm chỉ định là hạt nhân có tên "gốc" trong tập lệnh được chỉ định và chỉ có thể sử dụng một hoạt động phân bổ đầu vào. Kể từ API cấp 24, bạn có thể sử dụng một hàm hạt nhân tuỳ ý, như được chỉ định trong đối số hạt nhân. Xoá đối số tập lệnh. Hạt nhân phải được xác định trong tập lệnh hiện tại. Ngoài ra, bạn có thể sử dụng nhiều dữ liệu đầu vào.

Ví dụ:
float __attribute__((kernel)) square(float a) {
  return a * a;
}

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

rsForEachInternal : (API nội bộ) Khởi chạy một hạt nhân trong Tập lệnh hiện tại (với số vùng)

void rsForEachInternal(int khe, các lựa chọn rs_script_call_t*, int hasOutput, int numInputs, rs_allocation* allocs); Đã thêm vào API cấp 24
Tham số
khung giờ
tùy chọn
hasOutputCho biết nhân hệ điều hành có tạo đầu ra hay không
numInputSố lượt phân bổ đầu vào
phân bổPhân bổ đầu vào và đầu ra

API nội bộ để khởi chạy một nhân.

rsForEachWithOptions : Khởi chạy một hạt nhân với các tuỳ chọn

void rsForEachWithOptions(nhân rs_kernel, các lựa chọn rs_script_call_t*, ... ...); Đã thêm vào API cấp 24
Tham số
nhân hệ điều hànhChỉ định hàm cho một hàm được xác định bằng thuộc tính hạt nhân.
tùy chọnTuỳ chọn khởi chạy
...Phân bổ đầu vào và đầu ra

Khởi chạy hạt nhân theo cách tương tự như rsForEach. Tuy nhiên, thay vì xử lý tất cả ô trong dữ liệu đầu vào, hàm này chỉ xử lý các ô trong không gian con của không gian lập chỉ mục được chỉ định trong các tuỳ chọn. Với không gian lập chỉ mục được chỉ định rõ ràng theo các tuỳ chọn, bạn không cần phân bổ đầu vào hoặc đầu ra để khởi chạy hạt nhân bằng API này. Nếu các mức phân bổ được truyền vào, chúng phải khớp với số lượng đối số và giá trị trả về mà hàm hạt nhân dự kiến. Hoạt động phân bổ đầu ra xuất hiện khi và chỉ khi hạt nhân có giá trị trả về không trống.

Ví dụ:
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 : Chỉ mục trong chiều Array0 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetArray0(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về chỉ mục theo chiều Array0 của ô đang được xử lý, như được chỉ định bởi ngữ cảnh hạt nhân đã cung cấp.

Ngữ cảnh hạt nhân chứa các đặc điểm phổ biến của các lượt phân bổ đang được lặp lại và các chỉ mục ít được sử dụng, chẳng hạn như chỉ mục Array0.

Bạn có thể truy cập ngữ cảnh hạt nhân bằng cách thêm một tham số đặc biệt có tên là "context" thuộc loại rs_kernel_context vào hàm hạt nhân. Ví dụ:
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);
  //...
}

Hàm này trả về 0 nếu không có chiều Array0.

rsGetArray1 : Chỉ mục trong chiều Array1 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetArray1(Ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về chỉ mục theo chiều Array1 của ô đang được xử lý, như được chỉ định trong ngữ cảnh hạt nhân đã cung cấp. Vui lòng xem rsGetArray0() để biết nội dung giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array1.

rsGetArray2 : Chỉ mục trong chiều Array2 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetArray2(rs_kernel_context); Đã thêm vào API cấp 23

Trả về chỉ mục theo chiều Array2 của ô đang được xử lý, như được chỉ định bởi ngữ cảnh hạt nhân đã cung cấp. Vui lòng xem rsGetArray0() để biết nội dung giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array2.

rsGetArray3 : Chỉ mục trong chiều Array3 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetArray3(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về chỉ mục theo chiều Array3 của ô đang được xử lý, như được chỉ định bởi ngữ cảnh hạt nhân đã cung cấp. Vui lòng xem rsGetArray0() để biết nội dung giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array3.

rsGetDimArray0 : Kích thước của thứ nguyên Array0 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimArray0(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều Array0 cho ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array0.

rsGetDimArray1 : Kích thước của thứ nguyên Array1 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimArray1(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều Array1 cho ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array1.

rsGetDimArray2 : Kích thước của kích thước Array2 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimArray2(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều Array2 cho ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array2.

rsGetDimArray3 : Kích thước của thứ nguyên Array3 cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimArray3(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều Array3 cho ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Array3.

rsGetDimHasFaces : Sự hiện diện của nhiều khuôn mặt cho ngữ cảnh hạt nhân đã chỉ định

bool rsGetDimHasAres(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23
Giá trị trả về
Trả về true nếu có nhiều khuôn mặt, nếu không thì trả về false.

Nếu hạt nhân đang lặp lại trên một hình lập phương, hàm này sẽ trả về giá trị true nếu có nhiều hơn một khuôn mặt. Trong tất cả các trường hợp khác, giá trị trả về sẽ trả về false. Vui lòng xem rsGetDimX() để biết nội dung giải thích về ngữ cảnh này.

rsAllocationGetDimFaces() cũng tương tự nhưng trả về 0 hoặc 1 thay vì giá trị bool.

rsGetDimLod : Số cấp chi tiết cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimLod(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về số lượng mức chi tiết cho ngữ cảnh hạt nhân được chỉ định. Điều này rất hữu ích cho mipmap. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không sử dụng Cấp độ chi tiết.

rsAllocationGetDimLOD() cũng tương tự nhưng trả về 0 hoặc 1 số cấp thực tế.

rsGetDimX : Kích thước của chiều X cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimX(Ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều X đối với ngữ cảnh hạt nhân đã chỉ định.

Ngữ cảnh hạt nhân chứa các đặc điểm phổ biến của các lượt phân bổ đang được lặp lại và các chỉ mục ít được sử dụng, chẳng hạn như chỉ mục Array0.

Bạn có thể truy cập công cụ này bằng cách thêm một tham số đặc biệt có tên là "context" (ngữ cảnh) thuộc loại rs_kernel_context vào hàm kernel. Ví dụ:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

Để lấy phương diện của mức phân bổ cụ thể, hãy sử dụng rsAllocationGetDimX().

rsGetDimY : Kích thước của chiều Y cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimY(Ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều X đối với ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Y.

Để lấy phương diện của mức phân bổ cụ thể, hãy sử dụng rsAllocationGetDimY().

rsGetDimZ : Kích thước của chiều Z cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetDimZ(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về kích thước của chiều Z cho ngữ cảnh hạt nhân đã chỉ định. Vui lòng xem rsGetDimX() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có chiều Z.

Để lấy phương diện của mức phân bổ cụ thể, hãy sử dụng rsAllocationGetDimZ().

rsGetFace : Toạ độ của khuôn mặt cho ngữ cảnh hạt nhân đã chỉ định

rs_allocation_cumap_face rsGetFace(Ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về mặt tại đó ô đang được xử lý, như được chỉ định theo ngữ cảnh hạt nhân được cung cấp. Vui lòng xem rsGetArray0() để biết nội dung giải thích về ngữ cảnh này.

Trả về RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X nếu không có kích thước khuôn mặt.

rsGetLod : Chỉ mục trong thứ nguyên Cấp chi tiết cho ngữ cảnh hạt nhân được chỉ định

uint32_t rsGetLod(ngữ cảnh rs_kernel_context); Đã thêm vào API cấp 23

Trả về chỉ mục theo thứ nguyên Cấp chi tiết của ô đang được xử lý, như được chỉ định theo ngữ cảnh hạt nhân đã cung cấp. Vui lòng xem rsGetArray0() để biết thông tin giải thích về ngữ cảnh này.

Trả về 0 nếu không có thứ nguyên Cấp chi tiết.