AGSL-Kurzübersicht

AGSL ist weitgehend mit GLSL ES 1.0 kompatibel. Weitere Informationen finden Sie in der Dokumentation zur OpenGL ES-Shading-Language. In dieser Dokumentation werden nach Möglichkeit Unterschiede zwischen AGSL und GLSL hervorgehoben.

Typen

AGSL unterstützt GLSL ES 1.0-Typen sowie eine zusätzliche Möglichkeit zur Darstellung von Vektor- und Matrixtypen. AGSL unterstützt zusätzliche short- und half-Typen zur Darstellung mittlerer Genauigkeit.

Grundlegende Typen

Eingeben	Beschreibung
void	Keine Funktion gibt einen Rückgabewert oder eine leere Parameterliste zurück. Im Gegensatz zu GLSL müssen Funktionen ohne void-Rückgabetyp einen Wert zurückgeben.
bool, bvec2, bvec3, bvec4 (bool2, bool3, bool4).	Boolescher Skalar/Vektor
int, ivec2, ivec3, ivec4 (int2, int3, int4)	highp Vorzeichenbehaftete Ganzzahl/Vektor
float, vec2, vec3, vec4 (float2, float3, float4)	highp (einfache Genauigkeit) Gleitkomma skalar/Vektor
short, short2, short3, short4	Entspricht einem signed integer/vector von mediump int
half, half2, half3, half4	Entspricht mediump float Skalar/Vektor
mat2, mat3, mat4 (float2x2, float3x3, float4x4)	2 × 2, 3 × 3, 4 × 4 float-Matrix
half2x2, half3x3, half4x4	Entspricht den Matrixtypen von mediump float

Mindestwerte für Genauigkeit und Bereich

Dies sind die Mindestgenauigkeit und der Mindestbereich, die für jeden Modifikator gemäß der OpenGL ES 2.0-Spezifikation garantiert werden. Da die meisten Geräte ES 3.0 unterstützen, ist die highp-Genauigkeit/-Reichweite und die int mediump-Reichweite bei ihnen besser. Genauigkeitsmodifikatoren können auf Skalar-, Vektor- und Matrixvariablen und ‑parameter angewendet werden. Nur die unten aufgeführten Mindestwerte sind garantiert. lowp hat nicht unbedingt eine geringere Genauigkeit als mediump und mediump hat nicht unbedingt eine geringere Genauigkeit als highp. AGSL wandelt lowp derzeit in mediump in der endgültigen Ausgabe um.

Modifizierer	Bereich „float“	„float“-Magnitudenbereich	Genauigkeit „float“	Bereich „int“
highp	\(\left\{-2^{62},2^{62}\right\}\)	\(\left\{2^{-62},2^{62}\right\}\)	Relativ: \(2^{-16}\)	\(\left\{-2^{16},2^{16}\right\}\)
mediump	\(\left\{-2^{14},2^{14}\right\}\)	\(\left\{2^{-14},2^{14}\right\}\)	Relativ: \(2^{-10}\)	\(\left\{-2^{10},2^{10}\right\}\)
lowp	\(\left\{-2,2\right\}\)	\(\left\{2^{-8},2\right\}\)	Absolut: \(2^{-8}\)	\(\left\{-2^{8},2^{8}\right\}\)

Zusätzlich zur Syntax für numerische Unterindizes von Arrays, z. B. 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 – Wird beim Zugriff auf Vektoren verwendet, die Punkte/Normalen darstellen

vect.rgba: Wird beim Zugriff auf Vektoren verwendet, die Farben darstellen

vect.LTRB – Verwenden Sie diesen Wert, wenn der Vektor ein Rechteck darstellt (nicht in GLSL)

In AGSL können 0 und 1 verwendet werden, um in diesem Kanal eine konstante 0 oder 1 zu erzeugen. Beispiel: vect.rgb1 == vec4(vect.rgb,1)

Strukturen und Arrays

Strukturen werden mit derselben Syntax wie in GLSL deklariert, aber AGSL unterstützt nur Strukturen im globalen Gültigkeitsbereich.

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

Es werden nur eindimensionale Arrays mit einer expliziten Arraygröße unterstützt. Dabei kann entweder die C-Syntax oder die GLSL-Syntax verwendet werden:

<base type>[<array size>] variable name – z. B. half[10] x;

<base type> variable name[<array size>] – z. B. half x[10];

Arrays können nicht von einer Funktion zurückgegeben, kopiert, zugewiesen oder verglichen werden. Arrayeinschränkungen werden auf Strukturen mit Arrays angewendet. Arrays können nur mit einer Konstante oder einer Schleifenvariablen indexiert werden.

Qualifikation

Hinweis: attribute, varying und invariant werden nicht unterstützt.

