עזרה בנושא RenderScript Runtime API

סקירה כללית

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

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

כדי להשתמש ב-RenderScript, צריך להשתמש בממשקי ה-API בסביבת זמן הריצה של RenderScript שמתוארים כאן, וגם בממשקי ה-API של מסגרת Android ל-RenderScript. למסמכי עזרה בנושא ממשקי ה-API של Android framework, אפשר לעיין במסמכי העזרה של החבילה android.renderscript.

מידע נוסף על פיתוח באמצעות RenderScript ועל האינטראקציה בין סביבת זמן הריצה לבין ממשקי ה-API של מסגרת Android זמין במדריך למפתחים של RenderScript ובדוגמאות ל-RenderScript.

סוגי נתונים מספריים

סקלר:

ב-RenderScript יש תמיכה בסוגי המספרים הסקלריים הבאים:

	8 ביט	16 ביט	32 סיביות	64 ביט
מספר שלם:	char, ‏ int8_t	short, ‏ int16_t	int32_t	long, ‏ long long, ‏ int64_t
מספר שלם ללא סימן:	uchar, ‏ uint8_t	ushort, ‏ uint16_t	uint, ‏ uint32_t	ulong, ‏ uint64_t
נקודה צפה:		חצי	float	double

וקטורים:

ב-RenderScript יש תמיכה בווקטורים בגודל קבוע באורך 2, 3 ו-4. מודעים מכריזים על וקטורים באמצעות שם הסוג הנפוץ ואחריו 2, 3 או 4. לדוגמה: float4, ‏ int3, ‏ double2, ‏ ulong4.

כדי ליצור ליטרלים של וקטורים, צריך להשתמש בסוג הווקטור ואחריו להוסיף את הערכים שמקובצים בסוגריים מסולסלים, למשל (float3){1.0f, 2.0f, 3.0f}.

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

כדי לגשת לרשומה יחידה, מוסיפים נקודה אחרי שם המשתנה ואז:

• האותיות x,‏ y,‏ z ו-w,
• האותיות r,‏ g,‏ b ו-a,
• האות s או S, ואחריה אינדקס שמתחיל באפס.

לדוגמה, ב-int4 myVar;, הביטויים הבאים זהים:
myVar.x == myVar.r == myVar.s0 == myVar.S0
myVar.y == myVar.g == myVar.s1 == myVar.S1
myVar.z == myVar.b == myVar.s2 == myVar.S2
myVar.w == myVar.a == myVar.s3 == myVar.S3

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

בדוגמה שלמעלה, אפשר לגשת לשתי הרשומות האמצעיות באמצעות myVar.yz,‏ myVar.gb,‏ myVar.s12 ו-myVar.S12.

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

ריכזנו כאן כמה דוגמאות לפעולות שאפשר או אי אפשר לבצע:
float4 v4;
float3 v3;
float2 v2;
v2 = v4.xx; // Valid
v3 = v4.zxw; // Valid
v3 = v4.bba; // Valid
v3 = v4.s032; // Valid
v3.s120 = v4.S233; // Valid
v4.yz = v3.rg; // Valid
v4.yzx = v3.rg; // Invalid: mismatched sizes
v4.yzz = v3; // Invalid: z appears twice in an assignment
v3 = v3.xas0; // Invalid: can't mix xyzw with rgba nor s0...
v3 = v4.s034; // Invalid: the digit can only be 0, 1, 2, or 3


מטריצות וקוואטרניונים:

ב-RenderScript יש תמיכה במטריצות ריבועיות בגודל קבוע של מספרים מרחפים בגודל 2x2,‏ 3x3 ו-4x4. השמות של הסוגים הם rs_matrix2x2,‏ rs_matrix3x3 ו-rs_matrix4x4. רשימת הפעולות מפורטת במאמר פונקציות מטריקס.

יש תמיכה גם בקוואטרניונים באמצעות rs_quaternion. רשימת הפעולות מופיעה במאמר פונקציות של quaterrion.

