From 80d819033d4687507907f787d47379b7b37eae19 Mon Sep 17 00:00:00 2001 From: Jason Sams Date: Thu, 13 Sep 2012 17:00:48 -0700 Subject: Unhide intrinsics and document API. Change-Id: I0233245c68f9a08780213062e62cfea6cf909c13 --- .../java/android/renderscript/ScriptIntrinsic.java | 11 +++- .../android/renderscript/ScriptIntrinsicBlur.java | 55 ++++++++++++++----- .../renderscript/ScriptIntrinsicColorMatrix.java | 36 +++++++----- .../renderscript/ScriptIntrinsicConvolve3x3.java | 64 ++++++++++++++++------ .../renderscript/ScriptIntrinsicConvolve5x5.java | 50 ++++++++++++++--- .../android/renderscript/ScriptIntrinsicLUT.java | 52 ++++++++++++++---- 6 files changed, 202 insertions(+), 66 deletions(-) (limited to 'graphics') 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. * + * + *

[ 0, 0, 0 ] + *

[ 0, 1, 0 ] + *

[ 0, 0, 0 ] + * * - * @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 + * + *

[ 0, 1, 2 ] + *

[ 3, 4, 5 ] + *

[ 6, 7, 8 ] + * + * + * @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. + * + *

[ 0, 0, 0, 0, 0 ] + *

[ 0, 0, 0, 0, 0 ] + *

[ 0, 0, 1, 0, 0 ] + *

[ 0, 0, 0, 0, 0 ] + *

[ 0, 0, 0, 0, 0 ] + * * - * @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 + * + *

[ 0, 1, 2, 3, 4 ] + *

[ 5, 6, 7, 8, 9 ] + *

[ 10, 11, 12, 13, 14 ] + *

[ 15, 16, 17, 18, 19 ] + *

[ 20, 21, 22, 23, 24 ] + * + * + * @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 -- cgit v1.1