Android Graphics Shading Language (AGSL)
Stay organized with collections
Save and categorize content based on your preferences.
Android Graphics Shading Language (AGSL) is used by Android 13 and above to
define the behavior of programmable
RuntimeShader objects. AGSL
shares much of its syntax with GLSL fragment shaders, but works within the
Android graphics rendering system to both customize painting within Canvas
and filter View content.
Theory of operation
AGSL effects exist as part of the larger Android graphics pipeline. When Android
issues a GPU accelerated drawing operation, it assembles a single GPU fragment
shader to do the required work. This shader typically includes several pieces.
For example, it might include:
- Evaluating whether a pixel falls inside or outside of the shape being drawn
(or on the border, where it might apply anti-aliasing).
- Evaluating whether a pixel falls inside or outside of the clipping region
(again, with possible anti-aliasing logic for border pixels).
- Logic for the
Shader
on the Paint. The
Shader can actually be a tree of objects (due to
ComposeShader
and other features described below).
- Similar logic for the
ColorFilter.
- Blending code (for certain types of
BlendMode).
- Color space conversion code, as part of Android's color management.
- When the
Paint has a complex tree of objects in the Shader,
ColorFilter, or BlendMode fields, there is still only a single GPU fragment
shader. Each node in that tree creates a single function. The clipping code and
geometry code each create a function. The blending code might create a function.
The overall fragment shader then calls all of these functions (which may call
other functions, e.g. in the case of a shader tree).
Your AGSL effect contributes a function (or functions) to the GPU’s fragment shader.
Basic syntax
AGSL (and GLSL) are C-style domain specific languages. Types such as bool and
int closely track their C equivalents; there are additional types to
support vectors and matrices that support domain functionality.
Qualifiers can be applied to types for precision hints in a way that's unique to shading languages. Control structures such as if-else statements work much
like they do in C; the language also provides support for switch statements
and for loops with limitations. Some control structures require constant expressions that can be evaluated at compile time.
AGSL supports functions; every shader program begins with the main function.
User defined functions are supported, without support for recursion of any kind.
Functions use a "value-return" calling convention; values passed to functions are
copied into parameters when the function is called, and outputs are copied
back; this is determined by the in, out, and inout qualifiers.
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-02-22 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-02-22 UTC."],[],[],null,["# Android Graphics Shading Language (AGSL) is used by Android 13 and above to\ndefine the behavior of programmable\n[`RuntimeShader`](/reference/android/graphics/RuntimeShader) objects. AGSL\nshares much of its syntax with GLSL fragment shaders, but works within the\nAndroid graphics rendering system to both customize painting within `Canvas`\nand filter `View` content.\n\nTheory of operation\n-------------------\n\nAGSL effects exist as part of the larger Android graphics pipeline. When Android\nissues a GPU accelerated drawing operation, it assembles a single GPU fragment\nshader to do the required work. This shader typically includes several pieces.\nFor example, it might include:\n\n- Evaluating whether a pixel falls inside or outside of the shape being drawn (or on the border, where it might apply anti-aliasing).\n- Evaluating whether a pixel falls inside or outside of the clipping region (again, with possible anti-aliasing logic for border pixels).\n- Logic for the [`Shader`](/reference/android/graphics/Shader) on the [`Paint`](/reference/android/graphics/Paint). The Shader can actually be a tree of objects (due to [`ComposeShader`](/reference/android/graphics/ComposeShader) and other features described below).\n- Similar logic for the [`ColorFilter`](/reference/android/graphics/ColorFilter).\n- Blending code (for certain types of [`BlendMode`](/reference/android/graphics/BlendMode)).\n- Color space conversion code, as part of Android's color management.\n- When the `Paint` has a complex tree of objects in the `Shader`, `ColorFilter`, or `BlendMode` fields, there is still only a single GPU fragment shader. Each node in that tree creates a single function. The clipping code and geometry code each create a function. The blending code might create a function. The overall fragment shader then calls all of these functions (which may call other functions, e.g. in the case of a shader tree).\n\nYour AGSL effect contributes a function (or functions) to the GPU's fragment shader.\n\nBasic syntax\n------------\n\nAGSL (and GLSL) are C-style domain specific languages. Types such as `bool` and\n`int` closely track their C equivalents; there are additional types to\nsupport vectors and matrices that support domain functionality.\n\nQualifiers can be applied to types for precision hints in a way that's unique to shading languages. Control structures such as `if-else` statements work much\nlike they do in C; the language also provides support for `switch` statements\nand `for` loops with limitations. Some control structures require constant expressions that can be evaluated at compile time.\n\nAGSL supports functions; every shader program begins with the `main` function.\nUser defined functions are supported, without support for recursion of any kind.\nFunctions use a \"value-return\" calling convention; values passed to functions are\ncopied into parameters when the function is called, and outputs are copied\nback; this is determined by the `in`, `out`, and `inout` qualifiers."]]