סוגים
char2	שני מספרים שלמים בעלי סימן באורך 8 ביט
char3	שלושה מספרים שלמים עם סימן באורך 8 ביט
char4	ארבעה מספרים שלמים בעלי סימן באורך 8 ביט
double2	שני מספרים ממשיים (float) ב-64 ביט
double3	שלושה מספרים ממשיים (float) ב-64 ביט
double4	ארבעה מספרים ממשיים (float) ב-64 ביט
float2	שני מספרים ממשיים (float) ב-32 ביט
float3	שלושה מספרים ממשיים (float) ב-32 ביט
float4	ארבעה מספרים ממשיים (float) ב-32 ביט
half	ערך נקודה צפה (floating-point) של 16 ביט
half2	שני מספרים ממשיים (float) של 16 ביט
half3	שלושה מספרים מופשטים (float) של 16 ביט
half4	ארבעה מספרים ממשיים (float) ב-16 ביט
int16_t	מספר שלם של 16 ביט עם סימן
int2	שני מספרים שלמים בעלי סימן באורך 32 ביט
int3	שלושה מספרים שלמים עם סימן באורך 32 ביט
int32_t	מספר שלם בסימן של 32 ביט
int4	ארבעה מספרים שלמים בעלי סימן באורך 32 ביט
int64_t	מספר שלם בסימן של 64 ביט
int8_t	מספר שלם בסימן של 8 ביט
long2	שני מספרים שלמים ב-64 ביט עם סימן
long3	שלושה מספרים שלמים וחתומים של 64 ביט
long4	ארבעה מספרים שלמים וחתומים של 64 ביט
rs_matrix2x2	מטריצת 2x2 של מספרים ממשיים (float) ב-32 ביט
rs_matrix3x3	מטריצה 3x3 של מספרים ממשיים (float) ב-32 ביט
rs_matrix4x4	מטריצה 4x4 של מספרים ממשיים (float) ב-32 ביט
rs_quaternion	קוואטרניון
short2	שני מספרים שלמים בעלי סימן באורך 16 ביט
short3	שלושה מספרים שלמים עם סימן באורך 16 ביט
short4	ארבעה מספרים שלמים בעלי סימן באורך 16 ביט
size_t	סוג גודל ללא סימן
ssize_t	סוג חתום של גודל
uchar	מספר שלם ללא סימן באורך 8 ביט
uchar2	שני מספרים שלמים ללא סימן (unsigned integer) של 8 ביט
uchar3	שלושה מספרים שלמים ללא סימן (unsigned integer) של 8 ביט
uchar4	ארבעה מספרים שלמים ללא סימן (unsigned integer) של 8 ביט
uint	מספר שלם ללא סימן באורך 32 ביט
uint16_t	מספר שלם ללא סימן באורך 16 ביט
uint2	שני מספרים שלמים ללא סימן באורך 32 ביט
uint3	שלושה מספרים שלמים ללא סימן (unsigned integer) של 32 ביט
uint32_t	מספר שלם ללא סימן באורך 32 ביט
uint4	ארבעה מספרים שלמים ללא סימן באורך 32 ביט
uint64_t	מספר שלם ללא סימן (unsigned integer) של ‎64 סיביות
uint8_t	מספר שלם ללא סימן באורך 8 ביט
ulong	מספר שלם ללא סימן (unsigned integer) של ‎64 סיביות
ulong2	שני מספרים שלמים ללא סימן (unsigned integer) של 64 סיביות
ulong3	שלושה מספרים שלמים ללא סימן (unsigned integer) של 64 ביט
ulong4	ארבעה מספרים שלמים ללא סימן (unsigned integer) של 64 סיביות
ushort	מספר שלם ללא סימן באורך 16 ביט
ushort2	שני מספרים שלמים ללא סימן באורך 16 ביט
ushort3	שלושה מספרים שלמים ללא סימן באורך 16 ביט
ushort4	ארבעה מספרים שלמים ללא סימן באורך 16 ביט

סוגי אובייקטים

