סוגי פונקציות קריאה ל-RenderScript Kernel

סקירה כללית

אפשר להשתמש בפונקציה rsForEach() כדי להפעיל את הליבה ברמה הבסיסית של סקריפט.

הפונקציות האחרות משמשות לקבלת המאפיינים של ההפעלה של ליבה שפועלת, כמו מאפיינים ואינדקסים נוכחיים. הפונקציות האלה מקבלות כארגומנט rs_kernel_context.

סיכום

סוגים
rs_for_each_strategy_t סדר העיבוד המוצע של התאים
rs_kernel טיפול בפונקציית ליבה
rs_kernel_context טיפול בהקשר של קריאה לליבת המעבד
rs_script_call_t מידע על איטרציות של תאים
פונקציות
rsForEach הפעלת ליבה
rsForEachInternal (API פנימי) הפעלת ליבה בסקריפט הנוכחי (עם מספר המשבצת)
rsForEachWithOptions הפעלת ליבה עם אפשרויות
rsGetArray0 האינדקס במאפיין Array0 להקשר הליבה שצוין
rsGetArray1 אינדקס במאפיין Array1 להקשר הליבה שצוין
rsGetArray2 אינדקס במאפיין Array2 להקשר הליבה שצוין
rsGetArray3 אינדקס במאפיין Array3 להקשר הליבה שצוין
rsGetDimArray0 הגודל של המאפיין Array0 בהקשר הליבה שצוין
rsGetDimArray1 הגודל של המאפיין Array1 בהקשר הליבה שצוין
rsGetDimArray2 הגודל של המאפיין Array2 בהקשר הליבה שצוין
rsGetDimArray3 הגודל של המאפיין Array3 בהקשר הליבה שצוין
rsGetDimHasFaces נוכחות של יותר מפנייה אחת להקשר הליבה שצוין
rsGetDimLod מספר רמות הפירוט של ההקשר של הליבה שצוין
rsGetDimX הגודל של המאפיין X בהקשר הליבה שצוין
rsGetDimY הגודל של המאפיין Y בהקשר הליבה שצוין
rsGetDimZ הגודל של המאפיין Z בהקשר הליבה שצוין
rsGetFace הקואורדינטה של הפנים בהקשר הליבה שצוין
rsGetLod הוספת אינדקס למאפיין 'רמות פירוט' בהקשר הליבה שצוין

סוגים

rs_for_each_strategy_t : סדר מומלץ לעיבוד התאים

enum עם הערכים הבאים:     

RS_FOR_EACH_STRATEGY_SERIAL = 0עדיפות לאזורי זיכרון רציפים.
RS_FOR_EACH_STRATEGY_DONT_CARE = 1אין העדפות.
RS_FOR_EACH_STRATEGY_DST_LINEAR = 2העדפה ל-DST.
RS_FOR_EACH_STRATEGY_TILE_SMALL = 3עדיף לעבד אזורים קטנים בצורת מלבן.
RS_FOR_EACH_STRATEGY_TILE_MEDIUM = 4עדיף לעבד אזורים מלבניים בינוניים.
RS_FOR_EACH_STRATEGY_TILE_LARGE = 5עדיף לעבד אזורים גדולים ומלבניים.

הסוג הזה משמש להצעה לאופן שבו הליבה שהופעל צריכה לבצע איטרציה על התאים של ההקצאות. זו רק עצה. יכול להיות שההטמעות לא יתבצעו בהתאם להצעה.

המפרט הזה יכול לעזור להתנהגות האחסון במטמון של הליבה שפועלת, למשל, המיקום המקומי במטמון כשהעיבוד מופץ על פני כמה ליבות.

rs_kernel : טיפול בפונקציית ליבה

typedef של: void*     נוסף ב-רמת API 24

סוג אטום של פונקציה שמוגדרת באמצעות מאפיין הליבה. אפשר להשתמש בערך מהסוג הזה בקריאה ל-rsForEach כדי להפעיל ליבה.

rs_kernel_context : אחיזה בהקשר של קריאה לליבת ליבה

typedef של: const struct rs_kernel_context_t *     נוסף ב-רמת API 23

הקשר של הליבה מכיל מאפיינים נפוצים של ההקצאות שמתבצעת בהן חזרה, כמו מאפיינים. הוא מכיל גם אינדקסים של התא הנוכחי שמעובד, שנעשה בהם שימוש לעיתים רחוקות, כמו אינדקס Array0 או רמת הפירוט הנוכחית.

