Improve documentation for a number of classes

[libs/gl.git] / source / programbuilder.h

diff --git a/source/programbuilder.h b/source/programbuilder.h
index 62d8e07a087f7cebca651ee00b78a947131f96f0..43d43fcca8f74d6823812809d88cec0fde6b65a0 100644 (file)
--- 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;