הסוגים הבאים משמשים לטיפול באובייקטים של RenderScript, כמו הקצאות, Samplers, רכיבים וסקריפטים. רוב האובייקטים האלה נוצרים באמצעות ממשקי ה-API של Java RenderScript.

סוגים
rs_allocation	הקצאה למזהה
rs_allocation_cubemap_face	Enum לבחירת פנים של מפת קוביות
rs_allocation_usage_type	שדה ביטים לציון אופן השימוש בהקצאה
rs_data_kind	סוג הנתונים של הרכיב
rs_data_type	סוג הנתונים הבסיסי של הרכיב
rs_element	אחיזה ברכיב
rs_sampler	הרשאה ל-Sampler
rs_sampler_value	ערך T של Sampler wrap
rs_script	הפנייה לסקריפט
rs_type	ידית לסוג
rs_yuv_format	פורמט YUV

פונקציות המרה

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

פונקציות
convert	המרת וקטורים מספריים
rsPackColorTo8888	יצירת uchar4 RGBA מ-floats
rsUnpackColor8888	יצירת RGBA מסוג float4 מ-uchar4
rsYuvToRGBA	המרת ערך YUV ל-RGBA

פונקציות וקבועים מתמטיים

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

לדוגמה:
float3 a, b;
// The following call sets
// a.x to sin(b.x),
// a.y to sin(b.y), and
// a.z to sin(b.z).
a = sin(b);


במאמר פונקציות מתמטיות של וקטורים מפורט מידע על פונקציות כמו distance()‎ ו-length()‎, שמפרשות את הקלט כוקטור יחיד במרחב n-ממדי.

הדיוק של הפעולות המתמטיות על ערכים של 32 ביט עם נקודה צפה מושפע מהפראגמות rs_fp_relaxed ו-rs_fp_full. כשמשתמשים ב-rs_fp_relaxed, ערכים רגילים חלקית עשויים להימחק לאפס, ועשוי להתבצע עיגול לאפס. לעומת זאת, ב-rs_fp_full נדרש טיפול נכון בערכים קטנים מהרגיל, כלומר ערכים קטנים מ-1.17549435e-38f. בנוסף, ב-rs_fp_rull נדרש עיגול לשבר הקרוב ביותר, עם עיגול למספר זוגי במקרה של שוויון.

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

• native_: יכול להיות שיהיו לו הטמעות חומרה בהתאמה אישית עם דיוק נמוך יותר. בנוסף, ייתכן שערכים רגילים חלקית יימחקו ל-0, ייתכן שייעשה שימוש בעיגול ל-0 וייתכן שלא תתבצע טיפול נכון בקלט של NaN ושל אינסוף.
• half_: יכול לבצע חישובים פנימיים באמצעות 16 ביט של פלוט. בנוסף, ייתכן שערכים רגילים למחצה יוסרו לאפס, וייתכן שייעשה שימוש בעיגול לאפס.

קבועים
M_1_PI	1 / pi, כמספר ממשי (float) ב-32 ביט
M_2_PI	2 / pi, כמספר ממשי (float) ב-32 ביט
M_2_SQRTPI	2 / sqrt(pi), כמספר ממשי (float) ב-32 ביט
M_E	e, כמספר ממשי (float) ב-32 ביט
M_LN10	log_e(10), כמספר ממשי (float) ב-32 ביט
M_LN2	log_e(2), כמספר ממשי (float) של 32 ביט
M_LOG10E	log_10(e), כמספר ממשי (float) ב-32 ביט
M_LOG2E	log_2(e), כמספר ממשי (float) ב-32 ביט
M_PI	pi, כמספר ממשי (float) ב-32 ביט
M_PI_2	pi / 2, כמספר ממשי (float) ב-32 ביט
M_PI_4	pi / 4, כמספר ממשי (float) ב-32 ביט
M_SQRT1_2	1 / sqrt(2), כמספר ממשי (float) ב-32 ביט
M_SQRT2	sqrt(2), כמספר ממשי (float) של 32 ביט