Eingeben	Beschreibung
const	Kompilierzeitkonstante oder schreibgeschützter Funktionsparameter.
uniform	Der Wert ändert sich nicht im Verlauf der Verarbeitung des Primitives. RuntimeShader-Methoden für setColorUniform, setFloatUniform, setIntUniform, setInputBuffer und setInputShader werden verwendet, um Uniformen von Android zu übergeben.
in	Für übergebene Funktionsparameter. Das ist die Standardeinstellung.
out	Für übergebene Funktionsparameter. Es muss dieselbe Genauigkeit wie in der Funktionsdefinition verwendet werden.
inout	Für Parameter, die sowohl an eine Funktion übergeben als auch von ihr zurückgegeben werden. Es muss dieselbe Genauigkeit wie in der Funktionsdefinition verwendet werden.

Variablendeklaration

Deklarationen müssen in einem expliziten Bereich mit Klammern stehen. Die Deklaration von y im folgenden Beispiel ist nicht zulässig:

if (condition)
    int y = 0;

Grundlagen zu Matrizen, Strukturen und Arrays

Beispiele für Matrixkonstruktoren

Wenn eine Matrix mit einem einzelnen Wert erstellt wird, wird dieser Wert allen Werten entlang der Diagonale zugewiesen, während die übrigen Nullen erhalten. float2x2(1.0) würde daher eine 2 × 2-Identitätsmatrix erstellen.

Wenn eine Matrix mit mehreren Werten erstellt wird, werden zuerst die Spalten ausgefüllt (Spaltenprioritätsreihenfolge).

Im Gegensatz zu GLSL werden Konstruktoren, die die Anzahl der Komponenten eines übergebenen Vektors reduzieren, nicht unterstützt. Sie können jedoch das Swizzle-Verfahren verwenden, um denselben Effekt zu erzielen. Wenn Sie in AGSL eine vec3 aus einer vec4 mit demselben Verhalten wie in GLSL erstellen möchten, geben Sie vec3 nv = quadVec.xyz an.

Beispiel für einen Strukturkonstruktor

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

Matrixkomponenten

Mithilfe der Array-Indexierungssyntax auf Komponenten einer Matrix zugreifen

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

Strukturfelder

Wählen Sie Strukturfelder mit dem Punktoperator . aus. Zu den Operatoren gehören:

Operator	Beschreibung
.	Feldauswahl
==, !=	Gleichheit
=	Aufgabe

Arrayelemente

Der Zugriff auf Arrayelemente erfolgt über den Array-Skriptoperator [ ]. Beispiel:

diffuseColor += lightIntensity[3] * NdotL;

Netzbetreiber

Sie sind in der Reihenfolge der Priorität nummeriert. Die relationalen und Gleichheitsoperatoren >, <, <=, >=, == und != werden als boolescher Wert ausgewertet. Verwenden Sie Funktionen wie lessThan() oder equal(), um Vektoren komponentenweise zu vergleichen.

	Operator	Beschreibung	Assoziativität
1	()	Einschub	–
2	[] () . ++ --	Array-Index, Funktionsaufruf und Konstruktorstruktur, Feld- oder Methodenauswahl, swizzle, Postfix-Increment und Postfix-Decrement	Rechtsläufig
3	++ -- + - !	Präfix-Increment und Präfix-Decrement unär	Linksläufig
4	* /	multiplizieren und dividieren	Rechtsläufig
5	+ -	addieren und subtrahieren	Rechtsläufig
7	< > <= >=	relational	Rechtsläufig
8	== !=	Gleichheit/Ungleichheit	Rechtsläufig
12	&&	Logisches UND	Rechtsläufig
13	^^	Logisches XOR	Rechtsläufig
14	||	Logisches ODER	Rechtsläufig
15	?\:	Auswahl (ein ganzer Operand)	Rechtsläufig
16	= += -= *= /=	Zuweisung arithmetische Zuweisung arithmetische Zuweisung	Rechtsläufig
17	,	Sequenz	Rechtsläufig

Matrix- und Vektoroperationen

Wenn arithmetische Operatoren auf skalare Werte angewendet werden, ergibt sich ein Skalar. Bei anderen Operatoren als Modulo wird der Vorgang komponentenweise ausgeführt, wenn ein Operand ein Skalar und der andere ein Vektor oder eine Matrix ist. Das Ergebnis hat dann denselben Vektor- oder Matrixtyp. Wenn beide Operationen Vektoren derselben Größe sind, wird die Operation komponentenweise ausgeführt und es wird derselbe Vektortyp zurückgegeben.

Betrieb	Beschreibung
m = f * m	Komponentenweise Matrixmultiplikation mit einem Skalarwert
v = f * v	Komponentenweise Vektormultiplikation mit einem Skalarwert
v = v * v	Komponentenweise Vektormultiplikation mit einem Vektorwert
m = m + m	Komponentenweise Matrixaddition
m = m - m	Komponentenweise Subtraktion von Matrizen
m = m * m	Lineare algebraische Multiplikation

