commit dedacd82be03784af6d4a421a23771608573491a
Author: Leszek Koltunski <leszek@distorted.org>
Date:   Tue Dec 6 16:04:31 2016 +0000

    Javadoc

diff --git a/src/main/java/org/distorted/library/Distorted.java b/src/main/java/org/distorted/library/Distorted.java
index 819f891..d178bc1 100644
--- a/src/main/java/org/distorted/library/Distorted.java
+++ b/src/main/java/org/distorted/library/Distorted.java
@@ -374,6 +374,7 @@ public class Distorted
     {
     DistortedGridFactory.release();
     DistortedObjectList.release();
+    DistortedFramebufferList.release();
     DistortedNode.release();
     EffectQueue.reset();
     EffectMessageSender.stopSending();
diff --git a/src/main/java/org/distorted/library/DistortedFramebuffer.java b/src/main/java/org/distorted/library/DistortedFramebuffer.java
index 672883f..1a0e5f3 100644
--- a/src/main/java/org/distorted/library/DistortedFramebuffer.java
+++ b/src/main/java/org/distorted/library/DistortedFramebuffer.java
@@ -23,7 +23,13 @@ import android.opengl.GLES20;
 import android.opengl.Matrix;
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
+/**
+ * Class which represents a OpenGL Framebuffer object.
+ *
+ * User is able to create either WRITE-only Framebuffers from objects already constructed outside
+ * of the library (the first constructor; primary use case: the screen) or an offscreen READ-WRITE
+ * FBOs (used by the DistortedNode, but also can be used by external users of the library)
+ */
 public class DistortedFramebuffer
   {
   private static final int TEXTURE_FAILED_TO_CREATE = -1;
@@ -83,7 +89,6 @@ public class DistortedFramebuffer
   private boolean createFBO()
     {
     GLES20.glGenTextures(1, texIds, 0);
-
     GLES20.glBindTexture(GLES20.GL_TEXTURE_2D, texIds[0]);
     GLES20.glTexParameterf(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MIN_FILTER, GLES20.GL_NEAREST);
     GLES20.glTexParameterf(GLES20.GL_TEXTURE_2D, GLES20.GL_TEXTURE_MAG_FILTER, GLES20.GL_LINEAR);
@@ -94,12 +99,12 @@ public class DistortedFramebuffer
     GLES20.glGenFramebuffers(1, fboIds, 0);
     GLES20.glBindFramebuffer(GLES20.GL_FRAMEBUFFER, fboIds[0]);
     GLES20.glFramebufferTexture2D(GLES20.GL_FRAMEBUFFER, GLES20.GL_COLOR_ATTACHMENT0, GLES20.GL_TEXTURE_2D, texIds[0], 0);
+
     int status = GLES20.glCheckFramebufferStatus(GLES20.GL_FRAMEBUFFER);
 
     if(status != GLES20.GL_FRAMEBUFFER_COMPLETE)
       {
       android.util.Log.e("DistortedFramebuffer", "failed to create framebuffer, error="+status);
-
       GLES20.glDeleteTextures(1, texIds, 0);
       GLES20.glDeleteFramebuffers(1, fboIds, 0);
       fboIds[0] = 0;
@@ -107,7 +112,8 @@ public class DistortedFramebuffer
       return false;
       }
 
-    android.util.Log.e("FBO", "creating ("+mWidth+","+mHeight+") "+fboIds[0]);
+    DistortedFramebufferList.add(this);
+    android.util.Log.e("FBO", "created ("+mWidth+","+mHeight+") "+fboIds[0]);
 
     return true;
     }
@@ -146,7 +152,13 @@ public class DistortedFramebuffer
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 // PUBLIC API
-
+///////////////////////////////////////////////////////////////////////////////////////////////////
+/**
+ * Create a new offscreen FBO.
+ *
+ * @param width Width of the COLOR attachment.
+ * @param height Height of the COLOR attachment.
+ */
   public DistortedFramebuffer(int width, int height)
     {
     mProjectionMatrix = new float[16];
@@ -162,12 +174,14 @@ public class DistortedFramebuffer
     mMarked = false;
 
     createProjection();
-
-    DistortedFramebufferList.add(this);
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
+/**
+ * Create a new DistortedFramebuffer from an already created OpenGL Framebuffer.
+ *
+ * @param fbo the ID of a OpenGL Framebuffer object. Typically 0 (the screen)
+ */
   public DistortedFramebuffer(int fbo)
     {
     mProjectionMatrix = new float[16];
@@ -182,7 +196,9 @@ public class DistortedFramebuffer
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
+/**
+ * Mark the underlying OpenGL object for deletion. Actual deletion will take place on the next render.
+ */
   public void markForDeletion()
     {
     android.util.Log.e("FBO", "marking for deletion ("+mWidth+","+mHeight+") "+fboIds[0]);
@@ -192,10 +208,16 @@ public class DistortedFramebuffer
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
-  public void setProjection(float FOV, float x, float y)
+/**
+ * Create new Projection matrix.
+ *
+ * @param fov Vertical 'field of view' of the Projection frustrum (in degrees).
+ * @param x X-coordinate of the point at which our camera looks at. -1<x<1
+ * @param y Y-coordinate of the point at which our camera looks at. -1<y<1
+ */
+  public void setProjection(float fov, float x, float y)
     {
-    mFOV = FOV;
+    mFOV = fov;
     mX   = x;
     mY   = y;
 
@@ -203,7 +225,18 @@ public class DistortedFramebuffer
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
+/**
+ * Resize the underlying Framebuffer.
+ *
+ * As the Framebuffer is not created until the first render, typical usage of this API is actually
+ * to set the size of an not-yet-created Framebuffer of an object that has been created with the
+ * second constructor.
+ *
+ * Fully creating an object, rendering to it, then resizing mid-render is also possible.
+ *
+ * @param width The new width.
+ * @param height The new height.
+ */
   public void resize(int width, int height)
     {
     if( mWidth!=width || mHeight!=height )
@@ -218,14 +251,9 @@ public class DistortedFramebuffer
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-
-  public int getFBO()
-    {
-    return fboIds[0];
-    }
-
-///////////////////////////////////////////////////////////////////////////////////////////////////
-// set this as Render Target to draw to. Must be called from a thread holding OpenGL context.
+/**
+ * Set this as the Framebuffer to write to.
+ */
 
   public void setOutput()
     {
@@ -235,7 +263,9 @@ public class DistortedFramebuffer
     }
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
-// set this as Render Target to draw from. Must be called from a thread holding OpenGL context.
+/**
+ * Set this as the Framebuffer to read from.
+ */
 
   public void setInput()
     {
diff --git a/src/main/java/org/distorted/library/DistortedFramebufferList.java b/src/main/java/org/distorted/library/DistortedFramebufferList.java
index 469bcd6..9f98ffa 100644
--- a/src/main/java/org/distorted/library/DistortedFramebufferList.java
+++ b/src/main/java/org/distorted/library/DistortedFramebufferList.java
@@ -23,10 +23,12 @@ import java.util.LinkedList;
 import java.util.Iterator;
 
 /**
- * List of all DistortedRenderTarget objects currently created by the application.
+ * List of all DistortedFramebuffer objects currently created by the application.
  *
- * The point: we need to be able ot mark RenderTargets for deletion, and delete all marked
- * objects later at a convenient time. Thus we keep all of them in a LinkedList here.
+ * The point: we need to be able to mark Framebuffers for deletion, and delete all marked
+ * objects later at a convenient time (that's because we can only delete from a thread that
+ * holds the OpenGL context so here we provide a framework where one is able to mark for deletion
+ * at any place and actual deletion takes place on the next render).
  */
 
 ///////////////////////////////////////////////////////////////////////////////////////////////////
@@ -50,6 +52,14 @@ final class DistortedFramebufferList
     mMarked = true;
     }
 
+///////////////////////////////////////////////////////////////////////////////////////////////////
+
+  static synchronized void release()
+    {
+    mMarked = false;
+    mList.clear();
+    }
+
 ///////////////////////////////////////////////////////////////////////////////////////////////////
 // must be called form a thread holding OpenGL Context