AGSL Quick Reference

AGSL is designed to be largely compatible with GLSL ES 1.0. For more information, see the equivalent function in the OpenGL ES Shading Language documentation. When possible, this documentation attempts to call out differences between AGSL and GLSL.

Types

AGSL supports GLSL ES 1.0 types along with an additional way to represent vector and matrix types. AGSL supports additional short and half types to represent medium precision.

Basic types

Precision and range minimums

These are the minimum guaranteed precision and range associated with each modifier based upon the OpenGL ES 2.0 specification. Since most devices support ES 3.0, they will have more guaranteed highp precision/range and int mediump range. Precision modifiers can be applied to scalar, vector, and matrix variables and parameters. Only the minimums listed below are guaranteed; lowp is not necessarily actually lower precision than mediump, and mediump is not necessarily lower precision than highp. AGSL currently converts lowp to mediump in the final output.

In addition to array numeric subscript syntax 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 - Use when accessing vectors that represent points/normals

vect.rgba - Use when accessing vectors that represent colors

vect.LTRB - Use when the vector represents a rectangle (not in GLSL)

In AGSL, 0 and 1 can be used to produce a constant 0 or 1 in that channel. Ex: vect.rgb1 == vec4(vect.rgb,1)

Structures and arrays

Structures are declared with the same syntax as GLSL, but AGSL only supports structures at global scope.

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

Only 1-dimensional arrays are supported with an explicit array size, using either C-style or GLSL style syntax:

<base type>[<array size>] variable name - ex: half[10] x;

<base type> variable name[<array size>] - ex: half x[10];

Arrays cannot be returned from a function, copied, assigned or compared. Array restrictions propagate out to structures containing arrays. Arrays can only be indexed using a constant or a loop variable.

Qualifiers

Variable declaration

Declarations must be in an explicit braced scope. The declaration of y in the following sample is disallowed:

if (condition)
    int y = 0;

Matrix/structure/array basics

Matrix constructor examples

When a matrix is constructed with a single value, all values along the diagonal are given that value, while the rest are given zeros. float2x2(1.0) would therefore create a 2x2 identity matrix.

When a matrix is constructed with multiple values, columns are filled first (column-major order).

Note that, unlike GLSL, constructors that reduce the number of components of a passed-in vector are not supported, but you can use swizzling to have the same effect. To construct a vec3 from a vec4 in AGSL with the same behavior as GLSL, specify vec3 nv = quadVec.xyz.

Structure constructor example

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

Matrix components

Access components of a matrix with array subscripting syntax.

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

Structure fields

Select structure fields using the period . operator. Operators include:

Array elements

Array elements are accessed using the array subscript operator [ ]. For example:

diffuseColor += lightIntensity[3] * NdotL;

Operators

Numbered in order of precedence. The relational and equality operators > < <= >= == != evaluate to a Boolean. To compare vectors component-wise, use functions such as lessThan(), equal(), etc.

Matrix and vector operations

When applied to scalar values, the arithmetic operators result in a scalar. For operators other than modulo, if one operand is a scalar and the other is a vector or matrix, the operation is performed componentwise and results in the same vector or matrix type. If both operations are vectors of the same size, the operation is performed componentwise (and returns the same vector type).

If one operand is a vector matching the row or column size of our matrix, the multiplication operator can be used to do algebraic row and column multiplication.

Use the built-in functions for vector dot product, cross product, and component-wise multiplication:

Program control

For loop limitations

Similar to GLSL ES 1.0, 'for' loops are quite limited; the compiler must be able to unroll the loop. This means that the initializer, the test condition, and the next statement must use constants so that everything can be computed at compile time. The next statement is further limited to using ++, --, +=, or -=.

Built-in functions

GT (generic type) is float, float2, float3, float4 or half, half2, half3, half4.

Most of these functions operate component-wise (the function is applied per-component). It's noted when that is not the case.

Angle & trigonometric functions

Function parameters specified as an angle are assumed to be in units of radians. In no case will any of these functions result in a divide by zero error. If the divisor of a ratio is 0, then results will be undefined.

Exponential functions

Common functions

Geometric functions

These functions operate on vectors as vectors, not component-wise. GT is float/half vectors in sizes 2-4.

Matrix functions

Type mat is any square matrix type.

Vector relational functions

Compare x and y component-wise. Sizes of input and return vectors for a particular call must match. T is the union of integer and floating point vector types. BV is a boolean vector that matches the size of the input vectors.

Color functions

Shader sampling (evaluation)

Sampler types aren't supported, but you can evaluate other shaders. If you need to sample a texture, you can create a BitmapShader object, and add it as a uniform. You can do this for any shader, which means you can directly evaluate any Android Shader without turning it into a Bitmap first, including other RuntimeShader objects. This allows for a huge amount of flexibility, but complex shaders can be expensive to evaluate, particularly in a loop.

uniform shader image;

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

Raw buffer sampling

Although most images contain colors that should be color-managed, some images contain data that isn’t actually colors, including images storing normals, material properties (e.g., roughness), heightmaps, or any other purely mathematical data that happens to be stored in an image. When using these kinds of images in AGSL, you can use a BitmapShader as a generic raw buffer using RuntimeShader#setInputBuffer. This will avoid color space transformations and filtering.