Wenn ein Operand ein Vektor ist, der der Zeilen- oder Spaltengröße unserer Matrix entspricht, kann der Multiplikationsoperator zur algebraischen Zeilen- und Spaltenmultiplikation verwendet werden.

Betrieb	Beschreibung
m = v * m	Lineare algebraische Multiplikation von Zeilenvektor * Matrix
m = m * v	Matrix * Spaltenvektor – lineare algebraische Multiplikation

Verwenden Sie die integrierten Funktionen für das Vektor-Punktprodukt, das Kreuzprodukt und die komponentenweise Multiplikation:

Funktion	Beschreibung
f = dot(v, v)	Skalarprodukt
v = cross(v, v)	Vektorkreuzprodukt
m = matrixCompMult(m, m)	Komponentenweise Multiplikation

Programmsteuerung

Funktionsaufruf	Call by value-return
Iteration	for (<init>;<test>;<next>) { break, continue }
Auswahl	if ( ) { } if ( ) { } else { } switch () { break, case } – Standardfall zuletzt
Springen	break, continue, return („entfernen“ ist nicht zulässig)
Eintrag	half4 main(float2 fragCoord)

Einschränkungen bei For-Schleifen

Ähnlich wie in GLSL ES 1.0 sind „for“-Schleifen ziemlich eingeschränkt. Der Compiler muss die Schleife entschachteln können. Das bedeutet, dass für die Initialisierung, die Testbedingung und die next-Anweisung Konstanten verwendet werden müssen, damit alles zur Kompilierungszeit berechnet werden kann. Die next-Anweisung ist außerdem auf die Verwendung von ++, --, +=, or -= beschränkt.

Integrierte Funktionen

GT (generischer Typ) ist float, float2, float3, float4 oder half, half2, half3, half4.

Die meisten dieser Funktionen werden komponentenweise angewendet. Wenn dies nicht der Fall ist, wird dies vermerkt.

Winkel und trigonometrische Funktionen

Bei Funktionsparametern, die als Winkel angegeben werden, wird davon ausgegangen, dass sie in Radiant angegeben sind. Bei keiner dieser Funktionen kommt es zu einem Fehler vom Typ „Geteilt durch null“. Wenn der Nenner eines Verhältnisses 0 ist, sind die Ergebnisse nicht definiert.

Funktion	Beschreibung
GT radians(GT degrees)	Wandelt Grad in Radianten um
GT degrees(GT radians)	Wandelt Radianten in Grad um
GT sin(GT angle)	Standard-Sinus
GT cos(GT angle)	Standardkosinus
GT tan(GT angle)	Standardtangente
GT asin(GT x)	Gibt einen Winkel zurück, dessen Sinus x ist, im Bereich von $ \left[-{\pi\over 2},{\pi\over 2}\right] $
GT acos(GT x)	Gibt einen Winkel zurück, dessen Kosinus x ist, im Bereich [0, π].
GT atan(GT y, GT x)	Gibt einen Winkel zurück, dessen trigonometrischer Arkustangens $ \left[{y\over x}\right] $ im Bereich $ \left[-\pi,\pi\right] $ ist.
GT atan(GT y_over_x)	Gibt einen Winkel zurück, dessen trigonometrischer Arkustangens y_over_x im Bereich von $ \left[-{\pi\over 2},{\pi\over 2}\right] $ ist.

Exponentialfunktionen

Funktion	Beschreibung
GT pow(GT x, GT y)	Gibt $ x^y $ zurück
GT exp(GT x)	Gibt $ e^x $ zurück
GT log(GT x)	Gibt $ ln(x) $ zurück
GT exp2(GT x)	Gibt 2 hoch x zurück.
GT log2(GT x)	Gibt den Wert $ log_2(x) $ zurück.
GT sqrt(GT x)	Gibt die Quadratwurzel von x zurück.
GT inversesqrt(GT x)	Gibt 1 ÷ Wurzel(x) zurück

Gängige Funktionen