כדי לגשת להקשר של הליבה, מוסיפים לפונקציית הליבה פרמטר מיוחד בשם 'context' מסוג rs_kernel_context. דוגמאות זמינות ב-rsGetDimX() וב-rsGetArray0().

rs_script_call_t : מידע על איטרציה של תא

מבנה עם השדות הבאים:     

האסטרטגיה rs_for_each_strategy_tכרגע לא נכללת. בעתיד, תהיה הצעה לשיטת איטרציה של תאים.
uint32_t xStartאינדקס ההתחלה במימד X.
uint32_t xEndאינדקס הסיום (לא כולל) במאפיין X.
uint32_t yStartאינדקס ההתחלה במאפיין Y.
uint32_t yEndהאינדקס הסופי (לא כולל) במאפיין Y.
uint32_t zStartאינדקס ההתחלה במאפיין Z.
uint32_t zEndאינדקס הסיום (לא כולל) במאפיין Z.
uint32_t arrayStartאינדקס ההתחלה במאפיין Array0.
uint32_t arrayEndהאינדקס הסופי (לא כולל) במאפיין Array0.
uint32_t array1Startאינדקס ההתחלה במאפיין Array1.
uint32_t array1Endאינדקס הסיום (לא כולל) במאפיין Array1.
uint32_t array2Startאינדקס ההתחלה במאפיין Array2.
uint32_t array2Endאינדקס הסיום (לא כולל) במאפיין Array2.
uint32_t array3Startאינדקס ההתחלה במאפיין Array3.
uint32_t array3Endאינדקס הסיום (לא כולל) במאפיין Array3.

המבנה הזה משמש כדי לספק מידע על איטרציה לקריאה של rsForEach. בשלב הזה הוא משמש להגבלת העיבוד לקבוצת משנה של תאים. בגרסאות עתידיות, הוא ישמש גם כדי לספק רמז לגבי הדרך הטובה ביותר לעבור על התאים.

השדות 'התחלה' כוללים את התאריך עצמו, והשדות 'סיום' לא כוללים אותו. לדוגמה, כדי לבצע איטרציה על התאים 4, 5, 6 ו-7 במאפיין X, מגדירים את xStart כ-4 ואת xEnd כ-8.

פונקציות

rsForEach : הפעלת ליבה

void rsForEach(rs_kernel kernel, ... ...); נוספה ב-רמת API 24
void rsForEach(rs_script script, rs_allocation input, rs_allocation output); רמת API 14 עד 23
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData); הוסרו מ-רמת API 14 ואילך
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, const rs_script_call_t* sc); הוסרו מ-רמת API 14 ואילך
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen); רמת API 14 עד 20
void rsForEach(rs_script script, rs_allocation input, rs_allocation output, const void* usrData, size_t usrDataLen, const rs_script_call_t* sc); רמת API 14 עד 20
פרמטרים
סקריפטהסקריפט שרוצים להפעיל.
קלטהקצאה לנתוני המקור מ-.
outputהקצאה לכתיבה של תאריך.
usrDataנתונים מוגדרים על ידי משתמש שרוצים להעביר לסקריפט. יכול להיות NULL.
scפרטי בקרה נוספים שמשמשים לבחירת תת-אזור של ההקצאה לעיבוד או להצעת אסטרטגיית הליכה. יכול להיות NULL.
usrDataLenהגודל של המבנה userData. הוא ישמש ליצירת עותק שטחי של הנתונים במקרה הצורך.
ליבהסימון פונקציה לפונקציה שמוגדרת באמצעות מאפיין הליבה.
...הקצאות קלט ופלט

הפעלת הליבה על אפס הקצאות קלט או יותר. הם מועברים אחרי הארגומנט rs_kernel. אם הליבה שצוינה מחזירה ערך, צריך לציין הקצאת פלט כארגומנט האחרון. לכל הקצאות הקלט, ולקצאת הפלט אם היא קיימת, צריכים להיות אותם מאפיינים.

זוהי פונקציה סינכרונית. קריאה לפונקציה הזו מחזירה תשובה רק אחרי שכל העבודה הושלמה בכל התאים של הקצאות הקלט. אם פונקציית הליבה מחזירה ערך כלשהו, הקריאה ממתינה עד שכל התוצאות נכתבות להקצאת הפלט.

