Shaders in AGK

AGK uses shaders written in the OpenGL 2.0 Shading Language (GLSL version 110) on desktop platforms, and OpenGL ES 2.0 shaders on mobile platforms. Any shaders that you write yourself must be compatible with both desktop and mobile versions, thankfully OpenGL 2.0 and OpenGL ES 2.0 are almost identical in this regard. However you cannot use the "#version" definition sometimes used on desktop platforms, or the "precision highp float" definition sometimes used on mobile platforms, these will be added automatically by AGK.

Types of Shader

Everything in AGK requires a shader to appear on the screen, this includes sprites, text, and 3D objects. For 2D items it uses the same shader for everything to improve performance, but for 3D objects AGK will look at the object properties, such as the number of textures it uses, and create a shader for it. These are refered to as Default Shaders and are the most common way of displaying things in AGK, if you want to see the code that AGK created for an object you can use GetObjectMeshVSSource and GetObjectMeshPSSource, and use this as the basis for a Custom Shader.

Custom shaders are shaders that you write yourself and load into AGK, this is to cover use cases that AGK can't handle with its Default Shaders. These are loaded with LoadShader. Note that AGK will not check the suitablility of the shader for the objects it is applied to, so if your shader uses 2 textures, but the object only has 1 texture, then AGK won't warn you and the object may not render correctly.

Sprite shaders are loaded with LoadSpriteShader, which is a convenience function that loads a custom pixel shader but uses a standard vertex shader that is suitable for most sprites. If you wanted to modify the vertex shader you can use LoadShader and apply it to a sprite, but be aware that vertex shaders used for 3D objects will not work on sprites. The default sprite vertex shader looks like this

attribute highp vec4 position;
attribute mediump vec4 color;
attribute mediump vec2 uv;
varying mediump vec2 uvVarying;
varying mediump vec4 colorVarying;
uniform highp mat4 agk_Ortho;
 
void main() 
{
    gl_Position = agk_Ortho * position;
    uvVarying = uv;
    colorVarying = color;
}

The default pixel shader for sprites is

uniform sampler2D texture0;
varying mediump vec2 uvVarying;
varying mediump vec4 colorVarying;
 
void main()
{
    gl_FragColor = texture2D(texture0, uvVarying) * colorVarying;
}

Fullscreen shaders are loaded with LoadFullScreenShader, which is another convenience function that loads a custom pixel shader but uses a standard vertex shader that is suitable for full screen quads. Again you could modify the vertex shader by using LoadShader and applying it to a quad. The default quad vertex shader looks like this

attribute highp vec3 position;
varying mediump vec2 uvVarying;
uniform mediump vec4 uvBounds0;
uniform mediump float agk_invert; // used to correct for render images being inverted
 
void main() 
{
    gl_Position = vec4(position.xy*vec2(1.0,agk_invert),0.5,1.0);
    uvVarying = (position.xy*vec2(0.5,-0.5) + 0.5) * uvBounds0.xy + uvBounds0.zw;
}

The default pixel shader for fullscreen quads does nothing to the image and looks like this

uniform sampler2D texture0;
varying mediump vec2 uvVarying;
 
void main()
{
    gl_FragColor = texture2D(texture0, uvVarying);
}

All the shaders so far form what is called a Base Shader, telling AGK about the known attributes, such as number of textures. However there are unknown factors like the number of lights affecting the object that need to be in the shader, but which you don't always know in advance. As such AGK takes the given Base Shader and creates what we call a Generated Shader, which fills in any missing details before using it to draw. Typically this only applies to 3D objects which have a variable numbers of lights shining on them at any one time. Generated Shaders are temporary and may be thrown away if the scene changes, always using the given Base Shader to create a suitable Generated Shader for the current scene. This does mean that if the Base Shader is a Default Shader, then AGK is actually doing two rounds of shader creation, firstly to create the Default Shader and then using that as a base to create the Generated Shader. Using GetObjectMeshVSSource and GetObjectMeshPSSource will only ever return the Base Shader, never the Generated Shader, as these can change frequently and are scene dependent.

When writing a Custom Shader it is useful to know how the shader creation process works so you can tell AGK what you want, or don't want, to be in the final Generated Shader. You can also exclude everything, in which case AGK will recognise there is nothing to add and will use your Custom Shader directly to draw the object, skipping the whole Generated Shader path. This is done by using none of the functions from the next section.

Generated Shaders

There are currently three additional elements that AGK adds dynamically to shaders, these are Vertex Lighting, Pixel Lighting, and Fog. These are added if a particular function is declared in the shader, if the function is not declared then that element is not added. For example the function for vertex lighting is

mediump vec3 GetVSLighting( mediump vec3 normal, highp vec3 pos );

If this function is declared anywhere in the vertex shader then AGK will add a definition for the function before using it to draw an object. Its contents will vary depending on how many vertex lights affect that object. The function declaration must appear exactly as above, with the same spacing and case, for it to be detected. A custom vertex shader that uses this function might look like this

attribute highp vec3 position;
attribute mediump vec3 normal;
attribute mediump vec2 uv;
 
varying highp vec3 posVarying;
varying mediump vec3 normalVarying;
varying mediump vec2 uvVarying;
varying mediump vec3 lightVarying;
 
uniform highp mat3 agk_WorldNormal;
uniform highp mat4 agk_World;
uniform highp mat4 agk_ViewProj;
uniform mediump vec4 uvBounds0;
 
