Referencia rápida de AGSL

AGSL está diseñado para ser altamente compatible con GLSL ES 1.0. Para obtener más información, consulta la función equivalente en la documentación de OpenGL ES Shading Language. Cuando sea posible, en esta documentación, se intentará destacar las diferencias entre AGSL y GLSL.

Tipos

AGSL admite tipos GLSL ES 1.0, además de una forma adicional de representar tipos de vectores y matrices. AGSL admite tipos short y half adicionales para representar la precisión media.

Tipos básicos

Tipo	Descripción
void	No hay ningún valor de función que se muestra ni una lista de parámetros vacía. A diferencia de GLSL, las funciones sin un tipo de datos que se muestra vacío deben mostrar un valor.
bool, bvec2, bvec3, bvec4 (bool2, bool3, bool4).	Escalar/vector booleano
int, ivec2, ivec3, ivec4 (int2, int3, int4)	Número entero/vector con firma highp
float, vec2, vec3, vec4 (float2, float3, float4)	highp (precisión simple) de punto flotante escalar/vectorial
short, short2, short3, short4	equivalente a mediump int de número entero o vector con firma
half, half2, half3, half4	equivalente a mediump float escalar/vector
mat2, mat3, mat4 (float2x2, float3x3, float4x4)	Matriz float de 2 x 2, 3 x 3, 4 x 4
half2x2, half3x3, half4x4	Equivale a los tipos de matriz mediump float

Mínimos de precisión y rango

Estos son la precisión y el rango mínimos garantizados asociados con cada modificador, según la especificación de OpenGL ES 2.0. Dado que la mayoría de los dispositivos son compatibles con ES 3.0, tienen una precisión/rango de highp más garantizadas y el rango de int mediump. Los modificadores de precisión se pueden aplicar a variables y parámetros escalares, vectoriales y de matriz. Solo se garantizan los mínimos enumerados a continuación; lowp no tiene necesariamente una precisión menor que mediump, y mediump no necesariamente tiene una precisión menor que highp. Actualmente, AGSL convierte lowp en mediump en la salida final.

Modificador	rango "flotante"	rango de magnitud "float"	precisión “flotante”	rango 'int'
agudo	\(\left\{-2^{62},2^{62}\right\}\)	\(\left\{2^{-62},2^{62}\right\}\)	Relativo: \(2^{-16}\)	\(\left\{-2^{16},2^{16}\right\}\)
medio	\(\left\{-2^{14},2^{14}\right\}\)	\(\left\{2^{-14},2^{14}\right\}\)	Relativo: \(2^{-10}\)	\(\left\{-2^{10},2^{10}\right\}\)
bajo	\(\left\{-2,2\right\}\)	\(\left\{2^{-8},2\right\}\)	Absoluto: \(2^{-8}\)	\(\left\{-2^{8},2^{8}\right\}\)

Además de la sintaxis de subíndice numérico del array, por ejemplo: 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: Se usa cuando se accede a vectores que representan puntos o valores normales.

vect.rgba: Se usa cuando se accede a vectores que representan colores.

vect.LTRB: Se usa cuando el vector representa un rectángulo (no en GLSL).

En AGSL, se pueden usar 0 y 1 para producir una constante 0 o 1 en ese canal. Ej.: vect.rgb1 == vec4(vect.rgb,1)

Estructuras y arreglos

Las estructuras se declaran con la misma sintaxis que GLSL, pero AGSL solo admite estructuras de alcance global.

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

Solo los arrays de una dimensión son compatibles con un tamaño de array explícito con sintaxis de estilo C o GLSL:

<tipo de base>[<array size>] nombre de la variable - p. ej.: half[10] x;

nombre de la variable <base type>[<array size>] - p. ej.: half x[10];

No se pueden mostrar los arrays de una función, ni se pueden copiar, asignar o comparar. Las restricciones de array se propagan a estructuras que contienen arrays. Los arrays solo se pueden indexar mediante una constante o una variable de bucle.

Clasificatorios

