View source for Shader Coding - Best Practices

{{WIP|Will be based on: http://www.mail-archive.com/flightgear-devel@lists.sourceforge.net/msg35934.html}}

== File Header ==
{{Note|It's a good idea to add a header to each shader detailing:
* filename
* purpose 
* license
* author
* rendering pipeline (rembrandt/default)
* description
<syntaxhighlight lang="glsl">
// -*- mode: C; -*-
// urban.frag
// Licence: GPL v2
// Author: Frederic Bouvier.
//  Adapted from the paper by F. Policarpo et al. : Real-time Relief Mapping on Arbitrary Polygonal Surfaces
//  Adapted from the paper and sources by M. Drobot in GPU Pro : Quadtree Displacement Mapping with Height Blending
</syntaxhighlight>
}}


== Supported GLSL Versions ==

{{Note|Be aware that we currently '''_DO_NOT_''' support glsl <nowiki>> 1.2x. Please don't mix '''glsl''' flavours: please stick to glsl 1.2x.(even though support for it is largely </nowiki>''deprecated''). The transition to OpenGL 3.0 / glsl <nowiki>>=1.3x is a very big undertaking, and not backward compatible. It is always a good idea to declare the expected GLSL version at the top of each file</nowiki>:
<syntaxhighlight lang="glsl">
#version 120
</syntaxhighlight>
}}

== Vertex Shaders ==

{{Note|For testing purposes, you can use a simple pass-through vertex shader:
<syntaxhighlight lang="glsl">
#version 120
void main(void) {
        gl_Position = ftransform();
}
</syntaxhighlight>
}}

== Fragment Shaders ==

{{Note|To check if your shader is working, use a trivial  shader like this one or just add the last line to the end of the shader, it should turn all pixels black:
<syntaxhighlight lang="glsl">
#version 120
void main() {
// turn all pixels into  black
gl_FragColor = vec4 (0.0,0.0,0.0,1.0);
}
</syntaxhighlight>
}}

{{Note|if4dnf: it's usually bad practice to do any kind of operations on gl_FragColor assignment. At most a vec4() swizzle is ''accepted'', although even that one is treated differently based on the platform (some assign a temporary variable, some don't). Do wahtever you need in a separate vec4 variable and just assign it's value to gl_FragColor at the end.}}

{{Note|If the fragment isn't running, there should be an error message in the log file (I wish they'd still be written to the console). Might be that the texture isn't defined in the supporting framework for instance - the shader assumed that it is available, but you need to declare it in the matching C++ code/effect file first.}}

{{Note|This is how you can make a pixel darker:
<syntaxhighlight lang="glsl">
gl_FragColor = color * 0.5;
</syntaxhighlight>
}}