עד לרמה 23 של API, הליבה מצוינה באופן משתמע כליבה בשם 'root' בסקריפט שצוין, וניתן להשתמש רק בהקצאת קלט אחת. החל מרמת API 24, אפשר להשתמש בפונקציית ליבה שרירותית, כפי שצוין בארגומנט הליבה. הארגומנט של הסקריפט הוסר. הליבה צריכה להיות מוגדרת בסקריפט הנוכחי. בנוסף, אפשר להשתמש ביותר ממקור קלט אחד.

לדוגמה,
float __attribute__((kernel)) square(float a) {
  return a * a;
}

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

rsForEachInternal : (ממשק API פנימי) הפעלת ליבה בסקריפט הנוכחי (עם מספר השקע)

void rsForEachInternal(int slot, rs_script_call_t* options, int hasOutput, int numInputs, rs_allocation* allocs); נוספה ב-רמת API 24
פרמטרים
משבצת זמן
אפשרויות
hasOutputמציין אם הליבה יוצרת פלט
numInputsמספר הקצאות הקלט
allocsהקצאות קלט ופלט

ממשק API פנימי להפעלת ליבה.

rsForEachWithOptions : הפעלת ליבה עם אפשרויות

void rsForEachWithOptions(rs_kernel kernel, rs_script_call_t* options, ... ...); נוספה ב-רמת API 24
פרמטרים
ליבהסימון פונקציה לפונקציה שמוגדרת באמצעות מאפיין הליבה.
אפשרויותאפשרויות הפעלה
...הקצאות קלט ופלט

הפעלת הליבה באופן דומה ל-rsForEach. עם זאת, במקום לעבד את כל התאים בקלט, הפונקציה מעבדת רק תאים במרחב המשנה של מרחב האינדקס שצוין באפשרויות. כשמראים את מרחב האינדקס באופן מפורש באמצעות אפשרויות, לא נדרשת הקצאה של קלט או פלט להפעלת ליבה באמצעות ה-API הזה. אם מעבירים הקצאות, הן חייבות להתאים למספר הארגומנטים ולערך המוחזר שמצופים בפונקציית הליבה. הקצאת הפלט קיימת רק אם לליבה יש ערך החזרה שאינו ריק (void).

לדוגמה,
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 : אינדקס במאפיין Array0 של הקשר הליבה שצוין

uint32_t rsGetArray0(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את האינדקס במאפיין Array0 של התא שעובד, כפי שצוין בהקשר הליבה שסופק.

הקשר של הליבה מכיל מאפיינים משותפים של ההקצאות שמתבצעת בהן חזרה (iteration) ומערכי אינדקסים שבהם נעשה שימוש לעיתים רחוקות, כמו מערך האינדקס Array0.

כדי לגשת להקשר של הליבה, מוסיפים לפונקציית הליבה פרמטר מיוחד בשם 'context' מסוג rs_kernel_context. לדוגמה:
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);
  //...
}

הפונקציה הזו מחזירה 0 אם המאפיין Array0 לא קיים.

rsGetArray1 : אינדקס במאפיין Array1 בהקשר הליבה שצוין