פונקציות
abs	הערך המוחלט של מספר שלם
acos	קוסינוס הופכי
acosh	קוסינוס היפרבולי הפוך
acospi	קוסינוס הפוך חלקי פאי
asin	סינוס הופכי
asinh	סינוס היפרבולי הפוך
asinpi	סינוס הפוך חלקי פאי
atan	טנגנס הופכי
atan2	הטנגנס ההופכי של יחס
atan2pi	הטנגנס ההופכי של יחס, חלקי פאי
atanh	היפוך הטנגנס ההיפרבולי
atanpi	טנגנט הופכי חלקי פאי
cbrt	שורש שלישי
ceil	המספר השלם הקטן ביותר שאינו קטן מערך מסוים
clamp	הגבלת ערך לטווח
clz	מספר הביטים הפותחים של 0
copysign	העתקת הסימן של מספר למספר אחר
cos	קוסינוס
cosh	קוסינוס היפרבולי
cospi	קוסינוס של מספר כפול פאי
מעלות	המרה של רדיאנים למעלות
erf	פונקציית שגיאה מתמטית
erfc	פונקציית שגיאה מתמטית משלימה
exp	e בחזקת מספר
exp10	10 בחזקת מספר
exp2	2 בחזקת מספר
expm1	e בחזקת מספר מינוס אחד
fabs	הערך המוחלט של נקודה צפה
fdim	ההפרש החיובי בין שני ערכים
floor	המספר השלם הקטן ביותר שלא גדול מערך מסוים
fma	כפל והוספה
fmax	מקסימום שני מספרים מסוג float
fmin	מינימום שני פלוטורים
fmod	מודולוס
fract	חלק עשרוני חיובי
frexp	חזקה וחזקה רגילה בינאריות
half_recip	ערכים הופכים לערכים הפוכים ברמת דיוק של 16 ביט
half_rsqrt	הופכי של שורש ריבועי שמחושב ברמת דיוק של 16 ביט
half_sqrt	שורש ריבועי שמחושב בדיוק של 16 ביט
hypot	היפותנוזה
ilogb	מעריך בסיס שני
ldexp	יצירת נקודה צפה מחזקה וחזקה
lgamma	הלוגריתם הטבעי של פונקציית הגאמה
log	לוגריתם טבעי
log10	לוגריתם בסיס 10
log1p	לוגריתם טבעי של ערך ועוד 1
log2	לוגריתם בבסיס 2
logb	מעריך בסיס שני
mad	כפל והוספה
max	מקסימום
min	מינימום
mix	מערבב בין שני ערכים
modf	רכיבים שלמים וחלקיים
nan	Not a Number
nan_half	Not a Number
native_acos	היפוך קוסינוס משוער
native_acosh	קוסינוס היפרבולי הפוך משוער
native_acospi	קוסינוס הופכי משוער חלקי פאי
native_asin	סינוס הופכי משוער
native_asinh	סינוס היפרבולי הפוך משוער
native_asinpi	סינוס הפוך משוער חלקי פאי
native_atan	נגזרת הפוכה משוערת של טנגנס
native_atan2	טנגנס הופכי משוער של יחס
native_atan2pi	טנגנט הופכי משוער של יחס, חלקי פאי
native_atanh	טנגנס היפרבולי הפוך משוער
native_atanpi	טנגנט הופכי משוער חלקי פאי
native_cbrt	שורש שלישי משוער
native_cos	קוסינוס משוער
native_cosh	קוסינוס היפרבולי משוער
native_cospi	קוסינוס משוער של מספר כפול פאי
native_divide	חלוקה משוערת
native_exp	הערך המשוער של e בחזקת מספר
native_exp10	הערך המשוער של 10 בחזקת מספר
native_exp2	הערך המשוער של 2 בחזקת מספר
native_expm1	הערך המשוער של e בחזקת מספר מינוס אחד
native_hypot	היפותנוזה משוערת
native_log	לוגריתם טבעי משוער
native_log10	לוגריתם משוער על בסיס 10
native_log1p	לוגריתם טבעי משוער של ערך ועוד 1
native_log2	לוגריתם משוער לפי בסיס 2
native_powr	בסיס חיובי משוער שמורם למעריך
native_recip	פונקציית הופכית קרובה
native_rootn	שורש n משוער
native_rsqrt	הופכי משוער של שורש ריבועי
native_sin	סינוס משוער
native_sincos	סינוס וקוסינוס בקירוב
native_sinh	סינוס היפרבולי משוער
native_sinpi	סינוס משוער של מספר כפול פאי
native_sqrt	שורש ריבועי משוער
native_tan	טנגנס משוער
native_tanh	טנגנס היפרבולי משוער
native_tanpi	טנגנס משוער של מספר כפול פאי
nextafter	המספר הבא של נקודה צפה
pow	בסיס בחזקת מעריך
pown	בסיס שהועלה בחזקה של מספר שלם
powr	בסיס חיובי בחזקת מעריך
רדיאנים	המרה של מעלות לרדיאנים
remainder	היתרה של חלוקה
remquo	שארית ומכפיל של חלוקה
rint	עיגול למספר שלם
rootn	שורש N
round	עיגול הרחק מאפס
rsRand	מספר אקראי לכאורה
rsqrt	הופכי של שורש ריבועי
sign	סימן הערך
sin	סינוס
sincos	סינוס וקוסינוס
sinh	סינוס היפרבולי
sinpi	סינוס של מספר כפול פאי
sqrt	שורש ריבועי
step	0 אם הערך קטן מ-value, 0 אחרת
tan	טנגנס
tanh	טנגנס היפרבולי
tanpi	טנגנט של מספר כפול פאי
tgamma	פונקציית גאמה
trunc	חיתוך של נקודה צפה (floating-point)