mediump vec3 GetVSLighting( mediump vec3 normal, highp vec3 pos );
 
void main()
{ 
    uvVarying = uv * uvBounds0.xy + uvBounds0.zw;
    highp vec4 pos = agk_World * vec4(position,1.0);
    gl_Position = agk_ViewProj * pos;
    mediump vec3 norm = normalize(agk_WorldNormal * normal);
    posVarying = pos.xyz;
    normalVarying = norm;
    lightVarying = GetVSLighting( norm, posVarying );
}

Note the GetVSLighting function is declared but not defined, AGK will define it at runtime. In this case the lighting information is passed directly to the pixel shader, but you can do anything you like to the value. The GetVSLighting function makes no changes to any global values, it only returns a value. Also note that the call to GetVSLighting must occur after setting the gl_Position value, the lighting function makes use of this value.

The function for pixel lighting looks like this

mediump vec3 GetPSLighting( mediump vec3 normal, highp vec3 pos );

and the function for fog is

mediump vec3 ApplyFog( mediump vec3 color, highp vec3 pointPos );

Again they must appear exactly as above, with the same spacing and case. A pixel shader that uses both pixel lighting and fog might look like this

uniform sampler2D texture0;
 
varying highp vec3 posVarying;
varying mediump vec3 normalVarying;
varying mediump vec2 uvVarying;
varying mediump vec3 lightVarying;
 
mediump vec3 GetPSLighting( mediump vec3 normal, highp vec3 pos );
mediump vec3 ApplyFog( mediump vec3 color, highp vec3 pointPos );
 
void main()
{ 
    mediump vec3 norm = normalize(normalVarying);
    mediump vec3 light = lightVarying + GetPSLighting( norm, posVarying ); 
    
    mediump vec3 color = texture2D(texture0, uvVarying).rgb * light;
    color = ApplyFog( color, posVarying );
    
    gl_FragColor = vec4(color,1.0);
}

In this case we receive the lighting from the vertex shader in the lightVarying variable then add the pixel shader lighting to make up the final light value. You can use these values for any purpose, as mentioned earlier the lighting functions do not modify any global state, they only return a value. The same applies to fog.

If you wish your object to use lighting then it is recommended that you use both the vertex and pixel lighting functions unless you can be sure that all the lights will be of a particular type (vertex or pixel). Note that the global directional light (sun) is handled in the vertex shader function.

The fog function takes the desired pixel color and the pixel position in the world and returns a new color for this pixel based on the amount of fog it received. The fog function is only valid in the pixel shader, and will be ignored if placed in the vertex shader. If you turn off fog in AGK then the fog function will be removed from the shader to improve performance. It will be re-added if you turn fog back on.

AGK Shader Variables

AGK will recognise certain variable names in shaders and fill them with useful values that you can use in your shaders. Here is a list of the variables and a description of what they represent

• vec3 agk_CameraPos = The world position of the current 3D camera
• float agk_invert = -1 if drawing to an image, 1 if drawing to the screen, only needed by quads
• float agk_time = The time in seconds, taken from the AGK Timer() command
• float agk_sintime = The sine of the time value, equivalent to Sin(Timer()) in AGK
• vec2 agk_resolution = The resolution of the current render target, image or window
• vec2 agk_spritepos = If the shader is being used to draw a sprite then this is its current position in world coordinates
• vec2 agk_spritesize = If the shader is being used to draw a sprite then this is its current size in world coordinates
• mat4 agk_Ortho = A matrix to transform sprites from 2D world space into window space
• mat4 agk_World = A matrix to transform 3D object verticies from object space to 3D world space
• mat3 agk_WorldNormal = A matrix to transform 3D object normals from object space to 3D world space
• mat4 agk_View = A matrix to transform from 3D world space to camera space
• mat4 agk_Proj = A matrix to transform from camera space to window space
• mat4 agk_ViewProj = A combination of the View and Proj matrices, transforms from 3D world space to window space
• mat4 agk_WorldViewProj = A combination of the World, View, and Proj matrices, transforms from object space to window space
• vec4 agk_MeshDiffuse = The color of the mesh being drawn, set with SetObjectColor
• vec4 agk_MeshEmmisive = The emissive color of the mesh being drawn, set with SetObjectColorEmissive

Variables must be declared with the same case as shown above, and can be used in either the vertex or pixel shader, or both. They must be preceeded by the uniform keyword. These will be updated every time the shader is used to drawn an item.

Shader Constants

You can declare your own shader variables using the uniform keyword and set them using the AGK commands SetShaderConstantByName and SetShaderConstantArrayByName, see the documentation for these commands to see the parameters they use. Setting a shader value using these commands will change it permanently for all draw calls until you change it to something else.

You can also set a shader value on a per object basis by using SetObjectShaderConstantByName and SetObjectShaderConstantArrayByName. In which case the shader will use this value when drawing the specified object, but return to the default value when drawing other objects. To return an object to using the the default use SetObjectShaderConstantDefault.

Shader Precision

You can set the precision of each variable in a shader using the keywords highp, mediump, lowp, and it is recommended you use them to get the right trade off between performance and accuracy. In general position values should use highp, whilst normals and UVs (or anything that will always use small float values) should use mediump. Color values can use lowp if they will always be in the range 0 to 1, if there is a chance they will go beyond this range then they should use mediump. By default AGK sets all vertex shader values to use highp and all pixel shader values to use mediump.