Merge "Unhide intrinsics and document API." into jb-mr1-dev

Author: Jason Sams

api/current.txt

@@ -20043,6 +20043,49 @@ package android.renderscript {
     ctor protected ScriptC(android.renderscript.RenderScript, android.content.res.Resources, int);
   }
 
+  public abstract class ScriptIntrinsic extends android.renderscript.Script {
+  }
+
+  public final class ScriptIntrinsicBlur extends android.renderscript.ScriptIntrinsic {
+    method public static android.renderscript.ScriptIntrinsicBlur create(android.renderscript.RenderScript, android.renderscript.Element);
+    method public void forEach(android.renderscript.Allocation);
+    method public void setInput(android.renderscript.Allocation);
+    method public void setRadius(float);
+  }
+
+  public final class ScriptIntrinsicColorMatrix extends android.renderscript.ScriptIntrinsic {
+    method public static android.renderscript.ScriptIntrinsicColorMatrix create(android.renderscript.RenderScript, android.renderscript.Element);
+    method public void forEach(android.renderscript.Allocation, android.renderscript.Allocation);
+    method public void setColorMatrix(android.renderscript.Matrix4f);
+    method public void setColorMatrix(android.renderscript.Matrix3f);
+    method public void setGreyscale();
+    method public void setRGBtoYUV();
+    method public void setYUVtoRGB();
+  }
+
+  public final class ScriptIntrinsicConvolve3x3 extends android.renderscript.ScriptIntrinsic {
+    method public static android.renderscript.ScriptIntrinsicConvolve3x3 create(android.renderscript.RenderScript, android.renderscript.Element);
+    method public void forEach(android.renderscript.Allocation);
+    method public void setCoefficients(float[]);
+    method public void setInput(android.renderscript.Allocation);
+  }
+
+  public final class ScriptIntrinsicConvolve5x5 extends android.renderscript.ScriptIntrinsic {
+    method public static android.renderscript.ScriptIntrinsicConvolve5x5 create(android.renderscript.RenderScript, android.renderscript.Element);
+    method public void forEach(android.renderscript.Allocation);
+    method public void setCoefficients(float[]);
+    method public void setInput(android.renderscript.Allocation);
+  }
+
+  public final class ScriptIntrinsicLUT extends android.renderscript.ScriptIntrinsic {
+    method public static android.renderscript.ScriptIntrinsicLUT create(android.renderscript.RenderScript, android.renderscript.Element);
+    method public void forEach(android.renderscript.Allocation, android.renderscript.Allocation);
+    method public void setAlpha(int, int);
+    method public void setBlue(int, int);
+    method public void setGreen(int, int);
+    method public void setRed(int, int);
+  }
+
   public class Short2 {
     ctor public Short2();
     ctor public Short2(short, short);

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 @@
 
 
 /**
- * @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);
     }

graphics/java/android/renderscript/ScriptIntrinsicBlur.java

@@ -21,43 +21,72 @@
 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);
     }

graphics/java/android/renderscript/ScriptIntrinsicColorMatrix.java

@@ -20,33 +20,38 @@
 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 @@ private void setMatrix() {
     }
 
     /**
-     * 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.
      */

graphics/java/android/renderscript/ScriptIntrinsicConvolve3x3.java

@@ -20,45 +20,70 @@
 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 void setColorMatrix(float v[]) {
         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);
     }