X-Git-Url: http://git.tdb.fi/?p=libs%2Fgl.git;a=blobdiff_plain;f=source%2Fprogrambuilder.h;fp=source%2Fprogrambuilder.h;h=43d43fcca8f74d6823812809d88cec0fde6b65a0;hp=62d8e07a087f7cebca651ee00b78a947131f96f0;hb=c51030d1cb2308d30db80303a561de1774dfdb76;hpb=26ff1dd4c645c9b8b5361f5f37c58f071789f026

diff --git a/source/programbuilder.h b/source/programbuilder.h
index 62d8e07a..43d43fcc 100644
--- a/source/programbuilder.h
+++ b/source/programbuilder.h
@@ -20,12 +20,43 @@ public:
 
 /**
 Generates shaders with common features.
+
+The shader generation model is based on variable substitutions.  Initially, a
+goal variable is given for each shader stage.  The expression for computing
+each variable is examined for further variable definitions.  When there are no
+more known variables available for substitution, the process terminates.  Any
+unknown variables at this point are assumed to be provided by OpenGL.
+
+Variables can be defined in a number of scopes.  The scope of a variable
+determines where its value is computed.  If a variable is referenced from a
+scope that comes after the declaration scope, an interface variable is
+automatically emitted.
+
+Generated shaders are normally optimized by inlining variables with a single
+reference into the expression referencing them.  This can result in expressions
+of several hundreds of characters in length, so optimizations can be disabled
+with the set_optimize() method for debugging purposes.
+
+Custom variables can be injected to the generated shaders with the custom
+member of the StandardFeatures struct.  The syntax is:
+
+  <custom> := [<decl> ...]
+  <decl>   := <scope> <type> <name> [= <expr>] ;
+  <scope>  := uniform | attribute | vertex | fragment
+  <type>   := (any GLSL type)
+  <name>   := (valid identifier)
+  <expr>   := (GLSL expression)
+
+The custom variables should always include at least one override for a built-in
+variable; otherwise they will be ignored as no built-in expression references
+them.
 */
 class ProgramBuilder
 {
 public:
 	/**
-	Describes the features of a standard shader program.
+	Describes the features of a standard shader program.  All boolean features
+	default to false unless stated otherwise.
 	*/
 	struct StandardFeatures
 	{
@@ -35,16 +66,41 @@ public:
 			Loader(StandardFeatures &);
 		};
 
+		/** Use a diffuse map texture. */
 		bool texture;
+
+		/** Use material properties if lighting is true, or vertex colors if
+		lighting is false. */
 		bool material;
+
+		/** Use lighting to compute the brightness of surfaces. */
 		bool lighting;
+
+		/** Number of lights to use in lighting calculations.  Defaults to 1. */
 		unsigned max_lights;
+
+		/** Use a skylight component for ambient lighting. */
 		bool skylight;
+
+		/** Use a specular lighting component. */
 		bool specular;
+
+		/** Use a normal map texture.  Only used if lighting is true. */
 		bool normalmap;
+
+		/** Use a shadow map.  Requires a ShadowMap effect or equivalent in the
+		pipeline. */
 		bool shadow;
+
+		/** Use a reflection cube map.  Requires an EnvironmentMap effect or
+		equivalend in the pipeline. */
 		bool reflection;
+
+		/** Force the use of legacy shaders conforming to GLSL 1.10.   Defaults
+		to true if the version of GLSL is less than 1.30, false otherwise. */
 		bool legacy;
+
+		/** Custom variables to use in the shader. */
 		std::string custom;
 
 		StandardFeatures();
@@ -137,9 +193,15 @@ private:
 public:
 	ProgramBuilder(const StandardFeatures &);
 
+	/// Enable or disable optimization.  Defaults to enabled.
 	void set_optimize(bool);
+
+	/// Create a new Program with the features associated with the builder.
 	Program *create_program() const;
+
+	/// Generate shaders and add them to an existing program.
 	void add_shaders(Program &) const;
+
 private:
 	std::string create_source(const std::list<ShaderVariable *> &, VariableScope) const;
 	bool evaluate_flags(const char *) const;