Add comments for clarification

Author: ruberith

GUI/OpenGL/MiniGL.cpp

@@ -120,6 +120,7 @@ void MiniGL::drawVector(const Vector3r &a, const Vector3r &b, const float w, flo
 {
 	float thickness = 0.001f * w;
 
+    // Draw a thick line as a cylinder with constant color.
 	drawCylinder(a, b, color, thickness, 8, false);
 }
 
@@ -128,13 +129,19 @@ void MiniGL::drawCylinder(const Vector3r &a, const Vector3r &b, const float *col
 	Vector3r diffcolor(color);
 	Vector3r speccolor(1.0, 1.0, 1.0);
 
+    // To simplify computations, the cylinder of height v is generated
+    // along the z axis from z=0 to z=v and then transformed to the axis ab.
 	Vector3r ab = b - a;
 	Real v = ab.norm();
 	Eigen::Transform<Real, 3, Eigen::Affine> transform =
 		Eigen::Translation<Real, 3>(a) *
 		Quaternionr::FromTwoVectors(Vector3r(0.0, 0.0, v), ab);
 	Vector3r xMid = transform * Vector3r(0.0, 0.0, 0.5 * v);
 
+    // Both the lateral surface and the base disks are subdivided into n slices (cf. gluCylinder & gluDisk).
+    // For this purpose, the base circle is parametrized as a function of the angle theta.
+    // The lateral slices are again subdivided into two triangles each for rendering.
+    // Smooth normals are obtained by going outward from the midpoint.
 	unsigned int n = subdivisions;
 	VectorXr vertices((n+1) * 2 * 3);
 	VectorXr normals((n+1) * 2 * 3);
@@ -194,6 +201,10 @@ void MiniGL::drawSphere(const Vector3r &translation, float radius, float *color,
 	Vector3r diffcolor(color);
 	Vector3r speccolor(1.0, 1.0, 1.0);
 
+    // The surface of the sphere is subdivided into n slices and stacks (cf. gluSphere).
+    // For this purpose, it is parametrized as a function of the longitude theta and the colatitude phi.
+    // The slices and stacks are again subdivided into two triangles each for rendering.
+    // Smooth normals are obtained by going outward from the midpoint.
 	unsigned int n = subDivision;
 	VectorXr vertices((n+1) * n * 3);
 	VectorXr normals((n+1) * n * 3);
@@ -288,6 +299,7 @@ void MiniGL::drawMesh(const std::vector<Vector3r> &vertices, const std::vector<u
 
 void MiniGL::drawQuad(const Vector3r &a, const Vector3r &b, const Vector3r &c, const Vector3r &d, const Vector3r &norm, float *color)
 {
+    // The quad is subdivided into two triangles for rendering.
 	drawTriangle(a, b, c, norm, color);
 	drawTriangle(a, c, d, norm, color);
 }
@@ -389,6 +401,7 @@ void MiniGL::setViewport(float pfovy, float pznear, float pzfar, const Vector3r
 	znear = pznear;
 	zfar = pzfar;
 
+    // Compute the lookAt modelview matrix (cf. gluLookAt).
 	Vector3r f = (plookat - peyepoint).normalized();
 	Vector3r up(0.0, 1.0, 0.0);
 	Vector3r s = f.cross(up);
@@ -504,6 +517,7 @@ void MiniGL::init(const int width, const int height, const char *name, const boo
 	glGenBuffers(1, &m_vbo_vertices);
 	glGenBuffers(1, &m_vbo_normals);
 	glGenBuffers(1, &m_vbo_faces);
+    // Set the default normal (cf. glNormal).
 	glVertexAttrib3f(1, 0.0, 0.0, 1.0);
 
 	m_lastTime = glfwGetTime();
@@ -655,7 +669,8 @@ void MiniGL::char_callback(GLFWwindow* window, unsigned int codepoint)
 }
 
 void MiniGL::setProjectionMatrix (int width, int height) 
-{ 
+{
+    // Compute the perspective projection matrix (cf. gluPerspective).
 	Real aspect = (Real)width / (Real)height;
 	Real fovy_rad = fovy * M_PI / 180.0;
 	Real f = cos(0.5 * fovy_rad) / sin(0.5 * fovy_rad);
@@ -951,6 +966,7 @@ void MiniGL::unproject(const Vector3r& win, Vector3r& pos)
 	GLint viewport[4];
 	glGetIntegerv(GL_VIEWPORT, viewport);
 
+    // Map the specified window coordinates to object coordinates (cf. gluUnProject).
 	Vector4r ndc;
 	ndc(0) = static_cast<Real>(2.0) * (win(0) - static_cast<Real>(viewport[0])) / static_cast<Real>(viewport[2]) - static_cast<Real>(1.0);
 	ndc(1) = static_cast<Real>(2.0) * (win(1) - static_cast<Real>(viewport[1])) / static_cast<Real>(viewport[3]) - static_cast<Real>(1.0);

GUI/OpenGL/MiniGL.h

@@ -232,10 +232,15 @@ namespace SPH
 		static const GLuint getVboNormals() { return m_vbo_normals; }
 		static const GLuint getVboFaces() { return m_vbo_faces; }
 
+        // Fill a VBO with vector data and map to the VAO attribute at the specified index.
 		static void supplyVectors(GLuint index, GLuint vbo, unsigned int dim, unsigned int n, const Real* data);
+        // Fill the dedicated VBO with 3D vertex data and map to the VAO attribute at the specified index.
 		static void supplyVertices(GLuint index, unsigned int numVectors, const Real* data);
+        // Fill the dedicated VBO with 3D normal data and map to the VAO attribute at the specified index.
 		static void supplyNormals(GLuint index, unsigned int numVectors, const Real* data);
+        // Fill a VBO with index data.
 		static void supplyIndices(GLuint vbo, unsigned int n, const unsigned int* data);
+        // Fill the dedicated VBO with face index data.
 		static void supplyFaces(unsigned int numIndices, const unsigned int* data);
 	};
 }

data/shaders/mini.frag

@@ -26,6 +26,7 @@ void main()
         vec3 view = normalize(-IN.position);
         vec3 normal = normalize(IN.normal);
 
+        // Compute the ambient lighting.
         vec3 color = ambientReflectance * ambientIntensity;
 
         for (int i = 0; i < NUM_LIGHTS; i++)
@@ -34,11 +35,13 @@ void main()
             float diffuseFactor = max(dot(normal, light), 0.0);
             if (diffuseFactor > 0.0)
             {
+                // Compute the diffuse lighting using the Lambertian model.
                 color += diffuseFactor * diffuseReflectance * diffuseIntensity[i];
 
                 vec3 halfway = normalize(light + view);
                 float specularFactor = pow(max(dot(halfway, normal), 0.0), shininess);
 
+                // Compute the specular lighting using the Blinn-Phong model.
                 color += specularFactor * specularReflectance * specularIntensity[i];
             }
         }

data/shaders/mini_screen.vert

@@ -7,5 +7,6 @@ layout(location = 0) in vec2 position;
 
 void main()
 {
+    // Project the screen position to NDC (cf. glOrtho).
     gl_Position = vec4(2.0 * (position.x / width) - 1.0, -2.0 * (position.y / height) + 1.0, -1.0, 1.0);
 }