Unhide intrinsics and document API.

Change-Id: I0233245c68f9a08780213062e62cfea6cf909c13

6 files changed, 202 insertions, 66 deletions

diff --git a/graphics/java/android/renderscript/ScriptIntrinsic.java b/graphics/java/android/renderscript/ScriptIntrinsic.java
index f275fee..f54943a 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsic.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsic.java
@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2008 The Android Open Source Project
+ * Copyright (C) 2012 The Android Open Source Project
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -22,9 +22,14 @@ import android.util.Log;
 
 
 /**
- * @hide
+ * Base class for all Intrinsic scripts. An intrinsic a script
+ * which implements a pre-defined function. Intrinsics are
+ * provided to provide effecient implemtations of common
+ * operations.
+ *
+ * Not intended for direct use.
  **/
-public class ScriptIntrinsic extends Script {
+public abstract class ScriptIntrinsic extends Script {
     ScriptIntrinsic(int id, RenderScript rs) {
         super(id, rs);
     }
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicBlur.java b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
index 56c5426..8d093a7 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicBlur.java
@@ -21,43 +21,72 @@ import android.content.res.Resources;
 import android.util.Log;
 
 /**
- * @hide
+ * Intrinsic Gausian blur filter. Applies a gaussian blur of the
+ * specified radius to all elements of an allocation.
+ *
+ *
  **/
-public class ScriptIntrinsicBlur extends ScriptIntrinsic {
-    private float[] mValues = new float[9];
+public final class ScriptIntrinsicBlur extends ScriptIntrinsic {
+    private final float[] mValues = new float[9];
     private Allocation mInput;
 
-    ScriptIntrinsicBlur(int id, RenderScript rs) {
+    private ScriptIntrinsicBlur(int id, RenderScript rs) {
         super(id, rs);
     }
 
     /**
-     * Supported elements types are float, float4, uchar, uchar4
+     * Create an intrinsic for applying a blur to an allocation. The
+     * default radius is 5.0.
      *
+     * Supported elements types are {@link Element#U8_4}
      *
-     * @param rs
-     * @param e
+     * @param rs The Renderscript context
+     * @param e Element type for inputs and outputs
      *
-     * @return ScriptIntrinsicConvolve3x3
+     * @return ScriptIntrinsicBlur
      */
     public static ScriptIntrinsicBlur create(RenderScript rs, Element e) {
+        if (e != Element.U8_4(rs)) {
+            throw new RSIllegalArgumentException("Unsuported element type.");
+        }
         int id = rs.nScriptIntrinsicCreate(5, e.getID(rs));
-        return new ScriptIntrinsicBlur(id, rs);
-
+        ScriptIntrinsicBlur sib = new ScriptIntrinsicBlur(id, rs);
+        sib.setRadius(5.f);
+        return sib;
     }
 
+    /**
+     * Set the input of the blur.
+     * Must match the element type supplied during create.
+     *
+     * @param ain The input allocation
+     */
     public void setInput(Allocation ain) {
         mInput = ain;
         bindAllocation(ain, 1);
     }
 
-    public void setRadius(float v) {
-        if (v < 0 || v > 25) {
+    /**
+     * Set the radius of the Blur.
+     *
+     * Supported range 0-25
+     *
+     * @param radius The radius of the blur
+     */
+    public void setRadius(float radius) {
+        if (radius < 0 || radius > 25) {
             throw new RSIllegalArgumentException("Radius out of range (0-25).");
         }
-        setVar(0, v);
+        setVar(0, radius);
     }
 
+    /**
+     * Apply the filter to the input and save to the specified
+     * allocation.
+     *
+     * @param aout Output allocation. Must match creation element
+     *             type.
+     */
     public void forEach(Allocation aout) {
         forEach(0, null, aout, null);
     }
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
index 8cac28e..933a4dd 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java
@@ -20,33 +20,38 @@ import android.content.Context;
 import android.content.res.Resources;
 import android.util.Log;
 
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.Map.Entry;
-import java.util.HashMap;
-
-
 /**
- * @hide
+ * Intrinsic for applying a color matrix to allocations.
+ *
+ * This has the same effect as loading each element and
+ * converting it to a {@link Element#F32_4}, multiplying the
+ * result by the 4x4 color matrix as performed by
+ * rsMatrixMultiply() and writing it to the output after
+ * conversion back to {@link Element#U8_4}.
  **/
-public class ScriptIntrinsicColorMatrix extends ScriptIntrinsic {
-    private Matrix4f mMatrix = new Matrix4f();
+public final class ScriptIntrinsicColorMatrix extends ScriptIntrinsic {
+    private final Matrix4f mMatrix = new Matrix4f();
     private Allocation mInput;
 
-    ScriptIntrinsicColorMatrix(int id, RenderScript rs) {
+    private ScriptIntrinsicColorMatrix(int id, RenderScript rs) {
         super(id, rs);
     }
 
     /**
-     * Supported elements types are uchar4
+     * Create an intrinsic for applying a color matrix to an
+     * allocation.
      *
-     * @param rs
-     * @param e
+     * Supported elements types are {@link Element#U8_4}
+     *
+     * @param rs The Renderscript context
+     * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicColorMatrix
      */
     public static ScriptIntrinsicColorMatrix create(RenderScript rs, Element e) {
+        if (e != Element.U8_4(rs)) {
+            throw new RSIllegalArgumentException("Unsuported element type.");
+        }
         int id = rs.nScriptIntrinsicCreate(2, e.getID(rs));
         return new ScriptIntrinsicColorMatrix(id, rs);
 
@@ -59,7 +64,8 @@ public class ScriptIntrinsicColorMatrix extends ScriptIntrinsic {
     }
 
     /**
-     * Set the color matrix which will be applied to each cell of the image.
+     * Set the color matrix which will be applied to each cell of
+     * the image.
      *
      * @param m The 4x4 matrix to set.
      */
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
index c7465a7..fb2948d 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java
@@ -20,45 +20,70 @@ import android.content.Context;
 import android.content.res.Resources;
 import android.util.Log;
 
-import java.io.File;
-import java.io.IOException;
-import java.io.InputStream;
-import java.util.Map.Entry;
-import java.util.HashMap;
-
-
 /**
- * @hide
+ * Intrinsic for applying a 3x3 convolve to an allocation.
+ *
  **/
-public class ScriptIntrinsicConvolve3x3 extends ScriptIntrinsic {
-    private float[] mValues = new float[9];
+public final class ScriptIntrinsicConvolve3x3 extends ScriptIntrinsic {
+    private final float[] mValues = new float[9];
     private Allocation mInput;
 
-    ScriptIntrinsicConvolve3x3(int id, RenderScript rs) {
+    private ScriptIntrinsicConvolve3x3(int id, RenderScript rs) {
         super(id, rs);
     }
 
     /**
-     * Supported elements types are float, float4, uchar, uchar4
+     * Supported elements types are {@link Element#U8_4}
+     *
+     * The default coefficients are.
      *
+     * <code>
+     * <p> [ 0,  0,  0 ]
+     * <p> [ 0,  1,  0 ]
+     * <p> [ 0,  0,  0 ]
+     * </code>
      *
-     * @param rs
-     * @param e
+     * @param rs The Renderscript context
+     * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicConvolve3x3
      */
     public static ScriptIntrinsicConvolve3x3 create(RenderScript rs, Element e) {
+        float f[] = { 0, 0, 0, 0, 1, 0, 0, 0, 0};
+        if (e != Element.U8_4(rs)) {
+            throw new RSIllegalArgumentException("Unsuported element type.");
+        }
         int id = rs.nScriptIntrinsicCreate(1, e.getID(rs));
-        return new ScriptIntrinsicConvolve3x3(id, rs);
+        ScriptIntrinsicConvolve3x3 si = new ScriptIntrinsicConvolve3x3(id, rs);
+        si.setCoefficients(f);
+        return si;
 
     }
 
+    /**
+     * Set the input of the blur.
+     * Must match the element type supplied during create.
+     *
+     * @param ain The input allocation.
+     */
     public void setInput(Allocation ain) {
         mInput = ain;
         bindAllocation(ain, 1);
     }
 
-    public void setColorMatrix(float v[]) {
+    /**
+     * Set the coefficients for the convolve.
+     *
+     * The convolve layout is
+     * <code>
+     * <p> [ 0,  1,  2 ]
+     * <p> [ 3,  4,  5 ]
+     * <p> [ 6,  7,  8 ]
+     * </code>
+     *
+     * @param v The array of coefficients to set
+     */
+    public void setCoefficients(float v[]) {
         FieldPacker fp = new FieldPacker(9*4);
         for (int ct=0; ct < mValues.length; ct++) {
             mValues[ct] = v[ct];
@@ -67,6 +92,13 @@ public class ScriptIntrinsicConvolve3x3 extends ScriptIntrinsic {
         setVar(0, fp);
     }
 
+    /**
+     * Apply the filter to the input and save to the specified
+     * allocation.
+     *
+     * @param aout Output allocation. Must match creation element
+     *             type.
+     */
     public void forEach(Allocation aout) {
         forEach(0, null, aout, null);
     }
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
index 242623b..8599426 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicConvolve5x5.java
@@ -19,22 +19,31 @@ package android.renderscript;
 import android.util.Log;
 
 /**
- * @hide
+ * Intrinsic for applying a 5x5 convolve to an allocation.
+ *
  **/
-public class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic {
-    private float[] mValues = new float[25];
+public final class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic {
+    private final float[] mValues = new float[25];
     private Allocation mInput;
 
-    ScriptIntrinsicConvolve5x5(int id, RenderScript rs) {
+    private ScriptIntrinsicConvolve5x5(int id, RenderScript rs) {
         super(id, rs);
     }
 
     /**
-     * Supported elements types are float, float4, uchar, uchar4
+     * Supported elements types are {@link Element#U8_4}
      *
+     * The default coefficients are.
+     * <code>
+     * <p> [ 0,  0,  0,  0,  0  ]
+     * <p> [ 0,  0,  0,  0,  0  ]
+     * <p> [ 0,  0,  1,  0,  0  ]
+     * <p> [ 0,  0,  0,  0,  0  ]
+     * <p> [ 0,  0,  0,  0,  0  ]
+     * </code>
      *
-     * @param rs
-     * @param e
+     * @param rs The Renderscript context
+     * @param e Element type for intputs and outputs
      *
      * @return ScriptIntrinsicConvolve5x5
      */
@@ -44,11 +53,31 @@ public class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic {
 
     }
 
+    /**
+     * Set the input of the blur.
+     * Must match the element type supplied during create.
+     *
+     * @param ain The input allocation.
+     */
     public void setInput(Allocation ain) {
         mInput = ain;
         bindAllocation(ain, 1);
     }
 
+    /**
+    * Set the coefficients for the convolve.
+    *
+    * The convolve layout is
+    * <code>
+    * <p> [ 0,  1,  2,  3,  4  ]
+    * <p> [ 5,  6,  7,  8,  9  ]
+    * <p> [ 10, 11, 12, 13, 14 ]
+    * <p> [ 15, 16, 17, 18, 19 ]
+    * <p> [ 20, 21, 22, 23, 24 ]
+    * </code>
+    *
+    * @param v The array of coefficients to set
+    */
     public void setCoefficients(float v[]) {
         FieldPacker fp = new FieldPacker(25*4);
         for (int ct=0; ct < mValues.length; ct++) {
@@ -58,6 +87,13 @@ public class ScriptIntrinsicConvolve5x5 extends ScriptIntrinsic {
         setVar(0, fp);
     }
 
+    /**
+     * Apply the filter to the input and save to the specified
+     * allocation.
+     *
+     * @param aout Output allocation. Must match creation element
+     *             type.
+     */
     public void forEach(Allocation aout) {
         forEach(0, null, aout, null);
     }
diff --git a/graphics/java/android/renderscript/ScriptIntrinsicLUT.java b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
index e7d8d34..e45c0fd 100644
--- a/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
+++ b/graphics/java/android/renderscript/ScriptIntrinsicLUT.java
@@ -20,17 +20,19 @@ import android.content.Context;
 import android.content.res.Resources;
 import android.util.Log;
 
-
 /**
- * @hide
+ * Intrinsic for applying a per-channel lookup table. Each
+ * channel of the input has an independant lookup table. The
+ * tables are 256 entries in size and can cover the full value
+ * range of {@link Element#U8_4}.
  **/
-public class ScriptIntrinsicLUT extends ScriptIntrinsic {
-    private Matrix4f mMatrix = new Matrix4f();
+public final class ScriptIntrinsicLUT extends ScriptIntrinsic {
+    private final Matrix4f mMatrix = new Matrix4f();
     private Allocation mTables;
-    private byte mCache[] = new byte[1024];
+    private final byte mCache[] = new byte[1024];
     private boolean mDirty = true;
 
-    ScriptIntrinsicLUT(int id, RenderScript rs) {
+    private ScriptIntrinsicLUT(int id, RenderScript rs) {
         super(id, rs);
         mTables = Allocation.createSized(rs, Element.U8(rs), 1024);
         for (int ct=0; ct < 256; ct++) {
@@ -43,12 +45,14 @@ public class ScriptIntrinsicLUT extends ScriptIntrinsic {
     }
 
     /**
-     * Supported elements types are uchar4
+     * Supported elements types are {@link Element#U8_4}
+     *
+     * The defaults tables are identity.
      *
-     * @param rs
-     * @param e
+     * @param rs The Renderscript context
+     * @param e Element type for intputs and outputs
      *
-     * @return ScriptIntrinsicColorMatrix
+     * @return ScriptIntrinsicLUT
      */
     public static ScriptIntrinsicLUT create(RenderScript rs, Element e) {
         int id = rs.nScriptIntrinsicCreate(3, e.getID(rs));
@@ -66,24 +70,48 @@ public class ScriptIntrinsicLUT extends ScriptIntrinsic {
         }
     }
 
+    /**
+     * Set an entry in the red channel lookup table
+     *
+     * @param index Must be 0-255
+     * @param value Must be 0-255
+     */
     public void setRed(int index, int value) {
         validate(index, value);
         mCache[index] = (byte)value;
         mDirty = true;
     }
 
+    /**
+     * Set an entry in the green channel lookup table
+     *
+     * @param index Must be 0-255
+     * @param value Must be 0-255
+     */
     public void setGreen(int index, int value) {
         validate(index, value);
         mCache[index+256] = (byte)value;
         mDirty = true;
     }
 
+    /**
+     * Set an entry in the blue channel lookup table
+     *
+     * @param index Must be 0-255
+     * @param value Must be 0-255
+     */
     public void setBlue(int index, int value) {
         validate(index, value);
         mCache[index+512] = (byte)value;
         mDirty = true;
     }
 
+    /**
+     * Set an entry in the alpha channel lookup table
+     *
+     * @param index Must be 0-255
+     * @param value Must be 0-255
+     */
     public void setAlpha(int index, int value) {
         validate(index, value);
         mCache[index+768] = (byte)value;
@@ -92,8 +120,8 @@ public class ScriptIntrinsicLUT extends ScriptIntrinsic {
 
 
     /**
-     * Invoke the kernel and apply the matrix to each cell of ain and copy to
-     * aout.
+     * Invoke the kernel and apply the lookup to each cell of ain
+     * and copy to aout.
      *
      * @param ain Input allocation
      * @param aout Output allocation