documentation and cleanup

include/ACGL/OpenGL/Objects/LocationMappings.hh

@@ -6,7 +6,7 @@
 #ifndef ACGL_OPENGL_OBJECTS_LOCATIONMAPPINGS_HH
 #define ACGL_OPENGL_OBJECTS_LOCATIONMAPPINGS_HH
 
-/*
+/**
  * LocationMappings is a map from strings to GLuints that stores the mappings from
  *
  *    attribute names  to  attribute locations
@@ -15,8 +15,11 @@
  *
  * (as long as there are no name clashes one map can be used for both)
  *
- * A mapping like this can be used to init all mappings of multiple ShaderProgram
- * in the same way to they can be used with the same VAOs or FBOs, similar, these
+ * Another use is to query
+ *    uniform names    to  uniform buffer offsets
+ *
+ * A mapping like this can be used to init all mappings of multiple ShaderPrograms
+ * in the same way to they can be used with the same VAOs or FBOs. Similar, these
  * mapping objects can be used to configute VAOs and FBOs!
  *
  * To fully automate the mappings in a program the creation of these mappings can

include/ACGL/OpenGL/Objects/ProgramPipeline.hh

@@ -14,11 +14,13 @@
 
 #include <ACGL/OpenGL/Objects/ShaderProgram.hh>
 
+
+#if (ACGL_OPENGL_VERSION >= 41)
 namespace ACGL{
 namespace OpenGL{
 
 /**
- * OpenGL ProgramPipeline Objects
+ * OpenGL ProgramPipeline Objects (needs OpenGL 4.1)
  *
  * Multiple ShaderPrograms that are set to be separable can be attached to one ProgramPipeline.
  * Uniforms are still a ShaderProgram (not ProgramPipeline) state, so to update them you either have to
@@ -29,8 +31,6 @@ namespace OpenGL{
  * play around with ProgramPipeline Objects.
  */
 
-#if (ACGL_OPENGL_VERSION >= 41)
-
 class ProgramPipeline {
     ACGL_NOT_COPYABLE(ProgramPipeline)
 public:
@@ -80,9 +80,10 @@ private:
 };
 
 ACGL_SMARTPOINTER_TYPEDEFS(ProgramPipeline)
-#endif // OpenGL >= 4.1
 
 } // OpenGL
 } // ACGL
 
+#endif // OpenGL >= 4.1
+
 #endif // ACGL_OPENGL_OBJECTS_PROGRAMPIPELINE_HH

include/ACGL/OpenGL/Objects/Sampler.hh

@@ -14,14 +14,27 @@
 
 #include <ACGL/Math/Math.hh>
 
+#if (ACGL_OPENGL_VERSION >= 33)
 namespace ACGL{
 namespace OpenGL{
 
 /*
- * OpenGL Sampler Objects
+ * OpenGL Sampler Objects (needs OpenGL 3.3)
+ *
+ * A Sampler holds information about how to sample in textures (bi-linear, anisotrophic, wrap modes etc).
+ * Instead of setting these informations for each texture, a sampler object can be used and bound to
+ * the texture units, this will overwrite the sampling information in the texture object itself.
+ * This way, one texture can be bound to two texture units and two different samplers can be bound to those
+ * units to provide different sampling behavior from the same texture in one shaderpass.
+ * Similar, different textures can use the same sampler so only one object has to be changed if for example
+ * the number of anisotrophic filter-samples should get changed (instead of changing all texture objects).
+ *
+ * All default parameters of the setters used to change the sampling behavior are the OpenGL defaults as well.
+ *
+ * If needed, getters could be added that query the settings from GL, so no caching is needed here (that might
+ * be something for a derived class with larger memory footprint but faster access to the settings).
  */
 
-#if (ACGL_OPENGL_VERSION >= 33)
 
 class Sampler {
     ACGL_NOT_COPYABLE(Sampler)
@@ -82,9 +95,10 @@ private:
 };
 
 ACGL_SMARTPOINTER_TYPEDEFS(Sampler)
-#endif // OpenGL >= 3.3
 
 } // OpenGL
 } // ACGL
 
+#endif // OpenGL >= 3.3
+
 #endif // ACGL_OPENGL_OBJECTS_SAMPLER_HH

include/ACGL/OpenGL/Objects/UniformBuffer.hh

@@ -6,6 +6,25 @@
 #ifndef ACGL_OPENGL_OBJECTS_UNIFORM_BUFFER_HH
 #define ACGL_OPENGL_OBJECTS_UNIFORM_BUFFER_HH
 
+/*
+ * A uniform buffer is an OpenGL buffer object bound to a uniform buffer location.
+ * It can be used:
+   * provide the same set of uniforms to different ShaderPrograms without setting
+     the values multiple times
+   * set multiple uniform variables at once by mapping the buffer into the CPU
+     memory, memset all values and unmap it.
+ *
+ * To be used, uniforms must be organized in a uniform block, this block has to be bound
+ * to the same location the uniform buffer gets bound to (quite similar to textures).
+ *
+ * If only advantage one is requested, the individual offsets along with the uniform names
+ * can be saved in a uniform buffer to set the uniforms by setUniform() as it would be done
+ * for normal uniforms in a ShaderProgram.
+ * Otherwise the exact memory layout must be known, which can be queried by OpenGL, but which
+ * is also well defined in the case of std140-blocks (see OpenGL spec).
+ *
+ */
+
 #include <ACGL/ACGL.hh>
 
 #include <ACGL/Base/Macros.hh>
@@ -16,6 +35,7 @@
 #include <ACGL/OpenGL/Objects/LocationMappings.hh>
 #include <ACGL/Math/Math.hh>
 
+#if (ACGL_OPENGL_VERSION >= 31)
 namespace ACGL{
 namespace OpenGL{
 
@@ -23,8 +43,6 @@ namespace OpenGL{
  * An OpenGL Uniform Buffer Object that can be used to share blocks of uniforms between multiple ShaderPrograms.
  */
 
-#if (ACGL_OPENGL_VERSION >= 31)
-
 class UniformBuffer : public Buffer
 {
     // ========================================================================================================= \/
@@ -93,9 +111,10 @@ private:
 };
 
 ACGL_SMARTPOINTER_TYPEDEFS(UniformBuffer)
-#endif // OpenGL >= 3.1
 
 } // OpenGL
 } // ACGL
 
+#endif // OpenGL >= 3.1
+
 #endif // ACGL_OPENGL_OBJECTS_UNIFORM_BUFFER_HH