Merge "More documentation."

graphics/java/android/renderscript/BaseObj.java

@@ -41,6 +41,13 @@ class BaseObj {
         mID = id;
     }
 
+    /**
+     * Lookup the native object ID for this object.  Primarily used by the
+     * generated reflected code.
+     *
+     *
+     * @return int
+     */
     public int getID() {
         if (mDestroyed) {
             throw new RSInvalidStateException("using a destroyed object.");
@@ -53,8 +60,15 @@ class BaseObj {
     private String mName;
     RenderScript mRS;
 
-    public void setName(String s) {
-        if(s.length() < 1) {
+    /**
+     * setName assigns a name to an object.  This object can later be looked up
+     * by this name.  This name will also be retained if the object is written
+     * to an A3D file.
+     *
+     * @param name The name to assign to the object.
+     */
+    public void setName(String name) {
+        if(name.length() < 1) {
             throw new RSIllegalArgumentException("setName does not accept a zero length string.");
         }
         if(mName != null) {
@@ -62,9 +76,9 @@ class BaseObj {
         }
 
         try {
-            byte[] bytes = s.getBytes("UTF-8");
+            byte[] bytes = name.getBytes("UTF-8");
             mRS.nAssignName(mID, bytes);
-            mName = s;
+            mName = name;
         } catch (java.io.UnsupportedEncodingException e) {
             throw new RuntimeException(e);
         }
@@ -84,6 +98,12 @@ class BaseObj {
         super.finalize();
     }
 
+    /**
+     * destroy disconnects the object from the native object effectivly
+     * rendering this java object dead.  The primary use is to force immediate
+     * cleanup of resources when its believed the GC will not respond quickly
+     * enough.
+     */
     synchronized public void destroy() {
         if(mDestroyed) {
             throw new RSInvalidStateException("Object already destroyed.");
@@ -92,8 +112,10 @@ class BaseObj {
         mRS.nObjDestroy(mID);
     }
 
-    // If an object came from an a3d file, java fields need to be
-    // created with objects from the native layer
+    /**
+     * If an object came from an a3d file, java fields need to be
+     * created with objects from the native layer
+     */
     void updateFromNative() {
         mRS.validate();
         mName = mRS.nGetName(getID());

graphics/java/android/renderscript/RenderScript.java

@@ -28,6 +28,13 @@ import android.view.Surface;
 /**
  * @hide
  *
+ * RenderScript base master class.  An instance of this class creates native
+ * worker threads for processing commands from this object.  This base class
+ * does not provide any extended capabilities beyond simple data processing.
+ * For extended capabilities use derived classes such as RenderScriptGL.
+ *
+ *
+ *
  **/
 public class RenderScript {
     static final String LOG_TAG = "RenderScript_jni";
@@ -581,6 +588,14 @@ public class RenderScript {
     ///////////////////////////////////////////////////////////////////////////////////
     //
 
+    /**
+     * Base class application should derive from for handling RS messages
+     * comming from their scripts.  When a script calls sendToClient the data
+     * fields will be filled in and then the run method called by a message
+     * handling thread.  This will occur some time after sendToClient completes
+     * in the script.
+     *
+     */
     public static class RSMessage implements Runnable {
         protected int[] mData;
         protected int mID;
@@ -588,16 +603,42 @@ public class RenderScript {
         public void run() {
         }
     }
+    /**
+     * If an application is expecting messages it should set this field to an
+     * instance of RSMessage.  This instance will receive all the user messages
+     * sent from sendToClient by scripts from this context.
+     *
+     */
     public RSMessage mMessageCallback = null;
 
+    /**
+     * Runtime error base class.  An application should derive from this class
+     * if it wishes to install an error handler.  When errors occur at runtime
+     * the fields in this class will be filled and the run method called.
+     *
+     */
     public static class RSAsyncError implements Runnable {
         protected String mErrorMessage;
         protected int mErrorNum;
         public void run() {
         }
     }
+
+    /**
+     * Application Error handler.  All runtime errors will be dispatched to the
+     * instance of RSAsyncError set here.  If this field is null a
+     * RSRuntimeException will instead be thrown with details about the error.
+     * This will cause program termaination.
+     *
+     */
     public RSAsyncError mErrorCallback = null;
 
+    /**
+     * RenderScript worker threads priority enumeration.  The default value is
+     * NORMAL.  Applications wishing to do background processing such as
+     * wallpapers should set their priority to LOW to avoid starving forground
+     * processes.
+     */
     public enum Priority {
         LOW (5),     //ANDROID_PRIORITY_BACKGROUND + 5
         NORMAL (-4);  //ANDROID_PRIORITY_DISPLAY
@@ -614,6 +655,12 @@ public class RenderScript {
         }
     }
 
+
+    /**
+     * Change the priority of the worker threads for this context.
+     *
+     * @param p New priority to be set.
+     */
     public void contextSetPriority(Priority p) {
         validate();
         nContextSetPriority(p.mID);
@@ -690,9 +737,15 @@ public class RenderScript {
         }
     }
 
-    protected RenderScript() {
+    RenderScript() {
     }
 
+    /**
+     * Create a basic RenderScript context.
+     *
+     *
+     * @return RenderScript
+     */
     public static RenderScript create() {
         RenderScript rs = new RenderScript();
 
@@ -704,15 +757,32 @@ public class RenderScript {
         return rs;
     }
 
+    /**
+     * Print the currently available debugging information about the state of
+     * the RS context to the log.
+     *
+     *
+     * @param bits Currently ignored.
+     */
     public void contextDump(int bits) {
         validate();
         nContextDump(bits);
     }
 
+    /**
+     * Wait for any commands in the fifo between the java bindings and native to
+     * be processed.
+     *
+     */
     public void finish() {
         nContextFinish();
     }
 
+    /**
+     * Destroy this renderscript context.  Once this function is called its no
+     * longer legal to use this or any objects created by this context.
+     *
+     */
     public void destroy() {
         validate();
         nContextDeinitToClient(mContext);
@@ -733,9 +803,6 @@ public class RenderScript {
         return mContext != 0;
     }
 
-    ///////////////////////////////////////////////////////////////////////////////////
-    // Root state
-
     protected int safeID(BaseObj o) {
         if(o != null) {
             return o.getID();

graphics/java/android/renderscript/RenderScriptGL.java

@@ -30,12 +30,22 @@ import android.view.SurfaceView;
 /**
  * @hide
  *
+ * The Graphics derivitive of RenderScript.  Extends the basic context to add a
+ * root script which is the display window for graphical output.  When the
+ * system needs to update the display the currently bound root script will be
+ * called.  This script is expected to issue the rendering commands to repaint
+ * the screen.
  **/
 public class RenderScriptGL extends RenderScript {
     private Surface mSurface;
     int mWidth;
     int mHeight;
 
+    /**
+     * Class which is used to describe a pixel format for a graphical buffer.
+     * This is used to describe the intended format of the display surface.
+     *
+     */
     public static class SurfaceConfig {
         int mDepthMin       = 0;
         int mDepthPref      = 0;