Add some documentation to the GLSL compiler

[libs/gl.git] / source / glsl / compiler.h

diff --git a/source/glsl/compiler.h b/source/glsl/compiler.h
index 69ac7427d80fc97188fa2bcbb0c2c600ef6cf67a..1f3cbee4698c466a7b88b562d56373f7f9b0fb6e 100644 (file)
--- a/source/glsl/compiler.h
+++ b/source/glsl/compiler.h
@@ -28,35 +28,87 @@ private:
        std::map<std::string, int> spec_values;
 
 public:
+       /** Creates a compiler using features from the current OpenGL context. */
        Compiler();
+
+       /** Creates a compiler targeting a specific set of features. */
        Compiler(const Features &);
+
        ~Compiler();
 
 private:
        void clear();
+
 public:
+       /** Sets the source code to be compiled.  Only builtin imports are
+       available. */
        void set_source(const std::string &, const std::string & = "<string>");
+
+       /** Loads source code from an I/O object.  If a collection is used, imports
+       can be fetched from it. */
        void load_source(IO::Base &, DataFile::Collection * = 0, const std::string & = "<file>");
+
+       /** Loads source code from an I/O object.  Only builtin imports are
+       available. */
        void load_source(IO::Base &, const std::string &);
+
+       /** Specializes the shader.  All specialization constants are considered
+       specialized, even if they do not appear in the map. */
        void specialize(const std::map<std::string, int> &);
+
+       /** Compiles the shader. */
        void compile(Mode);
 
+       /** Returns combined GLSL source for all shader stages.  The result is
+       suitable for feeding back to the compiler. */
        std::string get_combined_glsl() const;
+
+       /** Returns a list of compiled stage types. */
        std::vector<Stage::Type> get_stages() const;
+
+       /** Returns GLSL source for a single shader stage.  The result is standard
+       GLSL suitable for OpenGL or an external GLSL compiler. */
        std::string get_stage_glsl(Stage::Type) const;
+
+       /** Returns a map of vertex attribute locations.  If the target GLSL version
+       supports interface layouts, the map is empty (locations are included in the
+       GLSL soucre). */
        const std::map<std::string, unsigned> &get_vertex_attributes() const;
+
+       /** Returns a map of fragment output locations.  If the target GLSL version
+       supports interface layouts, the map is empty (locations are included in the
+       GLSL soucre). */
        const std::map<std::string, unsigned> &get_fragment_outputs() const;
+
+       /** Returns the mapping of source indices to filenames.  Can be used to
+       translate error messages. */
        const SourceMap &get_source_map() const;
 
+       /** Returns a textual representation of the syntax tree for a shader stage.
+       Intended for debugging purposes. */
        std::string get_stage_debug(Stage::Type) const;
 
 private:
+       /** Appends a module to the target, processing any imports found in it. */
        void append_module(Module &, DataFile::Collection *);
+
+       /** Appends a single stage to the matching stage of the target. */
        void append_stage(Stage &);
+
+       /// Imports a module by name and appends it to the target. */
        void import(DataFile::Collection *, const std::string &);
+
+       /** Generates any implicitly defines syntactic structures and resolves
+       variables. */
        void generate(Stage &, Mode);
+
+       /** Applies optimizations to a stage.  The return value indicates if the
+       preceding stage should be processed again. */
        bool optimize(Stage &);
+
+       /** Performs final adjustments on a stage after compilation. */
        void finalize(Stage &, Mode);
+
        static void inject_block(Block &, const Block &);
 };