[x3d-public] Collect Shader variable documentation links into a single page

[Michalis Kamburelis]

John Carlson wrote:
> On Jan 11, 2016, at 5:47 PM, John Carlson <yottzumm at gmail.com
> <mailto:yottzumm at gmail.com>> wrote:
> 
> Don, can we collect Shader variable documentation links into a single
> page on www.web3d.org <http://www.web3d.org/>  This will be the first
> step at finding commonality.
> 
> X3DOM:  http://doc.x3dom.org/tutorials/lighting/customShader/index.html
> FreeWRL: http://freewrl.sourceforge.net/FreeX3D/Component_ProgrammableShaders.html
> Cobweb:  http://titania.create3000.de/cobweb/custom-shaders/
> BS
> Contact: http://www.bitmanagement.com/developer/contact/examples/shader/shader.html
> Standard OpenGL: ?
> 

Castle Game Engine documentation about shaders is on
http://castle-engine.sourceforge.net/x3d_implementation_shaders.php .
However, we did not introduce any built-in magic variables in GLSL,
thinking that it would be just a dirty hack. Instead:

1. The most preferred way to write shaders is to use our "Compositing
Shaders" extensions, documente on
http://castle-engine.sourceforge.net/compositing_shaders.php extensions
, to create shader effects.

  This avoids the need to have any "magic" uniforms (defined by the
engine and used by X3D authors). Instead, you simply define GLSL
functions that get all they need through their parameters.

2. To pass additional information to your shaders, you use X3D
specification sanctioned approach: ROUTE the necessary information from
the nodes to your shaders. This is documented on
http://castle-engine.sourceforge.net/x3d_implementation_shaders.php and
in many examples.

  This is the best way to pass information either to standard shaders
(X3D ComposedShader node) or to our compositing shaders (X3D Effect node).

2.1. In particular, to get camera matrix, ROUTE the appropriate
Viewpoint events:

  SFMatrix4f [out]         cameraMatrix
  SFMatrix4f [out]         cameraInverseMatrix
  SFMatrix3f [out]         cameraRotationMatrix
  SFMatrix3f [out]         cameraRotationInverseMatrix

Documented on
http://castle-engine.sourceforge.net/x3d_implementation_navigation_extensions.php#section_ext_viewpoint_camera_matrix

3. Finally: as a last resort, you can also use GLSL build-in variables,
like gl_Vertex or gl_ModelViewMatrix. The full list is in GLSL 1.20
specification. But this is only available on desktops (OpenGL, not
OpenGLES) and is very discouraged (newer GLSL language versions removed it).

Regards,
Michalis