Tipo	Descripción
const	Constante de tiempo de compilación o parámetro de la función de solo lectura.
uniform	El valor no cambia en toda la primitiva que se procesa. Los uniformes se pasan desde Android con los métodos RuntimeShader para setColorUniform, setFloatUniform, setIntUniform, setInputBuffer y setInputShader.
in	Para los parámetros de función pasados. Es el valor predeterminado.
out	Para los parámetros de función pasados. Debe usar la misma precisión que la definición de la función.
inout	Para los parámetros que se pasan dentro y fuera de una función. Debes usar la misma precisión que la definición de la función.

Declaración de una variable

Las declaraciones deben estar en un alcance entre llaves explícito. No se permite la declaración de y en el siguiente ejemplo:

if (condition)
    int y = 0;

Conceptos básicos de matriz, estructura o array

Ejemplos de constructores de matrices

Cuando se construye una matriz con un solo valor, a todos los valores de la diagonal se les da ese valor, mientras que al resto se les dan ceros. Por lo tanto, float2x2(1.0) crearía una matriz de identidad de 2 × 2.

Cuando una matriz se construye con varios valores, las columnas se completan primero (orden de columna principal).

Ten en cuenta que, a diferencia de GLSL, no se admiten los constructores que reducen la cantidad de componentes de un vector transferido, pero puedes usar swizzling para tener el mismo efecto. Para construir un vec3 a partir de un vec4 en AGSL con el mismo comportamiento que GLSL, especifica vec3 nv = quadVec.xyz.

Ejemplo del constructor de estructura

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

Componentes de la matriz

Accede a los componentes de una matriz con sintaxis de subíndice de array.

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

Campos de estructura

Selecciona los campos de estructura con el operador del período .. Entre los operadores, se incluyen los siguientes:

Operador	Descripción
.	selector de campo
==, !=	igualdad
=	asignación

Elementos de array

Se accede a los elementos del array con el operador de subíndice de array [ ]. Por ejemplo:

diffuseColor += lightIntensity[3] * NdotL;

Operadores

Numeradas en orden de precedencia. Los operadores relacionales y de igualdad > < <= >= == != evalúan como booleano. Para comparar vectores en cuanto a componentes, usa funciones como lessThan(), equal(), etcétera.

	Operador	Descripción	Asociación
1	()	agrupación entre paréntesis	N/A
2	[] () . ++ --	subíndice de array llamada a función y estructura de constructor campo o selector de método selector de swzzle y disminución postfija	Izquierda a derecha
3	++ -- + - !	incremento y disminución de prefijo	Derecha a izquierda
4	* /	multiplicar y dividir	Izquierda a derecha
5	+ -	sumar y restar	Izquierda a derecha
7	< > <= >=	relacional	Izquierda a derecha
8	== !=	igualdad/desigualdad	Izquierda a derecha
12	&&	lógico AND	Izquierda a derecha
13	^^	XOR lógico	Izquierda a derecha
14	||	lógico OR	Izquierda a derecha
15	?\:	selección (un operando completo)	Izquierda a derecha
16	= += -= *= /=	asignación aritmética asignación aritmética asignación	Izquierda a derecha
17	,	sequence	Izquierda a derecha

Operaciones de matriz y vectores

Cuando se aplican a valores escalares, los operadores aritméticos dan como resultado un escalar. Para operadores que no sean de módulo, si un operando es un escalar y el otro es un vector o una matriz, la operación se realiza por componentes y da como resultado el mismo tipo de vector o matriz. Si ambas operaciones son vectores del mismo tamaño, la operación se realiza por componentes (y muestra el mismo tipo de vector).

Operación	Descripción
m = f * m	Multiplicación de matrices en cuanto a componentes por un valor escalar
v = f * v	Multiplicación de vectores por componentes por un valor escalar
v = v * v	Multiplicación de vectores por componentes por un valor de vector
m = m + m	Suma de componentes de la matriz
m = m - m	Resta de componentes de la matriz
m = m * m	Multiplicación algebraica lineal

