Add documentation for geometry (ML rip-off) and Android corner-cases

git-svn-id: https://svn.code.sf.net/p/freeglut/code/trunk@1300 7f0cb862-5218-0410-a997-914c9d46530a

freeglut/freeglut/src/android/fg_main_android.c

@@ -185,10 +185,13 @@ int32_t handle_input(struct android_app* app, AInputEvent* event) {
   if (window == NULL)
     return EVENT_NOT_HANDLED;
 
-  /* FIXME: in Android, when key is repeated, down and up events
+  /* FIXME: in Android, when a key is repeated, down
-     happen most often at the exact same time.  This makes it
+     and up events happen most often at the exact same time.  This
-     impossible to animate based on key press time. */
+     makes it impossible to animate based on key press time. */
   /* e.g. down/up/wait/down/up rather than down/wait/down/wait/up */ 
+  /* This looks like a bug in the virtual keyboard system :/  Real
+     buttons such as the Back button appear to work correctly (series
+     of down events with proper getRepeatCount value */
   
   if (AInputEvent_getType(event) == AINPUT_EVENT_TYPE_KEY) {
     /* LOGI("action: %d", AKeyEvent_getAction(event)); */
@@ -317,10 +320,10 @@ void handle_cmd(struct android_app* app, int32_t cmd) {
     break;
   case APP_CMD_INIT_WINDOW: /* surfaceCreated */
     /* The window is being shown, get it ready. */
-    LOGI("handle_cmd: APP_CMD_INIT_WINDOW");
+    LOGI("handle_cmd: APP_CMD_INIT_WINDOW %p", app->window);
     fgDisplay.pDisplay.single_native_window = app->window;
-    /* glPlatformOpenWindow was waiting for Handle to be defined and
+    /* start|resume: glPlatformOpenWindow was waiting for Handle to be
-       will now return from fgPlatformProcessSingleEvent() */
+       defined and will now continue processing */
     break;
   case APP_CMD_GAINED_FOCUS:
     LOGI("handle_cmd: APP_CMD_GAINED_FOCUS");
@@ -450,6 +453,9 @@ void fgPlatformProcessSingleEvent ( void )
     if (app->destroyRequested != 1) {
       /* Android is full-screen only, simplified call.. */
       /* Ideally we'd have a fgPlatformReopenWindow() */
+      /* If we're hidden by a non-fullscreen or translucent activity,
+         we'll be paused but not stopped, and keep the current
+         surface; in which case fgPlatformOpenWindow will no-op. */
       fgPlatformOpenWindow(window, "", GL_FALSE, 0, 0, GL_FALSE, 0, 0, GL_FALSE, GL_FALSE);
       /* TODO: INVOKE_WCB(*window, Pause?); */
       /* TODO: INVOKE_WCB(*window, LoadResources/ContextLost/...?); */

freeglut/freeglut/src/fg_geometry.c

@@ -55,6 +55,8 @@
  * from face to face.
  */
 
+/** See comment for fghDrawGeometryWire **/
+
 /* Version for OpenGL (ES) 1.1 */
 #ifndef GL_ES_VERSION_2_0
 static void fghDrawGeometryWire11(GLfloat *vertices, GLfloat *normals,
@@ -198,6 +200,20 @@ static void fghDrawGeometryWire20(GLfloat *vertices, GLfloat *normals, GLsizei n
         fghDeleteBuffers(1, &ibo_elements2);
 }
 
+/**
+ * Draw geometric shape in wire mode (only edges)
+ *
+ * Arguments: the sphere, in wire mode, consists of multiple line
+ * loops for the stacks, and for the slices. The vertex indices for
+ * all slices are thrown together. numParts is how many separate loops
+ * are in the array, numVertIdxsPerPart is how many vertices there are
+ * per loop.  For those suffixed with 2, its exactly the same
+ * principle, the number of stacks and slices is not the same.
+ *
+ * Feel free to contribute better naming ;)
+ *
+ * See comment for fghDrawGeometrySolid
+ */
 static void fghDrawGeometryWire(GLfloat *vertices, GLfloat *normals, GLsizei numVertices,
     GLushort *vertIdxs, GLsizei numParts, GLsizei numVertPerPart, GLenum vertexMode,
     GLushort *vertIdxs2, GLsizei numParts2, GLsizei numVertPerPart2
@@ -221,15 +237,6 @@ static void fghDrawGeometryWire(GLfloat *vertices, GLfloat *normals, GLsizei num
 }
 
 
-/* Draw the geometric shape with filled triangles
- *
- * - If the shape is naturally triangulated (numEdgePerFace==3), each
- *   vertex+normal pair is used only once, so no vertex indices.
- * 
- * - If the shape was triangulated (DECOMPOSE_TO_TRIANGLE), some
- *   vertex+normal pairs are reused, so use vertex indices.
- */
-
 /* Version for OpenGL (ES) 1.1 */
 #ifndef GL_ES_VERSION_2_0
 static void fghDrawGeometrySolid11(GLfloat *vertices, GLfloat *normals, GLushort *vertIdxs,
@@ -346,6 +353,14 @@ static void fghDrawGeometrySolid20(GLfloat *vertices, GLfloat *normals, GLushort
         fghDeleteBuffers(1, &ibo_elements);
 }
 
+/* Draw the geometric shape with filled triangles
+ *
+ * - If the shape is naturally triangulated (numEdgePerFace==3), each
+ *   vertex+normal pair is used only once, so no vertex indices.
+ * 
+ * - If the shape was triangulated (DECOMPOSE_TO_TRIANGLE), some
+ *   vertex+normal pairs are reused, so use vertex indices.
+ */
 static void fghDrawGeometrySolid(GLfloat *vertices, GLfloat *normals, GLushort *vertIdxs,
                                  GLsizei numVertices, GLsizei numParts, GLsizei numVertIdxsPerPart)
 {
@@ -364,6 +379,8 @@ static void fghDrawGeometrySolid(GLfloat *vertices, GLfloat *normals, GLushort *
 #endif
 }
 
+
+
 /* Shape decomposition to triangles
  * We'll use glDrawElements to draw all shapes that are not naturally
  * composed of triangles, so generate an index vector here, using the