AGSL 可與 GLSL ES 1.0 密切相容。詳情請參閱 OpenGL ES 著色語言說明文件中的對等函式。此說明文件會盡可能找出 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) |
2x2、3x3、4x4 float 矩陣 |
half2x2, half3x3, half4x4 |
相當於 mediump float 個矩陣類型 |
精確度和範圍下限
這些是與每個修飾符關聯的最小保證精確度和範圍 (依 OpenGL ES 2.0 規格而定)。由於大多數裝置都支援 ES 3.0，因此能夠保證 highp 精確度/範圍和 int mediump 範圍。精確度修飾符可以套用至純量、向量和矩陣變數和參數。僅有下列最低限度；lowp 不一定實際上低於 mediump，且 mediump 的精確度未必低於 highp。AGSL 目前會在最終輸出結果中將 lowp 轉換為 mediump。
| 修飾符 | 「浮點值」範圍 | 「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\}\) |
除了陣列數字下標語法外，還有 ex: 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 僅支援全域範圍的結構。
struct type-name {
members
} struct-name; // optional variable declaration.
使用 C 樣式或 GLSL 樣式語法，僅支援含明確陣列大小的 1 維陣列：
<基數>[<array size>] 變數名稱 - 例如：half[10] x;
<基礎類型> 變數名稱 [<陣列大小>] - 例如：half x[10];
無法從函式、已複製、指派或比較項目傳回陣列。 陣列限制會傳播至含有陣列的結構。陣列只能使用常數或迴圈變數建立索引。
資格賽
| 類型 | 說明 |
|---|---|
const
|
編譯時間常數或唯讀函式參數。 |
uniform
|
值在處理原始期間不會改變。系統會使用適用於 setColorUniform、setFloatUniform、setIntUniform、setInputBuffer 和 setInputShader 的 RuntimeShader 方法，從 Android 傳遞統一格式。 |
in
|
針對傳入的函式參數。此為預設值。 |
out
|
針對傳遞的函式參數。必須使用與函式定義相同的精確度。 |
inout
|
適用於函式傳入及傳出的參數。必須使用與函式定義相同的精確度。 |
變量聲明
宣告內容必須在明確的多重脈絡範圍內。系統不允許宣告下列範例中的 y：
if (condition)
int y = 0;
矩陣/結構/陣列基本資訊
矩陣建構函式範例
如果以單一值建構矩陣，對對角線的所有值都會提供該值，其餘的值則會給零。float2x2(1.0) 會建立 2x2 的身分矩陣。
使用多個值建構矩陣時，系統會先填入資料欄 (資料欄與主要順序)。
請注意，與 GLSL 不同的是，建構函式無法減少傳遞的向量元件數量，但您可以使用滑動方式達到相同效果。如要從 AGSL 中的 vec4 建構 vec3，且行為與 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
結構欄位
使用句號 . 運算子選取結構欄位。運算子包括：
| 業者 | 說明 |
|---|---|
. |
欄位選取器 |
==, != |
平等 |
= |
作業 |
Array 元素
陣列元素可透過陣列下標運算子 [ ] 存取。例如：
diffuseColor += lightIntensity[3] * NdotL;
運算子
依優先順序排列。關係和等式運算子 > < <= >= == != 評估為布林值。如要以元件方式比較向量，請使用 lessThan()、equal() 等函式。
| 業者 | 說明 | 互助性 | |
|---|---|---|---|
| 1 | () |
括號式分組 | 無 |
| 2 | [] () . ++ --
|
陣列下標函式呼叫和建構函式結構 欄位或方法選取器、滑動後 遞增和減少 | 由左至右 |
| 3 | ++ -- + - !
|
前置字元增加和減少 | 從右到左 |
| 4 | * / |
乘除 | 從左至右 |
| 5 | + - |
加減法 | 從左至右 |
| 7 | < > <= >= |
關聯 | 從左至右 |
| 8 | == != |
不等/不相等 | 從左至右 |
| 12 | && |
邏輯 AND | 從左至右 |
| 13 | ^^ |
邏輯 XOR | 從左至右 |
| 14 | || |
邏輯 OR | 從左至右 |
| 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) |
迴圈限制
與 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) |
根據 x 的正負號傳回 -1.0、0.0 或 1.0 |
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) |
傳回 minVal 和 maxVal 之間的 x 限制值。 |
GT clamp(GT x, float
minVal, float maxVal) |
傳回 minVal 和 maxVal 之間的 x 限制值 |
GT saturate(GT x) |
傳回介於 0.0 和 1.0 之間的 x 限制值 |
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) |
如果 x < 邊緣會傳回 0.0，則傳回 0.0，否則傳回 1.0 |
GT step(float edge,
GT x) |
如果 x < 邊緣會傳回 0.0，則傳回 0.0，否則傳回 1.0。 |
GT smoothstep(GT edge0,
GT edge1, GT x) |
當 Edge0 < x < Edge1 之間 |
GT smoothstep(float
edge0, float edge1,
GT x) |
當 Edge0 < x < Edge1 之間 |
幾何函式
這些函式是以向量的形式運作，而非元件。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) |
如果 dot(Nref, I) < 0, else -N，就會傳回 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 < y |
BV lessThanEqual(T x,
T y) |
x <= y |
BV greaterThan(T x,
T y) |
x > y |
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) |
如果 x 的任何元件為 true，則為 true |
bool all(BV x) |
如果 x 的所有元件都是 true，則為 true。 |
BV not(BV x) |
x 的邏輯補餘 |
顏色函式
| 功能 | 說明 |
|---|---|
vec4 unpremul(vec4
color) |
將顏色值轉換為非預先調節係數的 Alpha 值 |
half3 toLinearSrgb(half3
color) |
將色域轉換為線性 SRGB |
half3 fromLinearSrgb(half3
color) |
色域轉換 |
著色器取樣 (評估)
系統不支援取樣類型，但您可以評估其他著色器。如要對紋理進行取樣，您可以建立 BitmapShader 物件並新增為統一物件。您可以為任何著色器完成這項操作，這表示您可以直接評估任何 Android 著色器，不必先將其轉換為點陣圖，包括其他 RuntimeShader 物件。這可以提供大量的彈性，但複雜的著色器評估成本可能很高，尤其是在迴圈中。
uniform shader image;
image.eval(coord).a // The alpha channel from the evaluated image shader
原始緩衝區取樣
雖然大部分的圖片都應使用顏色管理顏色，但部分圖片包含的資料並非實際顏色，包括儲存法線圖片、材質屬性 (例如粗糙度)、高度貼圖，或是圖像中發生的任何其他純數學資料。在 AGSL 中使用這類圖片時，您可以透過 RuntimeShader#setInputBuffer，將 BitmapShader 當做一般原始緩衝區。這將防止色域轉換和篩選。