Shaders

Shaders in Heirloom are written in GLSL. They are almost 100% vanilla GLSL but have been extended to support an #include directive. A standard include is expected for shaders to work correctly. They are standard/standard.vert or standard/standard.frag. This provides the correct input/output, uniforms and structures of each shader stage as well as the standard shader library.

This guide assumes you have some existing GLSL knowledge.

Default Shaders

The default shaders used in Heirloom are the following:

default.vert

#include "standard/standard.vert"

vec2 vertexProgram(vec2 position)
{
	// simple pass-through
	return position;
}

default.frag

#include "standard/standard.frag"

vec4 fragmentProgram(vec4 color) 
{
	// simple pass-through
	return color;
}

Example Shader

The following is a simple "invert color" shader.

#include "standard/standard.frag"

vec4 fragmentProgram(vec4 color) 
{ 
	// Invert RGB values
	return vec4(1.0 - color.rgb, color.a);
}

Another simple example, a distortion shader. This time uses an image and a time uniform.

#include "standard/standard.frag"

uniform sampler2D uNoiseImage;
uniform vec4      uNoiseImage_UVRect;

uniform float uTime;

vec4 fragmentProgram(vec4 color) 
{
	vec2 offset = atlas(uNoiseImage, uNoiseImage_UVRect, vec2(uTime / 5.0, uTime / 2.0) + frag.uv).xy * 2.0 - 1.0;
	return atlas(uMainImage, uMainImage_UVRect, frag.uv + offset * 0.05);
}

Note: In the example above, recognize the uniform uNoiseImage_UVRect. The _UVRect is a necessary part of sampling images in Heirloom as images are automatically packed into a texture atlas. The _UVRect uniforms are automatically populated when the sampler uniform is set in the application.

distort.SetUniform("uNoiseImage", myNoiseImage);
// uNoiseImage_UVRect was automatically set above

Standard Library

vec4 atlas(sampler2D img, vec4 rect, vec2 uv)

Samples the texture img with atlas encoding rectangle rect.

vec4 luminance(vec3 rgb)

Computes the luminance (grayscale) value of the input color.

Uniforms

Not all GLSL uniform types are backed by a type within Heirloom. The following describes the types that can be used to update a uniform variable.

Note: Uniform blocks are currently not supported or exposed by any API in Heirloom. Future versions may expose this functionality.

Basic Types

• Float types
  • A float can be set with float
  • A vec2 can be set with Vector, float[2]
  • A vec3 can be set with float[3]
  • A vec4 can be set with Rectangle, Color or float[4]
• Integer types
  • A int can be set with int
  • A ivec2 can be set with IntVector or int[2]
  • A ivec3 can be set with int[3]
  • A ivec4 can be set with IntRectangle, ColorBytes or int[4]
• Unsigned Integer types
  • A uint can be set with uint
  • A uvec2 can be set with uint[2]
  • A uvec3 can be set with uint[3]
  • A uvec4 can be set with uint[4]
• Boolean types
  • A bool can be set with bool or int
  • A bvec2 can be set with bool[2]
  • A bvec3 can be set with bool[3]
  • A bvec4 can be set with bool[4]
• Matrix
  • A mat2x3 can be set with Matrix
  • All other matrix types can be set with float[]
• Sampler types
  • A sampler2D can be set with Image or Surface
  • All other sampler types have no representation

Arrays

Arrays of the above GLSL type are just the one-dimensional array form of the above. If you have a uniform of vec4[8] for a list of 8 colors, you can provide Color[8] or float[32].