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.
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
The default pixel shader for sprites is
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
The default pixel shader for fullscreen quads does nothing to the image and looks like this
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.
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
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
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
and the function for fog is
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
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 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
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.
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.
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.