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 es posible, esta documentación intenta señalar las diferencias entre AGSL y GLSL.

Tipos

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

Tipos básicos

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

Precisión y mínimos de 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 admiten ES 3.0, tendrán una precisión o un rango de highp y un rango de int mediump más garantizados. Los modificadores de precisión se pueden aplicar a variables y parámetros escalares, vectoriales y matriciales. Solo se garantizan los mínimos que se indican a continuación. lowp no tiene necesariamente una precisión menor que mediump, y mediump no tiene necesariamente una precisión menor que highp. Actualmente, AGSL convierte lowp en mediump en el resultado final.

Modificador	Rango de "float"	Rango de magnitud "float"	Precisión de "float"	Rango "int"
highp	\(\left\{-2^{62},2^{62}\right\}\)	\(\left\{2^{-62},2^{62}\right\}\)	Relativo: \(2^{-16}\)	\(\left\{-2^{16},2^{16}\right\}\)
mediump	\(\left\{-2^{14},2^{14}\right\}\)	\(\left\{2^{-14},2^{14}\right\}\)	Relativo: \(2^{-10}\)	\(\left\{-2^{10},2^{10}\right\}\)
lowp	\(\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, p. ej., 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: Úsalo cuando accedas a vectores que representen puntos o normales.

vect.rgba: Úsalo cuando accedas a vectores que representen colores.

vect.LTRB: Úsalo cuando el vector represente un rectángulo (no en GLSL).

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

Estructuras y arrays

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

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

Solo se admiten arrays de 1 dimensión con un tamaño de array explícito, con sintaxis de estilo C o GLSL:

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

Nombre de la variable <base type>[<array size>] (p. ej., half x[10];)

Los arrays no se pueden mostrar desde una función, copiar, asignar ni comparar. Las restricciones de arrays se propagan a las estructuras que contienen arrays. Los arrays solo se pueden indexar con una constante o una variable de bucle.

Clasificatorios

Nota: No se admiten attribute, varying ni invariant.

Tipo	Descripción
const	Constante del tiempo de compilación o parámetro de función de solo lectura
uniform	El valor no cambia en la primitiva que se está procesando. Los uniformes se pasan desde Android con 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. Debe 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 explícito con llaves. No se permite la declaración de y en el siguiente ejemplo:

if (condition)
    int y = 0;

Conceptos básicos de matrices, estructuras y arrays

Ejemplos de constructores de matrices

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

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

Ten en cuenta que, a diferencia de GLSL, no se admiten los constructores que reducen la cantidad de componentes de un vector pasado, pero puedes usar el intercambio para obtener 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 de 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 matriz

Accede a los componentes de una matriz con la 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 campos de estructura con el operador de período .. Entre los operadores, se incluyen los siguientes:

Operador	Descripción
.	selector de campos
==, !=	igualdad
=	tarea

Elementos de array

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

diffuseColor += lightIntensity[3] * NdotL;

Operadores

Se numeran en orden de precedencia. Los operadores relacionales y de igualdad > < <= >= == != se evalúan como un valor booleano. Para comparar vectores por componente, usa funciones como lessThan(), equal(), etcétera.

	Operador	Descripción	Asociatividad
1	()	agrupación entre paréntesis	N/A
2	[] () . ++ --	Llamada a función de subíndice de array y selector de campo o método de estructura de constructor, incremento y decremento postfijo de intercambio	Izquierda a derecha
3	++ -- + - !	prefijo incremento y decremento unario	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	&&	Y lógico	Izquierda a derecha
13	^^	XOR lógico	Izquierda a derecha
14	||	O lógico	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	,	secuencia	Izquierda a derecha

Operaciones con matrices y vectores

Cuando se aplican a valores escalares, los operadores aritméticos generan un valor escalar. Para operadores distintos del 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 genera el mismo tipo de vector o matriz. Si ambas operaciones son vectores del mismo tamaño, la operación se realiza por componente (y muestra el mismo tipo de vector).

Operación	Descripción
m = f * m	Multiplicación de matrices por un valor escalar por componente
v = f * v	Multiplicación de vectores por un valor escalar por componente
v = v * v	Multiplicación de vectores por componentes por un valor de vector
m = m + m	Adición de componentes de matrices
m = m - m	Resta de componentes de matrices
m = m * m	Multiplicación algebraica lineal

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

Operación	Descripción
m = v * m	Multiplicación algebraica lineal de vector de fila por matriz
m = m * v	Multiplicación algebraica lineal de matriz × vector de columna

Usa las funciones integradas para el producto escalar de vectores, el producto cruzado y la multiplicación por componentes:

Función	Descripción
f = dot(v, v)	Producto punto de vectores
v = cross(v, v)	Producto vectorial cruzado
m = matrixCompMult(m, m)	Multiplicación por componente

Control de programas

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

Limitaciones del bucle for

Al igual que en GLSL ES 1.0, los bucles “for” son bastante limitados; el compilador debe poder desenrollar el bucle. Esto significa que el inicializador, la condición de prueba y la sentencia next deben usar constantes para que todo se pueda calcular en el momento de la 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, half4.

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

Ángulos y funciones trigonométricas

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

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 arctangente 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 arctangente 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)	Devuelve $ x^y $
GT exp(GT x)	Devuelve $ e^x $
GT log(GT x)	Devuelve $ ln(x) $
GT exp2(GT x)	Devuelve $ 2^x $
GT log2(GT x)	Devuelve $ log_2(x) $
GT sqrt(GT x)	Devuelve $ \sqrt{x} $
GT inversesqrt(GT x)	Devuelve $ 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)	Muestra la parte fraccionaria de x.
GT mod(GT x, GT y)	Muestra el valor de x módulo y.
GT mod(GT x, float y)	Muestra el valor de x módulo y.
GT min(GT x, GT y)	Muestra el valor mínimo de x o y.
GT min(GT x, float y)	Muestra el valor mínimo de x o y.
GT max(GT x, GT y)	Muestra el valor máximo de x o y.
GT max(GT x, float y)	Muestra 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 limitado entre 0.0 y 1.0.
GT mix(GT x, GT y, GT a)	Muestra una combinación lineal de x e y.
GT mix(GT x, GT y, float a)	Muestra una combinación lineal de x e y.
GT step(GT edge, GT x)	Muestra 0.0 si x < edge, de lo contrario, 1.0.
GT step(float edge, GT x)	Muestra 0.0 si x < edge, de lo contrario, 1.0.
GT smoothstep(GT edge0, GT edge1, GT x)	Realiza la interpolación de Hermite entre 0 y 1 cuando edge0 < x < edge1.
GT smoothstep(float edge0, float edge1, GT x)	Realiza la interpolación de Hermite entre 0 y 1 cuando edge0 < x < edge1.