פונקציות מתמטיות של וקטורים

הפונקציות האלה מפרשות את ארגומנטי הקלט כמייצגים של וקטורים במרחב n-ממדי.

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

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

• native_: יכול להיות שיהיו לו הטמעות חומרה בהתאמה אישית עם דיוק נמוך יותר. בנוסף, ייתכן שערכים רגילים חלקית יוסרו ל-0, יתבצע עיגול ל-0 וייתכן שלא תתבצע טיפול נכון בקלט של NaN ושל אינסוף.
• fast_: יכול לבצע חישובים פנימיים באמצעות 16 ביט של פלוט. בנוסף, ייתכן שערכים רגילים למחצה יוסרו לאפס, וייתכן שייעשה שימוש בעיגול לאפס.

פונקציות
cross	המכפלה הווקטורית (cross product) של שני וקטורים
distance	המרחק בין שתי נקודות
נקודה	מכפלה סקלרית של שני וקטורים
fast_distance	המרחק המשוער בין שתי נקודות
fast_length	האורך המשוער של וקטור
fast_normalize	וקטור מנורמלי משוער
length	אורך וקטור
native_distance	המרחק המשוער בין שתי נקודות
native_length	האורך המשוער של וקטור
native_normalize	נורמליזציה של וקטור באופן משוער
normalize	נורמליזציה של וקטור

פונקציות מטריציוניות

הפונקציות האלה מאפשרות לבצע פעולות במטריצות ריבועיות בדרגות 2x2,‏ 3x3 ו-4x4. הם שימושיים במיוחד לטרנספורמציות גרפיות ותואמים ל-OpenGL.

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

ב-RenderScript נעשה שימוש במטריצות עם עמודות ראשיות ובווקטורים שמבוססים על עמודות. כדי לבצע טרנספורמציה של וקטור, מכפילים את הווקטור בחזרה, למשל (matrix * vector), באמצעות הפונקציה rsMatrixMultiply().

כדי ליצור מטריצה של טרנספורמציה שמבצעת שתי טרנספורמציות בו-זמנית, מכפילים את שתי מטריצות המקור, כאשר הטרנספורמציה הראשונה היא הארגומנט הימני. לדוגמה, כדי ליצור מטריצת טרנספורמציה שמחילה את הטרנספורמציה s1 ואחריה את הטרנספורמציה s2, צריך להפעיל את הפונקציה rsMatrixLoadMultiply(&combined, &s2, &s1). הערך הזה נגזר מ-s2 * (s1 * v), שהוא (s2 * s1) * v.

