מידע מהיר על AGSL

AGSL תוכנן להיות תואם ברובו ל-GLSL ES 1.0. לקבלת מידע נוסף, את הפונקציה המקבילה מסמכי תיעוד של OpenGL ES Shading Language כשהדבר אפשרי, מסמכי התיעוד האלה מנסים להסביר את ההבדלים בין AGSL ו-GLSL.

סוגים

ב-AGSL יש תמיכה בסוגי GLSL ES 1.0 וגם דרך נוספת לייצג וקטור ומטריצות. AGSL תומך בסוגים נוספים של short ו-half לייצוג בדיוק בינוני.

סוגים בסיסיים

סוג	תיאור
void	אין פונקציה שמחזירה ערך או פרמטר ריק חדשה. בניגוד ל-GLSL, הפונקציה פועלת ללא ערך הערך המוחזר חייב להחזיר ערך.
bool, bvec2, bvec3, bvec4 (bool2, bool3, bool4)	סקלר/וקטור בוליאני
int, ivec2, ivec3, ivec4 (int2, int3, int4)	וקטור/מספר שלם חתום highp
float, vec2, vec3, vec4 (float2, float3, float4)	נקודה צפה של highp (דיוק יחיד) סקלר/וקטור
short, short2, short3, short4	שווה ערך לסימן 'mediump int' חתום מספר שלם/וקטור
half, half2, half3, half4	שווה ערך לסקלר/וקטור mediump float
mat2, mat3, mat4 (float2x2, float3x3, float4x4)	מטריצת float, 2x2, 3x3, 4x4
half2x2, half3x3, half4x4	שוות ערך לסוגי המטריצה של mediump float

דיוק וטווח מינימליים

אלה ערכי הדיוק והטווח המינימליים המובטחים שמשויכים לכל מגביל מבוסס על מפרט OpenGL ES 2.0. מאז רוב המכשירים תומכים ב-ES 3.0, הדיוק/הטווח שלהם יהיה גבוה יותר ב-highp טווח int mediump. ניתן להחיל תנאי דיוק על סקלר, על וקטור משתנים ופרמטרים של מטריצות. רק ערכי המינימום שמפורטים בהמשך מובטחים. רמת הדיוק של lowp לא בהכרח נמוכה יותר מזו של mediump, וגם mediump הוא לא בהכרח רמת דיוק נמוכה יותר מאשר highp. נכון לעכשיו, AGSL משלים המרה של lowp ל-mediump בפלט הסופי.

מגביל	'float' טווח	'float' טווח גודל	'float' דיוק	'int' טווח
גבוה	\(\left\{-2^{62},2^{62}\right\}\)	\(\left\{2^{-62},2^{62}\right\}\)	קרוב משפחה: \(2^{-16}\)	\(\left\{-2^{16},2^{16}\right\}\)
בינוני	\(\left\{-2^{14},2^{14}\right\}\)	\(\left\{2^{-14},2^{14}\right\}\)	קרוב משפחה: \(2^{-10}\)	\(\left\{-2^{10},2^{10}\right\}\)
נמוכה	\(\left\{-2,2\right\}\)	\(\left\{2^{-8},2\right\}\)	מוחלט: \(2^{-8}\)	\(\left\{-2^{8},2^{8}\right\}\)