Funciones geométricas

Estas funciones operan en vectores como vectores, no por componentes. GT son vectores de punto flotante o medio en tamaños de 2 a 4.

Función	Descripción
float/half length (GT x)	Muestra la longitud del vector.
float/half distance(GT p0, GT p1)	Muestra la distancia entre puntos
float/half dot(GT x, GT y)	Devuelve el producto punto
float3/half3 cross(float3/half3 x, float3/half3 y)	Devolución de producto cruzado
GT normalize(GT x)	Normaliza el vector a 1 de longitud
GT faceforward(GT N, GT I, GT Nref)	Muestra N si dot(Nref, I) < 0, de lo contrario, -N.
GT reflect(GT I, GT N)	Dirección de reflexión I - 2 * producto punto(N,I) * N.
GT refract(GT I, GT N, float/half eta)	Devuelve el 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)	Multiplica x por y por componente
mat inverse(mat m)	Muestra la inversa de m.

Funciones relacionales de vectores

Compara x e y por componente. Los tamaños de los vectores de entrada y devueltos para una llamada en particular deben coincidir. T es la unión de los tipos de vectores de números enteros y de 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)

No se admiten los tipos de sampler, pero puedes evaluar otros sombreadores. Si necesitas muestrear una textura, puedes crear un objeto BitmapShader y agregarlo como uniforme. Puedes hacerlo para 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 cantidad de flexibilidad, pero los sombreadores complejos pueden ser costosos de evaluar, en especial 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, algunas contienen datos que no son realmente colores, incluidas las imágenes que almacenan normales, propiedades de material (p.ej., rugosidad), mapas de altura o cualquier otro dato puramente matemático que se almacena en una imagen. Cuando usas estos tipos de imágenes en AGSL, puedes usar un BitmapShader como un búfer sin procesar genérico con RuntimeShader#setInputBuffer. Esto evitará las transformaciones y el filtrado del espacio de color.