יש לנו שני סגנונות של פונקציות ליצירת מטריצות טרנספורמציה: Transformation של rsMatrixLoad ו-Transformation של rsMatrix. בסגנון הקודם, מטריית הטרנספורמציה מאוחסנת בארגומנט הראשון. באפשרות השנייה, מטריצה קיימת של טרנספורמציה משתנה כך שהטרנספורמציה החדשה תתבצע קודם. לדוגמה, אם קוראים ל-rsMatrixTranslate() במטריצה שכבר מבצעת שינוי קנה מידה, המטריצה שמתקבלת כשמחילים אותה על וקטור תבצע קודם את התרגום ואז את שינוי קנה המידה.

פונקציות
rsExtractFrustumPlanes	חישוב של מישורי גוף קטום
rsIsSphereInFrustum	בדיקה אם כדור נמצא בתוך המישורים של גוף דמוי חרוט
rsMatrixGet	אחזור רכיב אחד
rsMatrixInverse	הפיכת מטריצה במקום
rsMatrixInverseTranspose	הפיכה והמרת מטריצה במקום
rsMatrixLoad	טעינת מטריצה או העתקה שלה
rsMatrixLoadFrustum	טעינת מטריצה של הקרנה דרך חרוט
rsMatrixLoadIdentity	טעינת מטריצה של זהויות
rsMatrixLoadMultiply	הכפלת שתי מטריצות
rsMatrixLoadOrtho	טעינת מטריצה של הקרנה אורתוגרפית
rsMatrixLoadPerspective	טעינת מטריצת הקרנה פרופרקטיבית
rsMatrixLoadRotate	טעינת מטריצה של סיבוב
rsMatrixLoadScale	טעינת מטריצה של שינוי קנה מידה
rsMatrixLoadTranslate	טעינת מטריצה של תרגום
rsMatrixMultiply	הכפלה של מטריצה בוקטור או במטריצה אחרת
rsMatrixRotate	החלת סיבוב על מטריצה של טרנספורמציה
rsMatrixScale	החלת שינוי קנה מידה על מטריצה של טרנספורמציה
rsMatrixSet	הגדרת רכיב אחד
rsMatrixTranslate	החלת תרגום על מטריצה של טרנספורמציה
rsMatrixTranspose	החלפת מיקום של מטריצה

פונקציות Quaternion

הפונקציות הבאות מבצעות מניפולציות על קוואטרניונים.

פונקציות
rsQuaternionAdd	הוספת שני קווטרניונים
rsQuaternionConjugate	הופעה מצומדת של קוואטרניון
rsQuaternionDot	מכפלת נקודות של שני קווטרניונים
rsQuaternionGetMatrixUnit	אחזור מטריצה של רוטציה מ-quaternion
rsQuaternionLoadRotate	יצירת קוואטרניון של סיבוב
rsQuaternionLoadRotateUnit	קוואטרניון שמייצג סיבוב סביב וקטור יחידה שרירותי
rsQuaternionMultiply	הכפלת קוואטרניון בסקלר או בקווארטרניון אחר
rsQuaternionNormalize	נרמל קווטרניון
rsQuaternionSet	יצירת קוואטרניון
rsQuaternionSlerp	אינטרפולציה ליניארית כדורית בין שני קוואטרניונים

פונקציות עדכון אטומי

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

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

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

פונקציות
rsAtomicAdd	הוספה ללא סיכון לבעיות בשרשור (thread-safe)
rsAtomicAnd	ביטוי AND בינארי בטוח למחרוזות
rsAtomicCas	השוואה והגדרה ללא סיכון לבעיות בשרשור (thread-safe)
rsAtomicDec	הפחתה בטוחה למחרוזת
rsAtomicInc	הוספה בטוחה למחרוזת (thread-safe)
rsAtomicMax	ערך מקסימלי ללא סיכון לבעיות בשרשור
rsAtomicMin	מינימום בטוח למספר השרשור
rsAtomicOr	או ביטוי ברמת הסיביות ללא סיכון לבעיות בשרשור (thread-safe)
rsAtomicSub	חיסור בטוח למספרי תהליכים
rsAtomicXor	או בלעדי בוליאני ברמת הסיביות ללא סיכון לבעיות בשרשור (thread-safe)

