.shader

From TargetWiki

Contents 1 Shader Development 2 File Layout 3 Shaders 4 Uniforms

Shader Development

If you want to create a shader, then understand that it is not easy and unlike creating a texture. For a starter have a look over this web site, http://www.lighthouse3d.com/opengl/glsl/, which seems to go through the process well. Also http://www.janwalter.com/ShaderWriting/Filmakademie/filmakademie.html for how to write your own.

It is likely that a small number of shaders will be developed by mods, and shared across the communitity, where appropiate.

File Layout

Example code:

  shaders =
  {
  	{
  		type = vertex
     		file = "ocean.vert"
  	}
  	
  	{
  		type = fragment
  		file = "ocean.frag"
  	}
  }
  
  uniforms =
  {
  	normal_map = 0
  	reflection = { 0.2, 0.4, 0.4 }
  	refraction = { 0.025, 0.1, 0.2 }
  }

Description:

A shader file is a standard TW2 configuration file. Shader files contain two things at the top level:

• A 'shaders' table.
• A 'uniforms' table.

The example above shows the ocean.shader from the intial release of TW2.

The shader, calls files which contain the detailed shader parameters. Shaders are a set of software instructions used to define the rendering effects via the hardware on the materials and thus models in game. For further information see [1].

These shaders are developed outside the TW2 environment and are not documented within this user guide.

A more complex example, showing the atmosphere.shader is below:

  transparent = true
  
  shaders =
  {
  	{
  		type = vertex
  		file = "atmosphere.vert"
  	}
  	
  	{
  		type = fragment
  		file = "atmosphere.frag"
  	}
  }
  
  uniforms =
  {
  	// wavelengths = { 0.650, 0.570, 0.475 }
  	// this is actually 1/pow( wavelengths, 4 )
  	wavelengths = { 5.602, 9.473, 19.644 }
  	rayleigh = 0.0025
  	mie = 0.0015
  	brightness = 15.0
  	surface_brightness = 2.0
  	average_density = 0.25
  	phase = -0.95
  }

The first line of the example above has the transparent setting defined, which sets the material as using the alpha channel. Wouldn;t be atmosphere if you couldn't see through it!

Default states:

No default, if defined it is used.

---

Shaders

The shaders table contains a collection of unnamed tables, each of which adds a shader program to the shader. Normally this will mean two entries: one for the vertex program and one for the fragment program.

Each entry contains the following values:

• type = string. This must be 'vertex' or 'fragment' and indicates whether the shader program being added is a vertex program or a fragment program.
• file = string. The name of the file to add.
• define = an optional table of zero or more strings.

The 'define' table is used to define preprocessor values in shaders. It can only do simple defines; that is, it cannot define a macro. For example, if the define table for a shader program looks like this:

define = { USE_SPSA, USE_CH2 }

Then the the file being added to the shader will be treated as if the following appeared at the beginning of the file:

#define USE_SPSA
#define USE_CH2

Uniforms

The uniform table sets uniform values in the shader. It consists of a set of strings, each of which can be assigned either a number or a table of up to 4 numbers. The numbers must either be all integers or all floating point numbers, depending on the type of the uniform value being set in the shader.

For example, take the following uniform table:

uniforms =
{
  test_vec = { 1.0, 0.5, 0.75 }
}

That would be used to initialise a shader uniform declared like this:

uniform vec3 test_vec;

It would set test_vec.x to 1.0, test_vec.y to 0.5 and test_vec.z to 0.75.

The uniform table can be used for many things, but the most common will be binding shader sampler variables to texture units.