בנוסף לתחביר מספרי של כתב תחתי מערך, לדוגמה: var[num], names of vector components for vectors of length 2 - 4 are denoted by a single letter. Components can be swizzled and replicated. ex:vect.yx,vect.yy`

vect.xyzw – לשימוש בעת גישה לווקטורים שמייצגים נקודות/נורמליות

vect.rgba – לשימוש כשניגשים לווקטורים שמייצגים צבעים

vect.LTRB – שימוש כאשר הווקטור מייצג מלבן (לא ב-GLSL)

ב-AGSL, אפשר להשתמש במספרים 0 ו-1 כדי ליצור מספר 0 או 1 קבוע בערוץ הזה. לדוגמה: vect.rgb1 == vec4(vect.rgb,1)

מבנים ומערכים

המבנים מוצהרים עם תחביר זהה לזה של GLSL, אבל ב-AGSL יש תמיכה רק ב-AGSL. נרחבים בהיקף גלובלי.

struct type-name {
 members
} struct-name; // optional variable declaration.

רק מערכים חד-ממדיים נתמכים עם גודל מערך מפורש, באמצעות תחביר של סגנון C או GLSL:

שם המשתנה <base type>[<array size>] – לדוגמה: half[10] x;

<base type> שם המשתנה [<array size>] - לדוגמה: half x[10];

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

מוקדמות

הערה: אין תמיכה ב-attribute, ב-varying וב-invariant.

סוג	תיאור
const	פונקציה קבועה עם זמן הידור או פונקציה לקריאה בלבד הפרמטר.
uniform	הערך לא משתנה לאורך כל רכיב בתהליך עיבוד. מדים מועברים מ-Android באמצעות RuntimeShader שיטות ל-setColorUniform, setFloatUniform, setIntUniform, setInputBuffer וגם setInputShader.
in	לפרמטרים של פונקציה שמועברת. כאן כברירת מחדל.
out	לפרמטרים של פונקציה מועברת. חובה להשתמש אותו רמת דיוק כמו הגדרת הפונקציה.
inout	לגבי פרמטרים גם שמועברים וגם מועברים של פונקציה. יש להשתמש באותו דיוק כמו את הגדרת הפונקציה.

הצהרה לגבי משתנים

ההצהרות חייבות להיות בהיקף סוגריים מפורש. ההצהרה של y ב- הדוגמה הבאה אסורה:

if (condition)
    int y = 0;

יסודות של מטריצה/מבנה/מערך

דוגמאות לבניית מטריצות

כשמטריצה נבנית עם ערך יחיד, כל הערכים האלכסון מקבל את הערך הזה, והשאר מקבל אפסים. float2x2(1.0) ירצה ולכן תיצור מטריצת זהות בגודל 2x2.

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

שימו לב שבניגוד ל-GLSL, בנאים שמצמצמים את מספר הרכיבים של אין תמיכה בווקטור שהועבר, אבל אפשר להשתמש בהזזה כדי ! כדי ליצור vec3 מ-vec4 ב-AGSL עם אותה התנהגות כמו GLSL, צריך לציין vec3 nv = quadVec.xyz.

דוגמה לבניית מבנה

struct light { float intensity; float3 pos; };
// literal integer constants auto-converted to floating point
light lightVar = light(3, float3(1, 2, 3.0));

רכיבי המטריצה

גישה לרכיבים של מטריצה עם תחביר לכתיבה תחתי של מערך.

float4x4 m; // represents a matrix
m[1] = float4(2.0); // sets second column to all 2.0
m[0][0] = 1.0; // sets upper left element to 1.0
m[2][3] = 2.0; // sets 4th element of 3rd column to 2.0

שדות מבנה

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

מפעיל	תיאור
.	בורר שדות
==, !=	שוויון
=	מטלה

רכיבי מערך

ניתן לגשת לרכיבי מערך באמצעות אופרטור כתב תחתי של מערך [ ]. לדוגמה:

diffuseColor += lightIntensity[3] * NdotL;

מפעילים

ממוספר לפי סדר הקדימות. היחסים בין שוויון אופרטורים > &lt; <= >= == != מקבל ערך בוליאני. כדי להשוות בין וקטורים מבחינת הרכיבים, יש להשתמש בפונקציות כמו lessThan(), equal() וכו'.

	מפעיל	תיאור	שיוכים
1	()	קיבוץ בסוגריים	לא רלוונטי
2	[] () . ++ --	תת-תו של מערך הפעלת פונקציה ו- constructor שדה או שיטה סלקטור, החלקה מרווח הוספה (postfix) וגם הקטנה	משמאל לימין
3	++ -- + - !	תוספת של תחילית וגם הפחתה אונרית	מימין לשמאל
4	* /	להכפיל ולחלק	משמאל לימין
5	+ -	חיבור וחיסור	משמאל לימין
7	< > <= >=	יחסי	משמאל לימין
8	== !=	שוויון/אי שוויון	משמאל לימין
12	&&	"וגם" בלוגיקה	משמאל לימין
13	^^	XOR לוגי	משמאל לימין
14	||	לוגי או	משמאל לימין
15	?\:	בחירה (שלם אחד אופרנד)	משמאל לימין
16	= += -= *= /=	מתמטיקה למטלות מתמטיקה למטלות מטלה	משמאל לימין
17	,	רצף	משמאל לימין

פעולות וקטורים ומטריצה

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

פעולה	תיאור
m = f * m	הכפלה של מטריצה ברמת הרכיב בערך סקלרי
v = f * v	הכפלה של וקטורים ברמת הרכיב בערך סקלרי
v = v * v	הכפלה של וקטורים ברמת הרכיב בערך וקטורי
m = m + m	חיבור ברמת הרכיבים של המטריצה
m = m - m	חיסור ברמת הרכיבים של המטריצה
m = m * m	הכפלה אלגברית לינארית

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

פעולה	תיאור
m = v * m	וקטור שורה * הכפלה אלגברית לינארית של מטריצה
m = m * v	כפל אלגברי לינארי בין וקטורים של עמודות ומטריצה

להשתמש בפונקציות המובנות של וקטור נקודה, מוצר חוצה-מוצרים הכפלה מבחינת רכיבים:

פעולה	תיאור
f = dot(v, v)	מכפלה וקטורית
v = cross(v, v)	מכפלה וקטורית
m = matrixCompMult(m, m)	הכפלה ברמת הרכיב

בקרת התוכנית

בקשה להפעלת פונקציה	קריאה לפי ערך-ערך
איטרציה	for (<init>;<test>;<next>) { break, continue }
בחירה	if ( ) { } if ( ) { } else { } switch () { break, case } - ברירת המחדל של סוג האותיות האחרון
קפיצה	break, continue, return (אין להשתמש בגילוי הנאות)
הערך	half4 main(float2 fragCoord)

מגבלות של לולאת for

דומה ל-GLSL ES 1.0, 'for' לולאות מוגבלות למדי; כי המהדר צריך להיות מסוגל כדי לפתוח את הלולאה. פירוש הדבר הוא שהמאתחל, תנאי הבדיקה הצהרת next חייבת להשתמש בקבועים כדי שיהיה אפשר לחשב הכול בזמן הידור בזמן האימון. ההצהרה next מוגבלת גם לשימוש ב-++, --, +=, or -=.

פונקציות מובנות

GT (סוג גנרי) הוא float, float2, float3, float4 או half, half2, half3, half4.

רוב הפונקציות האלה פועלות ברמת הרכיבים (הפונקציה מיושמת לרכיב). הערה: אם זה לא המצב,

זווית ו- פונקציות טריגונומטריות

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

פעולה	תיאור
GT radians(GT degrees)	ממירה מעלות לרדיאנים
GT degrees(GT radians)	ממירה רדיאנים למעלות
GT sin(GT angle)	סינוס רגיל
GT cos(GT angle)	קוסינוס רגיל
GT tan(GT angle)	טנגנס סטנדרטי
GT asin(GT x)	מחזירה זווית שהסינוס שלה הוא x בטווח מתוך $ \left[-{\pi\over 2},{\pi\over 2}\right] $
GT acos(GT x)	מחזירה זווית שהקוסינוס שלה הוא x ב טווח של $ \left[0,\pi\right] $
GT atan(GT y, GT x)	מחזירה זווית ארק-טנגנס טריגונומטרי הוא $ \left[{y\over x}\right] $ ב טווח של $ \left[-\pi,\pi\right] $
GT atan(GT y_over_x)	מחזירה זווית שהטריגונומטריה שלה הארק-טנגנס הוא y_over_x בטווח מתוך $ \left[-{\pi\over 2},{\pi\over 2}\right] $

פונקציות מעריכיות

פעולה	תיאור
GT pow(GT x, GT y)	פונקציה זו מחזירה $ x^y $
GT exp(GT x)	החזרת $ e^x $
GT log(GT x)	פונקציה זו מחזירה $ ln(x) $
GT exp2(GT x)	החזרת $ 2^x $
GT log2(GT x)	פונקציה זו מחזירה את $ log_2(x) $
GT sqrt(GT x)	פונקציה זו מחזירה $ \sqrt{x} $
GT inversesqrt(GT x)	פונקציה זו מחזירה $ 1\over{\sqrt{x}} $

פונקציות נפוצות

פעולה	תיאור
GT abs(GT x)	ערך מוחלט
GT sign(GT x)	מחזירה -1.0, 0.0 או 1.0 לפי הסימן של x
GT floor(GT x)	המספר השלם הקרוב ביותר <= x
GT ceil(GT x)	המספר השלם הקרוב ביותר >= x
GT fract(GT x)	החזרת החלק החלקי של x
GT mod(GT x, GT y)	החזרת הערך של x מודולו y
GT mod(GT x, float y)	החזרת הערך של x מודולו y
GT min(GT x, GT y)	החזרת הערך המינימלי של x או y
GT min(GT x, float y)	החזרת הערך המינימלי של x או y
GT max(GT x, GT y)	החזרת הערך המקסימלי של x או y
GT max(GT x, float y)	החזרת הערך המקסימלי של x או y
GT clamp(GT x, GT minVal, GT maxVal)	הפונקציה מחזירה x מוצמד בין minVal ל-maxVal.
GT clamp(GT x, float minVal, float maxVal)	החזרת x מוצמד בין minVal ל-maxVal
GT saturate(GT x)	פונקציה זו מחזירה x מוצמד בין 0.0 ל-1.0
GT mix(GT x, GT y GT a)	החזרת שילוב לינארי של x ו-y
GT mix(GT x, GT y, float a)	החזרת שילוב לינארי של x ו-y
GT step(GT edge, GT x)	הפונקציה מחזירה 0.0 אם x < קצה, אחרת 1.0
GT step(float edge, GT x)	הפונקציה מחזירה 0.0 אם x < קצה, אחרת 1.0
GT smoothstep(GT edge0, GT edge1, GT x)	מבצע אינטרפולציה של Hermite בין 0 ל-1 כשהקצה 0 < x < קצה 1
GT smoothstep(float edge0, float edge1, GT x)	מבצע אינטרפולציה של Hermite בין 0 ל-1 כשהקצה 0 < x < קצה 1

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

הפונקציות האלה פועלות על וקטורים בתור וקטורים, ולא ברמת הרכיבים. GT הוא וקטורים מסוג צף/חצי בגדלים 2-4.

פעולה	תיאור
float/half length (GT x)	החזרת אורך הווקטור
float/half distance(GT p0, GT p1)	החזרת מרחק בין נקודות
float/half dot(GT x, GT y)	החזרת מכפלה
float3/half3 cross(float3/half3 x, float3/half3 y)	החזרת מוצרים לא קשורים
GT normalize(GT x)	נרמול הווקטור לאורך 1
GT faceforward(GT N, GT I, GT Nref)	הפונקציה מחזירה N אם נקודה(Nref, I) < 0, אחרת – N.
GT reflect(GT I, GT N)	כיוון ההשתקפות I – 2 * נקודה(N,I) * N.
GT refract(GT I, GT N, float/half eta)	החזרת וקטור שבירה

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

מטריצת טיפוס היא כל מטריצה ריבועית.

פעולה	תיאור
mat matrixCompMult(mat x, mat y)	הכפילו את x ב-y מבחינת רכיב
mat inverse(mat m)	מחזירה את הערך ההופכי של m

פונקציות יחסיות וקטוריות

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

פעולה	תיאור
BV lessThan(T x, T y)	x < שנה
BV lessThanEqual(T x, T y)	x <= y
BV greaterThan(T x, T y)	x > שנה
BV greaterThanEqual(T x, T y)	x >= y
BV equal(T x, T y)	x == y
BV equal(BV x, BV y)	x == y
BV notEqual(T x, T y)	x != y
BV notEqual(BV x, BV y)	x != y
bool any(BV x)	true אם רכיב כלשהו של x הוא true
bool all(BV x)	true אם כל הרכיבים של x הם true.
BV not(BV x)	השלמה לוגית של x

פונקציות צבע

פעולה	תיאור
vec4 unpremul(vec4 color)	ממירה את ערך הצבע לחוסר התאמה מראש אלפא
half3 toLinearSrgb(half3 color)	טרנספורמציה של מרחב צבעים ל-SRGB ליניארי
half3 fromLinearSrgb(half3 color)	טרנספורמציה של מרחב צבעים

דגימת אזורים כהים (הערכה)

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

uniform shader image;

image.eval(coord).a   // The alpha channel from the evaluated image shader

דגימת מאגר נתונים גולמי

למרות שרוב התמונות כוללות צבעים שצריך לנהל צבעים, חלק מהתמונות מכילים נתונים שהם לא צבעים בפועל, כולל תמונות לשמירת נורמליות, תכונות מהותיות (למשל: חספוס), מפות גובה או כל מאפיין אחר לחלוטין במקרה של נתונים מתמטיים שמאוחסנים בתמונה. כשמשתמשים בסוגים האלה ב-AGSL, אפשר להשתמש ב-BitmapShader כמאגר גולמי כללי באמצעות RuntimeShader#setInputBuffer. כך ניתן למנוע טרנספורמציות וסינון של מרחב צבעים.