uint32_t rsGetArray1(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את האינדקס במאפיין Array1 של התא שעובד, כפי שצוין בהקשר הליבה שסופק. הסבר על ההקשר זמין ב-rsGetArray0().

הפונקציה מחזירה 0 אם המאפיין Array1 לא קיים.

rsGetArray2 : אינדקס במאפיין Array2 בהקשר הליבה שצוין

uint32_t rsGetArray2(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את האינדקס במאפיין Array2 של התא שעובד, כפי שצוין בהקשר הליבה שסופק. הסבר על ההקשר זמין ב-rsGetArray0().

הפונקציה מחזירה 0 אם המאפיין Array2 לא קיים.

rsGetArray3 : אינדקס במאפיין Array3 בהקשר הליבה שצוין

uint32_t rsGetArray3(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את האינדקס במאפיין Array3 של התא שעובד, כפי שצוין בהקשר הליבה שסופק. הסבר על ההקשר זמין ב-rsGetArray0().

הפונקציה מחזירה 0 אם המאפיין Array3 לא קיים.

rsGetDimArray0 : הגודל של המאפיין Array0 בהקשר הליבה שצוין

uint32_t rsGetDimArray0(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין Array0 בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה את הערך 0 אם המאפיין Array0 לא קיים.

rsGetDimArray1 : הגודל של המאפיין Array1 בהקשר הליבה שצוין

uint32_t rsGetDimArray1(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין Array1 בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה 0 אם המאפיין Array1 לא קיים.

rsGetDimArray2 : הגודל של המאפיין Array2 בהקשר הליבה שצוין

uint32_t rsGetDimArray2(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין Array2 בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה 0 אם המאפיין Array2 לא קיים.

rsGetDimArray3 : הגודל של המאפיין Array3 בהקשר הליבה שצוין

uint32_t rsGetDimArray3(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין Array3 בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה 0 אם המאפיין Array3 לא קיים.

rsGetDimHasFaces : נוכחות של יותר מפנים אחד בהקשר הליבה שצוין

bool rsGetDimHasFaces(rs_kernel_context context); נוספה ברמת API 23
החזרות
הפונקציה מחזירה את הערך true אם יש יותר מפנייה אחת, ואת הערך false אם לא.

אם הליבה מבצעת איטרציה על מפת קוביות, הפונקציה הזו מחזירה true אם יש יותר מפנייה אחת. בכל מצב אחר, הפונקציה מחזירה את הערך false. הסבר על ההקשר זמין ב-rsGetDimX().

rsAllocationGetDimFaces() דומה, אבל מחזירה 0 או 1 במקום bool.

rsGetDimLod : מספר רמות הפירוט של הקשר הליבה שצוין

uint32_t rsGetDimLod(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את מספר רמות הפירוט של הקשר הליבה שצוין. האפשרות הזו מועילה למיפויי mip. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה את הערך 0 אם לא נעשה שימוש ברמת הפירוט.

rsAllocationGetDimLOD() דומה, אבל מחזירה 0 או 1 במקום מספר הרמות בפועל.

rsGetDimX : הגודל של המאפיין X בהקשר הליבה שצוין

uint32_t rsGetDimX(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין X בהקשר הליבה שצוין.

הקשר של הליבה מכיל מאפיינים משותפים של ההקצאות שמתבצעת בהן חזרה (iteration) ומערכי אינדקסים שבהם נעשה שימוש לעיתים רחוקות, כמו מערך האינדקס Array0.

כדי לגשת אליו, מוסיפים לפונקציית הליבה פרמטר מיוחד בשם 'context' מסוג rs_kernel_context. לדוגמה:
int4 RS_KERNEL myKernel(int4 value, rs_kernel_context context) {
  uint32_t size = rsGetDimX(context); //...

כדי לקבל את המאפיין של הקצאה ספציפית, משתמשים ב-rsAllocationGetDimX().

rsGetDimY : הגודל של המאפיין Y בהקשר הליבה שצוין

uint32_t rsGetDimY(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של המאפיין X בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה את הערך 0 אם המאפיין Y לא קיים.

כדי לקבל את המאפיין של הקצאה ספציפית, משתמשים בפונקציה rsAllocationGetDimY().

rsGetDimZ : הגודל של המאפיין Z בהקשר הליבה שצוין

uint32_t rsGetDimZ(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הגודל של מימד Z בהקשר הליבה שצוין. הסבר על ההקשר זמין ב-rsGetDimX().

הפונקציה מחזירה 0 אם המאפיין Z לא קיים.

כדי לקבל את המאפיין של הקצאה ספציפית, משתמשים בפונקציה rsAllocationGetDimZ().

rsGetFace : קואורדינטה של הפנים בהקשר הליבה שצוין

rs_allocation_cubemap_face rsGetFace(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את הפנים שבהם נמצא התא שעובד, כפי שצוין בהקשר הליבה שסופק. הסבר על ההקשר זמין ב-rsGetArray0().

הפונקציה מחזירה את הערך RS_ALLOCATION_CUBEMAP_FACE_POSITIVE_X אם מאפיין הפנים לא נמצא.

rsGetLod : אינדקס במאפיין רמות הפירוט של הקשר הליבה שצוין

uint32_t rsGetLod(rs_kernel_context context); נוספה ברמת API 23

הפונקציה מחזירה את האינדקס במאפיין רמות הפירוט של התא שעובד, כפי שצוין בהקשר הליבה שסופק. הסבר על ההקשר זמין ב-rsGetArray0().

הפונקציה מחזירה את הערך 0 אם המאפיין 'רמות פירוט' לא קיים.