Si un operando es un vector que coincide con el tamaño de fila o columna de nuestra matriz, se puede usar el operador de multiplicación para hacer una multiplicación algebraica de filas y columnas.

Operación	Descripción
m = v * m	Vector de fila * multiplicación algebraica lineal de matriz
m = m * v	Matriz * multiplicación algebraica lineal del vector de columna

Usa las funciones integradas para el producto vectorial, producto cruzado y multiplicación por componentes:

Función	Descripción
f = dot(v, v)	Producto escalar vectorial
v = cross(v, v)	Producto cruzado vectorial
m = matrixCompMult(m, m)	Multiplicación por componentes

Control de programas

Llamada a función	Llamada por valor de retorno
Iteración	for (<init>;<test>;<next>) { break, continue }
Selección	if ( ) { } if ( ) { } else { } switch () { break, case } (valor predeterminado del último caso)
Saltar	break, continue, return (no se permite descartar)
Entrada	half4 main(float2 fragCoord)

Para limitaciones de bucle

Al igual que GLSL ES 1.0, los bucles "for" son bastante limitados: el compilador debe poder desenrollar el bucle. Eso significa que el inicializador, la condición de prueba y la sentencia next deben usar constantes para que todo se pueda calcular en el tiempo de compilación. La sentencia next se limita aún más al uso de ++, --, +=, or -=.

Funciones integradas

GT (tipo genérico) es float, float2, float3, float4 o half, half2, half3 y half4.

La mayoría de estas funciones operan en cuanto a componentes (la función se aplica por componente). Se nota cuando no es así.

Ángulos y funciones trigonométricas

Se supone que los parámetros de una función especificados como un ángulo están en unidades de radianes. En ningún caso ninguna de estas funciones dará como resultado un error de división por cero. Si el divisor de una proporción es 0, los resultados serán indefinidos.

Función	Descripción
GT radians(GT degrees)	Convierte grados en radianes.
GT degrees(GT radians)	Convierte radianes en grados.
GT sin(GT angle)	Seno estándar
GT cos(GT angle)	Coseno estándar
GT tan(GT angle)	Tangente estándar
GT asin(GT x)	Muestra un ángulo cuyo seno es x en el rango de $ \left[-{\pi\over 2},{\pi\over 2}\right] $
GT acos(GT x)	Muestra un ángulo cuyo coseno es x en el rango de $ \left[0,\pi\right] $
GT atan(GT y, GT x)	Muestra un ángulo cuya arquitectura trigonométrica es $ \left[{y\over x}\right] $ en el rango de $ \left[-\pi,\pi\right] $.
GT atan(GT y_over_x)	Muestra un ángulo cuya arcotangente trigonométrica es y_over_x en el rango de $ \left[-{\pi\over 2},{\pi\over 2}\right] $

Funciones exponenciales

Función	Descripción
GT pow(GT x, GT y)	Muestra $ x^y $
GT exp(GT x)	Muestra $ e^x $
GT log(GT x)	Muestra $ ln(x) $
GT exp2(GT x)	Muestra $ 2^x $
GT log2(GT x)	Muestra $ log_2(x) $
GT sqrt(GT x)	Muestra $ \sqrt{x} $
GT inversesqrt(GT x)	Muestra $ 1\over{\sqrt{x}} $

Funciones comunes