Funktion	Beschreibung
GT abs(GT x)	Absoluter Wert
GT sign(GT x)	Gibt je nach Vorzeichen von x -1,0, 0,0 oder 1,0 zurück
GT floor(GT x)	Nächste ganze Zahl <= x
GT ceil(GT x)	Nächste ganze Zahl >= x
GT fract(GT x)	Gibt den Bruchteil von x zurück
GT mod(GT x, GT y)	Gibt den Wert von x modulo y zurück
GT mod(GT x, float y)	Gibt den Wert von x modulo y zurück
GT min(GT x, GT y)	Gibt den Mindestwert von x oder y zurück
GT min(GT x, float y)	Gibt den Mindestwert von x oder y zurück
GT max(GT x, GT y)	Gibt den Höchstwert von x oder y zurück
GT max(GT x, float y)	Gibt den Höchstwert von x oder y zurück
GT clamp(GT x, GT minVal, GT maxVal)	Gibt x zurück, das zwischen minVal und maxVal begrenzt ist.
GT clamp(GT x, float minVal, float maxVal)	Gibt x zurück, das zwischen minVal und maxVal begrenzt ist.
GT saturate(GT x)	Gibt x zurück, begrenzt auf 0,0 und 1,0.
GT mix(GT x, GT y, GT a)	Gibt eine lineare Mischung aus x und y zurück
GT mix(GT x, GT y, float a)	Gibt eine lineare Mischung aus x und y zurück
GT step(GT edge, GT x)	Gibt 0,0 zurück, wenn x < edge, andernfalls 1,0.
GT step(float edge, GT x)	Gibt 0,0 zurück, wenn x < edge, andernfalls 1,0.
GT smoothstep(GT edge0, GT edge1, GT x)	Führt eine Hermite-Interpolation zwischen 0 und 1 aus, wenn edge0 < x < edge1
GT smoothstep(float edge0, float edge1, GT x)	Führt eine Hermite-Interpolation zwischen 0 und 1 aus, wenn edge0 < x < edge1

Geometrische Funktionen

Diese Funktionen arbeiten nicht komponentenweise, sondern auf Vektoren als Ganzes. GT ist ein Float-/Halbvektor der Größe 2–4.

Funktion	Beschreibung
float/half length (GT x)	Gibt die Länge des Vektors zurück
float/half distance(GT p0, GT p1)	Gibt die Entfernung zwischen Punkten zurück
float/half dot(GT x, GT y)	Skalarprodukt zurückgeben
float3/half3 cross(float3/half3 x, float3/half3 y)	Rückgaben – produktübergreifend
GT normalize(GT x)	Vektor auf Länge 1 normalisieren
GT faceforward(GT N, GT I, GT Nref)	Gibt N zurück, wenn „dot(Nref, I)“ < 0 ist, andernfalls -N.
GT reflect(GT I, GT N)	Reflexionsrichtung I – 2 * Skalarprodukt(N,I) * N.
GT refract(GT I, GT N, float/half eta)	Gibt den Brechungsvektor zurück

Matrixfunktionen

„Typ mat“ ist ein beliebiger quadratischer Matrixtyp.

Funktion	Beschreibung
mat matrixCompMult(mat x, mat y)	Komponentenweise Multiplikation von x mit y
mat inverse(mat m)	Gibt die Umkehrfunktion von m zurück.

Vektorrelationale Funktionen

Vergleichen Sie die Komponenten x und y. Die Größe der Eingabe- und Rückgabevektoren für einen bestimmten Aufruf muss übereinstimmen. T ist die Vereinigung von Ganzzahl- und Gleitkommavektortypen. BV ist ein boolescher Vektor, der der Größe der Eingabevektoren entspricht.

Funktion	Beschreibung
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)	true, wenn eine Komponente von x true ist
bool all(BV x)	true, wenn alle Komponenten von x true sind.
BV not(BV x)	logisches Komplement von x

Farbfunktionen

Funktion	Beschreibung
vec4 unpremul(vec4 color)	Wandelt den Farbwert in einen nicht vormultiplizierten Alphawert um.
half3 toLinearSrgb(half3 color)	Farbraumtransformation in linearen sRGB
half3 fromLinearSrgb(half3 color)	Farbraumtransformation

Shader-Sampling (Bewertung)

Samplertypen werden nicht unterstützt, Sie können aber andere Shader verwenden. Wenn Sie eine Textur stichprobenartig verwenden möchten, können Sie ein BitmapShader-Objekt erstellen und es als Uniform hinzufügen. Das ist für jeden Shader möglich. Sie können also jeden Android-Shader direkt auswerten, ohne ihn zuerst in eine Bitmap umzuwandeln, einschließlich anderer RuntimeShader-Objekte. Das bietet eine enorme Flexibilität, aber komplexe Shader können teuer in der Auswertung sein, insbesondere in einer Schleife.

uniform shader image;

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

Stichprobenerhebung aus dem Rohbuffer

Die meisten Bilder enthalten Farben, die farbkalibriert werden sollten. Einige Bilder enthalten jedoch keine Farben, sondern Daten wie Normalen, Materialeigenschaften (z. B. Rauheit), Höhenkarten oder andere rein mathematische Daten, die in einem Bild gespeichert sind. Wenn Sie diese Art von Bildern in AGSL verwenden, können Sie einen BitmapShader als generischen Rohbuffer mit RuntimeShader#setInputBuffer verwenden. So werden Farbraumtransformationen und -filter vermieden.