סוגי פונקציות זמן ופונקציות זמן

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

סוגים
rs_time_t	שניות מ-1 בינואר 1970
rs_tm	המבנה של תאריך ושעה

פונקציות
rsGetDt	הזמן שחלף מאז השיחה האחרונה
rsLocaltime	המרה לזמן המקומי
rsTime	שניות מ-1 בינואר 1970
rsUptimeMillis	זמן פעולה תקינה של המערכת באלפיות שנייה
rsUptimeNanos	זמן פעולה תקינה של המערכת בננו-שניות

פונקציות ליצירת הקצאות

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

אפשר להפעיל את הפונקציות האלה באופן ישיר או עקיף מפונקציה שניתן להפעיל. אם נתיב כלשהו של תהליך הבקרה יכול לגרום לקריאה לפונקציות האלה מתוך פונקציית ליבה של RenderScript, תיווצר שגיאה במהדר.

פונקציות
rsCreateAllocation	יצירת אובייקט rs_allocation מסוג נתון.
rsCreateElement	יצירת אובייקט rs_element מסוג הנתונים שצוין
rsCreatePixelElement	יצירת אובייקט rs_element מסוג הנתונים וסוג הנתונים שצוינו
rsCreateType	יצירת אובייקט rs_type עם מאפייני הרכיב והצורה שצוינו
rsCreateVectorElement	יצירת אובייקט rs_element מסוג הנתונים ורוחבו של הווקטור שצוינו

פונקציות גישה לנתוני הקצאה

אפשר להשתמש בפונקציות הבאות כדי לקבל ולהגדיר את התאים שמרכיבים את ההקצאה.

• כדי לגשת לתאים ספציפיים, משתמשים בפונקציות rsGetElementAt* ‏ ו-rsSetElementAt.
• אפשר להעתיק כמה תאים באמצעות הפונקציות rsAllocationCopy* ו-rsAllocationV*.
• כדי לקבל ערכים באמצעות Sampler, משתמשים ב-rsSample.

השם של הפונקציות rsGetElementAt ו-rsSetElement* שגוי במקצת. הם לא מקבלים או מגדירים רכיבים, שדומים לסוגי נתונים, אלא מקבלים או מגדירים תאים. אפשר להתייחס אליהן כאל rsGetCellAt ו-rsSetCellAt.

פונקציות
rsAllocationCopy1DRange	העתקת תאים רצופים בין הקצאות
rsAllocationCopy2DRange	העתקת אזור מלבני של תאים בין הקצאות
rsAllocationVLoadX	אחזור וקטור מהקצאה של סקלרים
rsAllocationVStoreX	אחסון וקטור בהקצאה של סקלר
rsGetElementAt	החזרת תא מהקצאה
rsGetElementAtYuv_uchar_U	אחזור של רכיב U בהקצאה של רכיבי YUV
rsGetElementAtYuv_uchar_V	אחזור הרכיב V של הקצאה של רכיבי YUV
rsGetElementAtYuv_uchar_Y	אחזור הרכיב Y של הקצאה של רכיבי YUV
rsSample	דגימה של ערך מהקצאת טקסטורה
rsSetElementAt	הגדרת תא של הקצאה

פונקציות של מאפייני אובייקטים

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

הקצאות:

הקצאות הן השיטה הראשית להעברת נתונים אל ליבות RenderScript ומהן.

הן אוסף של תאים מובְנים שאפשר להשתמש בהם לאחסון בימפטים, טקסטורות, נקודות נתונים שרירותיות וכו'.

לאוסף התאים הזה יכולות להיות הרבה מאפיינים (X,‏ Y,‏ Z,‏ Array0,‏ Array1,‏ Array2,‏ Array3), פנים (למפות קוביות) ורמת פירוט (למיפ-מאפינג).

