added comments

include/ACGL/OpenGL/Objects/RenderObject.hh

@@ -6,6 +6,14 @@
 #ifndef ACGL_OPENGL_OBJECTS_RENDEROBJECT_HH
 #define ACGL_OPENGL_OBJECTS_RENDEROBJECT_HH
 
+/*
+ * A RenderObject combines a FrameBuffer to draw to, a ShaderProgramObject
+ * to draw with and a VertexBufferObject to name what to draw.
+ *
+ * Instead of setting those objects individually and hoping that they match
+ * a RenderObject can take care of that.
+ */
+
 #include <vector>
 #include <string>
 #include <tr1/memory>
@@ -74,8 +82,7 @@ public:
 
     virtual ~RenderObject(void)
     {
-        if(mpDrawBuffers != NULL)
-            delete[](mpDrawBuffers);
+        delete[](mpDrawBuffers);
     }
 
     // ==================================================================================================== \/
@@ -135,8 +142,8 @@ protected:
     ConstSharedShaderProgramObject mpShaderProgramObject;
     ConstSharedFrameBufferObject   mpFrameBufferObject;
 
-    AttributeMappingVec    mAttributeMappings;
-    GLuint* mpDrawBuffers;
+    AttributeMappingVec            mAttributeMappings;
+    GLuint*                        mpDrawBuffers;
 };
 
 ACGL_SHARED_TYPEDEF(RenderObject)

include/ACGL/OpenGL/Objects/Shader.hh

@@ -6,6 +6,15 @@
 #ifndef ACGL_OPENGL_OBJECTS_SHADER_HH
 #define ACGL_OPENGL_OBJECTS_SHADER_HH
 
+/*
+ * A Shader ist just one OpenGL shader like a fragment or vertex shader. To use these
+ * a ShaderProgram is needed that links together multiple Shaders for the different
+ * pipelinestages.
+ *
+ * So normally you want to work with ShaderPrograms instead of Shaders (switch Programs,
+ * set uniforms etc).
+ */
+
 #include <vector>
 #include <string>
 #include <tr1/memory>

include/ACGL/OpenGL/Objects/ShaderProgram.hh

@@ -6,6 +6,40 @@
 #ifndef ACGL_OPENGL_OBJECTS_SHADERPROGRAM_HH
 #define ACGL_OPENGL_OBJECTS_SHADERPROGRAM_HH
 
+/*
+ * A ShaderProgram is a wrapper around an OpenGL Program: A combination of Shaders
+ * that are linked together to controll the programmable pipeline stages.
+ *
+ * A ShaderProgram is still quite low-level and just wraps the OpenGL object itself.
+ *
+ * One note on uniforms:
+ * There are basically four ways to set uniform values here:
+ *
+ * setUniform(        GLint       _location, VALUE );
+ * setUniform(        std::string _location, VALUE );
+ * setProgramUniform( GLint       _location, VALUE );
+ * setProgramUniform( std::string _location, VALUE );
+ *
+ * The versions with a std::string as a location are easy to use, just provide the name
+ * the uniform is called in the shaderfile. But it will have to query the uniform location
+ * each call and thus is inefficient! It would be faster to query the location once using
+ * getUniformLocation( std::string ); and use the returned value in combination with the
+ * set*Uniform( GLint, ...) versions.
+ *
+ * Both are provided as setUniform and setProgramUniform:
+ * In order for setUniform(...) to work as intendet the ShaderProgram has to be active ( use() ),
+ * setProgramUniform(...) does not have this limitation and is based on direct state access
+ * (via an extension or a basic simulation of the extension).
+ * Use setProgramUniform if you can't know which program is in use right now, setUniform should
+ * be prefered for performance critical parts of your app.
+ *
+ * In short: setProgramUniform( std::string _location, VALUE ); is the most error proof option
+ *           and good for testing out new stuff
+ *           setUniform( GLint _location, VALUE ); is best for performance critical code thats
+ *           well tested
+ *
+ */
+
 #include <ACGL/ACGL.hh>
 
 #include <ACGL/Base/Macros.hh>
@@ -75,6 +109,7 @@ public:
 
     bool link (void) const;
 
+
     inline void setUniform (GLint _location, GLint _v)   const { glUniform1i (_location, _v); }
     inline void setUniform (GLint _location, GLfloat _v) const { glUniform1f (_location, _v); }
 

include/ACGL/OpenGL/Objects/ShaderProgramObject.hh

@@ -6,6 +6,20 @@
 #ifndef ACGL_OPENGL_OBJECTS_SHADERPROGRAMOBJECT_HH
 #define ACGL_OPENGL_OBJECTS_SHADERPROGRAMOBJECT_HH
 
+/*
+ * A ShaderProgramObject has no direct OpenGL counterpart but it is a combination
+ * of a ShaderProgram an a set of Uniforms which are saved on the client side
+ * until that ShaderProgram gets used.
+ *
+ * This way we can have multiple ShaderProgramOpbjects for the same ShaderProgram
+ * but with different values for the uniforms (think of 5 objects which use the same
+ * material shader but have different ModelviewMatrixes and colors set as uniforms,
+ * in that case we only need one ShaderProgram but 5 descriptions of the different
+ * uniform values. Thats what this class provides).
+ *
+ * You might not use this class directly but as a part of a RenderObject!
+ */
+
 #include <ACGL/ACGL.hh>
 
 #include <ACGL/Base/Macros.hh>

include/ACGL/OpenGL/Objects/Texture.hh

@@ -6,6 +6,11 @@
 #ifndef ACGL_OPENGL_OBJECTS_TEXTURE_HH
 #define ACGL_OPENGL_OBJECTS_TEXTURE_HH
 
+/*
+ * A Texture wrapps the OpenGL texture. To fill these with data from image files a
+ * matching TextureControllerFile* is needed.
+ */
+
 #include <ACGL/ACGL.hh>
 
 #include <ACGL/Base/Macros.hh>

include/ACGL/OpenGL/Objects/Uniform.hh

@@ -6,6 +6,16 @@
 #ifndef ACGL_OPENGL_OBJECTS_UNIFORM_HH
 #define ACGL_OPENGL_OBJECTS_UNIFORM_HH
 
+/*
+ * Uniforms do not map to OpenGL objects directly, to set a uniform value in a
+ * ShaderProgram, use the setUniform() / setProgramUniform() methods there with
+ * the raw values you want to ste.
+ *
+ * This class provides the ability to save uniform values on the client side and
+ * wait with the uploading until the ShaderProgram gets used. It gets used in
+ * combination with the ShaderProgramObject/RenderObject (see there).
+ */
+
 #include <ACGL/ACGL.hh>
 
 #include <ACGL/Base/Macros.hh>