Función	Descripción
GT abs(GT x)	Valor absoluto
GT sign(GT x)	Muestra -1.0, 0.0 o 1.0 según el signo de x
GT floor(GT x)	Número entero más cercano <= x
GT ceil(GT x)	Número entero más cercano >= x
GT fract(GT x)	Devuelve la parte fraccionaria de x.
GT mod(GT x, GT y)	Muestra un valor de x módulo y
GT mod(GT x, float y)	Muestra un valor de x módulo y
GT min(GT x, GT y)	Muestra un valor mínimo de x o y
GT min(GT x, float y)	Muestra un valor mínimo de x o y
GT max(GT x, GT y)	Devuelve el valor máximo de x o y.
GT max(GT x, float y)	Devuelve el valor máximo de x o y.
GT clamp(GT x, GT minVal, GT maxVal)	Muestra x restringido entre minVal y maxVal.
GT clamp(GT x, float minVal, float maxVal)	Muestra x restringido entre minVal y maxVal
GT saturate(GT x)	Muestra x restringido entre 0.0 y 1.0
GT mix(GT x, GT y GT a)	Muestra la combinación lineal de x e y
GT mix(GT x, GT y, float a)	Muestra la combinación lineal de x e y
GT step(GT edge, GT x)	Muestra 0.0 si x < borde, excepto 1.0
GT step(float edge, GT x)	Muestra 0.0 si x < borde, excepto 1.0
GT smoothstep(GT edge0, GT edge1, GT x)	Realiza una interpolación de Hermite entre 0 y 1 cuando borde0 < x < borde1
GT smoothstep(float edge0, float edge1, GT x)	Realiza una interpolación de Hermite entre 0 y 1 cuando borde0 < x < borde1

Funciones geométricas

Estas funciones operan en vectores como vectores, no en componentes. GT son vectores flotante/medios en tamaños 2-4.

Función	Descripción
float/half length (GT x)	Muestra la longitud del vector
float/half distance(GT p0, GT p1)	Devuelve la distancia entre puntos.
float/half dot(GT x, GT y)	Devuelve producto escalar
float3/half3 cross(float3/half3 x, float3/half3 y)	Devuelve productos cruzados
GT normalize(GT x)	Normalizar vector a una longitud de 1
GT faceforward(GT N, GT I, GT Nref)	Muestra N si punto(Nref, I) < 0, else -N.
GT reflect(GT I, GT N)	Dirección de reflexión I - 2 * punto(N,I) * N.
GT refract(GT I, GT N, float/half eta)	Muestra vector de refracción

Funciones de matriz

El tipo mat es cualquier tipo de matriz cuadrada.

Función	Descripción
mat matrixCompMult(mat x, mat y)	Multiplicar x por y a nivel de los componentes
mat inverse(mat m)	Muestra la inversa de m.

Funciones relacionales de vector

Comparar los componentes x e y. Los tamaños de los vectores de entrada y retorno de una llamada en particular deben coincidir. T es la unión de los tipos de vectores de número entero y punto flotante. BV es un vector booleano que coincide con el tamaño de los vectores de entrada.

Función	Descripción
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 si algún componente de x es true.
bool all(BV x)	true si todos los componentes de x son true.
BV not(BV x)	complemento lógico de x

Funciones de color

Función	Descripción
vec4 unpremul(vec4 color)	Convierte el valor de color en alfa no premultiplicado.
half3 toLinearSrgb(half3 color)	Transformación del espacio de color a SRGB lineal
half3 fromLinearSrgb(half3 color)	Transformación del espacio de color

Muestreo de sombreadores (evaluación)

Los tipos de sampler no son compatibles, pero puedes evaluar otros sombreadores. Si necesitas hacer un muestreo de una textura, puedes crear un objeto BitmapShader y agregarlo como uniforme. Puedes hacerlo con cualquier sombreador, lo que significa que puedes evaluar directamente cualquier sombreador de Android sin convertirlo primero en un Bitmap, incluidos otros objetos RuntimeShader. Esto permite una gran flexibilidad, pero puede ser costoso evaluar sombreadores complejos, especialmente en un bucle.

uniform shader image;

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

Muestreo de búfer sin procesar

Aunque la mayoría de las imágenes contienen colores que deben administrarse por color, algunas imágenes contienen datos que en realidad no son colores, incluidas las imágenes de almacenamiento normal, las propiedades de los materiales (p.ej., aspereza), mapas de altura o cualquier otro dato puramente matemático que esté almacenado en una imagen. Cuando usas este tipo de imágenes en AGSL, puedes usar un BitmapShader como búfer genérico sin procesar mediante RuntimeShader#setInputBuffer. Esto evitará las transformaciones del espacio de color y el filtrado.