פרטים על יצירת הקצאות זמינים במאמר android.renderscript.Allocation.

רכיבים:

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

• rs_element הוא שם של מפרט סוג, ו-
• בפונקציות כמו rsGetElementAt(), 'element' הוא יצירת המופע של הסוג, כלומר תא של הקצאה.

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

רכיב יכול לציין סוגי נתונים פשוטים כמו ב-C, למשל מספר שלם, מספר עשרוני או בוליאני. אפשר גם לציין כאן את ה-handle של אובייקט RenderScript. ברשימה rs_data_type מפורטת רשימה של סוגי נתונים בסיסיים.

רכיבים יכולים לציין גרסאות של וקטור בגודל קבוע (בגודל 2, 3 או 4) של הסוגים הבסיסיים. אפשר לקבץ רכיבים יחד לרכיבים מורכבים, וכך ליצור את המקבילה להגדרות המבנה של C.

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

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

כדי ליצור רכיבי Element מורכבים, משתמשים בכיתה Element.Builder ב-Java.

סמפלים:

אובייקטים של Samplers מגדירים איך אפשר לקרוא את הקצאות (Allocations) כמבנה בתוך ליבה. מידע נוסף זמין במאמר android.renderscript.S.

פונקציות
rsAllocationGetDimFaces	יש יותר מפנים אחד
rsAllocationGetDimLOD	נוכחות של רמות פירוט
rsAllocationGetDimX	הגודל של המאפיין X
rsAllocationGetDimY	הגודל של המאפיין Y
rsAllocationGetDimZ	הגודל של המאפיין Z
rsAllocationGetElement	אחזור האובייקט שמתאר את התא של הקצאה
rsClearObject	שחרור אובייקט
rsElementGetBytesSize	גודל הרכיב
rsElementGetDataKind	סוג הרכיב
rsElementGetDataType	סוג הנתונים של רכיב
rsElementGetSubElement	רכיב משנה של רכיב מורכב
rsElementGetSubElementArraySize	גודל המערך של רכיב משנה של רכיב מורכב
rsElementGetSubElementCount	מספר רכיבי המשנה
rsElementGetSubElementName	שם של רכיב משנה
rsElementGetSubElementNameLength	האורך של שם רכיב המשנה
rsElementGetSubElementOffsetBytes	היסט של רכיב המשנה שנוצר
rsElementGetVectorSize	גודל הווקטור של הרכיב
rsIsObject	בדיקה אם הכינוי ריק
rsSamplerGetAnisotropy	אנאיזוטרופיה של הסמפלר
rsSamplerGetMagnification	ערך ההגדלה של ה-Sampler
rsSamplerGetMinification	ערך המינימיזציה של הסמפלר
rsSamplerGetWrapS	ערך S של Sampler wrap
rsSamplerGetWrapT	ערך T של Sampler wrap

סוגי פונקציות קריאה לליבת ליבה

אפשר להשתמש בפונקציה 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	הוספת אינדקס למאפיין 'רמות פירוט' בהקשר הליבה שצוין

פונקציות קלט/פלט

הפונקציות האלה משמשות כדי:

• שולחים מידע ללקוח Java, וגם
• שולחים את ההקצאה שעברה עיבוד או מקבלים את ההקצאה הבאה לעיבוד.

פונקציות
rsAllocationIoReceive	קבלת תוכן חדש מהתור
rsAllocationIoSend	שליחת תוכן חדש לתור
rsSendToClient	שליחת הודעה ללקוח, ללא חסימה
rsSendToClientBlocking	שליחת הודעה ללקוח, חסימה

ניפוי באגים בפונקציות

הפונקציות הבאות מיועדות לשימוש במהלך פיתוח האפליקציה. אין להשתמש בהם באפליקציות למשלוח.

פונקציות
rsDebug	רישום ביומן של הודעה וערכים

סוגי פונקציות וגרפיקה

מערכת המשנה של הגרפיקה ב-RenderScript הוסרה ברמת API ‏23.