Unhide intrinsics and document API.
Change-Id: I0233245c68f9a08780213062e62cfea6cf909c13
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 @@
/**
- * @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.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.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 @@
}
/**
- * 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.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.
*
- * @param rs
- * @param e
+ * <code>
+ * <p> [ 0, 0, 0 ]
+ * <p> [ 0, 1, 0 ]
+ * <p> [ 0, 0, 0 ]
+ * </code>
+ *
+ * @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 @@
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 @@
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 @@
}
+ /**
+ * 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 @@
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.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 @@
}
/**
- * Supported elements types are uchar4
+ * Supported elements types are {@link Element#U8_4}
*
- * @param rs
- * @param e
+ * The defaults tables are identity.
*
- * @return ScriptIntrinsicColorMatrix
+ * @param rs The Renderscript context
+ * @param e Element type for intputs and outputs
+ *
+ * @return ScriptIntrinsicLUT
*/
public static ScriptIntrinsicLUT create(RenderScript rs, Element e) {
int id = rs.nScriptIntrinsicCreate(3, e.getID(rs));
@@ -66,24 +70,48 @@
}
}
+ /**
+ * 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 @@
/**
- * 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