diff options
Diffstat (limited to 'rs/java')
-rw-r--r-- | rs/java/android/renderscript/Allocation.java | 40 | ||||
-rw-r--r-- | rs/java/android/renderscript/AllocationAdapter.java | 6 | ||||
-rw-r--r-- | rs/java/android/renderscript/Element.java | 15 | ||||
-rw-r--r-- | rs/java/android/renderscript/RenderScript.java | 11 | ||||
-rw-r--r-- | rs/java/android/renderscript/Script.java | 27 | ||||
-rw-r--r-- | rs/java/android/renderscript/ScriptGroup2.java | 191 | ||||
-rw-r--r-- | rs/java/android/renderscript/Type.java | 23 |
7 files changed, 220 insertions, 93 deletions
diff --git a/rs/java/android/renderscript/Allocation.java b/rs/java/android/renderscript/Allocation.java index 28547cc..2203850 100644 --- a/rs/java/android/renderscript/Allocation.java +++ b/rs/java/android/renderscript/Allocation.java @@ -273,8 +273,8 @@ public class Allocation extends BaseObj { } /** - * @hide * Enable/Disable AutoPadding for Vec3 elements. + * By default: Diabled. * * @param useAutoPadding True: enable AutoPadding; flase: disable AutoPadding * @@ -802,7 +802,7 @@ public class Allocation extends BaseObj { /** * This is only intended to be used by auto-generated code reflected from - * the RenderScript script files. + * the RenderScript script files and should not be used by developers. * * @param xoff * @param component_number @@ -813,9 +813,8 @@ public class Allocation extends BaseObj { } /** - * @hide * This is only intended to be used by auto-generated code reflected from - * the RenderScript script files. + * the RenderScript script files and should not be used by developers. * * @param xoff * @param yoff @@ -1247,8 +1246,11 @@ public class Allocation extends BaseObj { } /** - * @hide + * Copy a rectangular region from the array into the allocation. + * The array is assumed to be tightly packed. * + * The data type of the array is not required to be the same as + * the element data type. */ private void copy3DRangeFromUnchecked(int xoff, int yoff, int zoff, int w, int h, int d, Object array, Element.DataType dt, int arrayLen) { @@ -1277,7 +1279,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy a rectangular region from the array into the allocation. * The array is assumed to be tightly packed. * @@ -1298,7 +1299,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy a rectangular region into the allocation from another * allocation. * @@ -1422,7 +1422,6 @@ public class Allocation extends BaseObj { } /** - * @hide * This is only intended to be used by auto-generated code reflected from * the RenderScript script files and should not be used by developers. * @@ -1430,7 +1429,7 @@ public class Allocation extends BaseObj { * @param yoff * @param zoff * @param component_number - * @param array + * @param fp */ public void copyToFieldPacker(int xoff, int yoff, int zoff, int component_number, FieldPacker fp) { mRS.validate(); @@ -1508,7 +1507,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * guarantee that the Allocation is compatible with the input buffer. * @@ -1523,7 +1521,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * guarantee that the Allocation is compatible with the input buffer. * @@ -1536,7 +1533,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * guarantee that the Allocation is compatible with the input buffer. * @@ -1549,7 +1545,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * guarantee that the Allocation is compatible with the input buffer. * @@ -1562,7 +1557,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * guarantee that the Allocation is compatible with the input buffer. * @@ -1576,7 +1570,6 @@ public class Allocation extends BaseObj { /** - * @hide * Copy part of this Allocation into an array. This method does not * and will generate exceptions if the Allocation type does not * match the component type of the array passed in. @@ -1592,7 +1585,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * and will generate exceptions if the Allocation type is not a 32 bit * integer type. @@ -1607,7 +1599,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * and will generate exceptions if the Allocation type is not a 16 bit * integer type. @@ -1622,7 +1613,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * and will generate exceptions if the Allocation type is not an 8 bit * integer type. @@ -1637,7 +1627,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy part of this Allocation into an array. This method does not * and will generate exceptions if the Allocation type is not a 32 bit float * type. @@ -1678,7 +1667,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation @@ -1694,7 +1682,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation @@ -1710,7 +1697,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation @@ -1726,7 +1712,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation @@ -1742,7 +1727,6 @@ public class Allocation extends BaseObj { } /** - * @hide * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation @@ -1759,8 +1743,11 @@ public class Allocation extends BaseObj { /** - * @hide + * Copy from a rectangular region in this Allocation into an array. + * The array is assumed to be tightly packed. * + * The data type of the array is not required to be the same as + * the element data type. */ private void copy3DRangeToUnchecked(int xoff, int yoff, int zoff, int w, int h, int d, Object array, Element.DataType dt, int arrayLen) { @@ -1787,8 +1774,7 @@ public class Allocation extends BaseObj { Trace.traceEnd(RenderScript.TRACE_TAG); } - /** - * @hide + /* * Copy from a rectangular region in this Allocation into an array. * * @param xoff X offset of the region to copy in this Allocation diff --git a/rs/java/android/renderscript/AllocationAdapter.java b/rs/java/android/renderscript/AllocationAdapter.java index 183726f..35d59dd 100644 --- a/rs/java/android/renderscript/AllocationAdapter.java +++ b/rs/java/android/renderscript/AllocationAdapter.java @@ -136,7 +136,7 @@ public class AllocationAdapter extends Allocation { /** - * @hide + * * Set the active X. The x value must be within the range for * the allocation being adapted. * @@ -208,7 +208,7 @@ public class AllocationAdapter extends Allocation { } /** - * @hide + * */ public void setArray(int arrayNum, int arrayVal) { if (mAdaptedAllocation.getType().getArray(arrayNum) == 0) { @@ -242,7 +242,7 @@ public class AllocationAdapter extends Allocation { } /** - * @hide + * * * Create an arbitrary window into the base allocation * The type describes the shape of the window. diff --git a/rs/java/android/renderscript/Element.java b/rs/java/android/renderscript/Element.java index 60ff996..4b3e30f 100644 --- a/rs/java/android/renderscript/Element.java +++ b/rs/java/android/renderscript/Element.java @@ -119,9 +119,6 @@ public class Element extends BaseObj { */ public enum DataType { NONE (0, 0), - /** - * @hide - */ FLOAT_16 (1, 2), FLOAT_32 (2, 4), FLOAT_64 (3, 8), @@ -390,9 +387,6 @@ public class Element extends BaseObj { return rs.mElement_I64; } - /** - * @hide - */ public static Element F16(RenderScript rs) { if(rs.mElement_F16 == null) { rs.mElement_F16 = createUser(rs, DataType.FLOAT_16); @@ -534,9 +528,6 @@ public class Element extends BaseObj { return rs.mElement_RGBA_8888; } - /** - * @hide - */ public static Element F16_2(RenderScript rs) { if(rs.mElement_HALF_2 == null) { rs.mElement_HALF_2 = createVector(rs, DataType.FLOAT_16, 2); @@ -544,9 +535,6 @@ public class Element extends BaseObj { return rs.mElement_HALF_2; } - /** - * @hide - */ public static Element F16_3(RenderScript rs) { if(rs.mElement_FLOAT_3 == null) { rs.mElement_FLOAT_3 = createVector(rs, DataType.FLOAT_16, 3); @@ -554,9 +542,6 @@ public class Element extends BaseObj { return rs.mElement_HALF_3; } - /** - * @hide - */ public static Element F16_4(RenderScript rs) { if(rs.mElement_HALF_4 == null) { rs.mElement_HALF_4 = createVector(rs, DataType.FLOAT_16, 4); diff --git a/rs/java/android/renderscript/RenderScript.java b/rs/java/android/renderscript/RenderScript.java index 9f3348c..7c927fd 100644 --- a/rs/java/android/renderscript/RenderScript.java +++ b/rs/java/android/renderscript/RenderScript.java @@ -24,7 +24,6 @@ import android.content.Context; import android.content.res.AssetManager; import android.graphics.Bitmap; import android.graphics.SurfaceTexture; -import android.os.Process; import android.util.Log; import android.view.Surface; import android.os.SystemProperties; @@ -138,7 +137,8 @@ public class RenderScript { * Returns an identifier that can be used to identify a particular * minor version of RS. * - * @hide + * @return The minor RenderScript version number + * */ public static long getMinorID() { return sMinorID; @@ -1310,7 +1310,6 @@ public class RenderScript { /** * Create a RenderScript context. * - * @hide * @param ctx The context. * @return RenderScript */ @@ -1415,14 +1414,13 @@ public class RenderScript { /** * Gets or creates a RenderScript context of the specified type. * - * @hide * @param ctx The context. * @param ct The type of context to be created. * @param sdkVersion The target SDK Version. * @param flags The OR of the CREATE_FLAG_* options desired * @return RenderScript */ - public static RenderScript create(Context ctx, int sdkVersion, ContextType ct, int flags) { + private static RenderScript create(Context ctx, int sdkVersion, ContextType ct, int flags) { if (sdkVersion < 23) { return internalCreate(ctx, sdkVersion, ct, flags); } @@ -1445,8 +1443,6 @@ public class RenderScript { } /** - * @hide - * * Releases all the process contexts. This is the same as * calling .destroy() on each unique context retreived with * create(...). If no contexts have been created this @@ -1483,7 +1479,6 @@ public class RenderScript { * * If you need a single context please use create() * - * @hide * @param ctx The context. * @return RenderScript */ diff --git a/rs/java/android/renderscript/Script.java b/rs/java/android/renderscript/Script.java index 65056ac..6a1efee 100644 --- a/rs/java/android/renderscript/Script.java +++ b/rs/java/android/renderscript/Script.java @@ -66,7 +66,6 @@ public class Script extends BaseObj { } /** - * @hide Pending API review * InvokeID is an identifier for an invoke function. It is used * as an identifier for ScriptGroup creation. * @@ -86,7 +85,6 @@ public class Script extends BaseObj { private final SparseArray<InvokeID> mIIDs = new SparseArray<InvokeID>(); /** - * @hide Pending API review * Only to be used by generated reflected classes. */ protected InvokeID createInvokeID(int slot) { @@ -222,22 +220,21 @@ public class Script extends BaseObj { /** * Only intended for use by generated reflected code. - * - * @hide */ protected void forEach(int slot, Allocation[] ains, Allocation aout, FieldPacker v) { + + // FieldPacker is kept here to support regular params in the future. forEach(slot, ains, aout, v, null); } /** * Only intended for use by generated reflected code. - * - * @hide */ protected void forEach(int slot, Allocation[] ains, Allocation aout, FieldPacker v, LaunchOptions sc) { // TODO: Is this necessary if nScriptForEach calls validate as well? + // FieldPacker is kept here to support regular params in the future. mRS.validate(); if (ains != null) { for (Allocation ain : ains) { @@ -476,7 +473,23 @@ public class Script extends BaseObj { /** - * Class used to specify clipping for a kernel launch. + * Class for specifying the specifics about how a kernel will be + * launched + * + * This class can specify a potential range of cells on which to + * run a kernel. If no set is called for a dimension then this + * class will have no impact on that dimension when the kernel + * is executed. + * + * The forEach launch will operate over the intersection of the + * dimensions. + * + * Example: + * LaunchOptions with setX(5, 15) + * Allocation with dimension X=10, Y=10 + * The resulting forEach run would execute over x = 5 to 10 and + * y = 0 to 10. + * * */ public static final class LaunchOptions { diff --git a/rs/java/android/renderscript/ScriptGroup2.java b/rs/java/android/renderscript/ScriptGroup2.java index 417bbee..96bb6e2 100644 --- a/rs/java/android/renderscript/ScriptGroup2.java +++ b/rs/java/android/renderscript/ScriptGroup2.java @@ -24,25 +24,39 @@ import java.util.List; import java.util.Map; /** + * ScriptGroup2 is a new, enhanced API for script groups. + * A script group is a collection of kernels or invocable functions, with + * data dependencies defined among them. A script group is launched for + * execution as a whole, rather than launching each kernel or invocable function + * separately. Once created, a script group can be repeatedly used with + * different inputs. + * <p> + * In the new ScriptGroup2 API, a script group is modeled using closures. + * A closure, in this context, is defined as a function call to a kernel or + * invocable function. Each function argument or global variable accessed inside + * the function is bound to 1) a known value, 2) a script group input, or 3) a + * future. A future is the output of a closure, i.e., the return value of the + * function or a global variable written by that function. + * <p> + * A script group is a directed acyclic graph (DAG), in which closures are the + * vertices and the dependencies among them are the edges. + * The way the ScriptGroup2 API is designed makes cycles impossible in a script + * group. For example, it is impossible to make forward references to futures, + * i.e., it is impossible to set as input to a closure the future from itself or + * a future from another closure that directly or indirectly depends on it. + * <p> + * Grouping kernels and invocable functions together allows to execute them more + * efficiently. Runtime and compiler optimizations are applied to script + * groups, to reduce computation or communication overhead, and to make more + * efficient use of the CPU and the GPU. + */ -****************************** -You have tried to change the API from what has been previously approved. - -To make these errors go away, you have two choices: -1) You can add "@hide" javadoc comments to the methods, etc. listed in the -errors above. - -2) You can update current.txt by executing the following command: -make update-api - -To submit the revised current.txt to the main Android repository, -you will need approval. -****************************** - -@hide Pending Android public API approval. -*/ public class ScriptGroup2 extends BaseObj { + /** + * An opaque class for closures + */ + public static class Closure extends BaseObj { private Object[] mArgs; private Allocation mReturnValue; @@ -135,7 +149,6 @@ public class ScriptGroup2 extends BaseObj { UnboundValue unbound = (UnboundValue)obj; unbound.addReference(this, fieldID); } else { - // TODO(yangni): Verify obj not a future. retrieveValueAndDependenceInfo(rs, i, obj, values, sizes, depClosures, depFieldIDs); } @@ -177,6 +190,12 @@ public class ScriptGroup2 extends BaseObj { sizes[index] = vs.size; } + /** + * Returns the future for the return value + * + * @return a future + */ + public Future getReturn() { if (mReturnFuture == null) { mReturnFuture = new Future(this, null, mReturnValue); @@ -185,6 +204,13 @@ public class ScriptGroup2 extends BaseObj { return mReturnFuture; } + /** + * Returns the future for a global variable + * + * @param field the field ID for the global variable + * @return a future + */ + public Future getGlobal(Script.FieldID field) { Future f = mGlobalFuture.get(field); @@ -239,6 +265,10 @@ public class ScriptGroup2 extends BaseObj { } } + /** + * An opaque class for futures + */ + public static class Future { Closure mClosure; Script.FieldID mFieldID; @@ -255,6 +285,10 @@ public class ScriptGroup2 extends BaseObj { Object getValue() { return mValue; } } + /** + * An opaque class for unbound values (a.k.a. script group inputs) + */ + public static class UnboundValue { // Either mFieldID or mArgIndex should be set but not both. List<Pair<Closure, Script.FieldID>> mFieldID; @@ -316,6 +350,13 @@ public class ScriptGroup2 extends BaseObj { setID(id); } + /** + * Executes a script group + * + * @param inputs inputs to the script group + * @return outputs of the script group as an array of objects + */ + public Object[] execute(Object... inputs) { if (inputs.length < mInputs.size()) { Log.e(TAG, this.toString() + " receives " + inputs.length + " inputs, " + @@ -350,32 +391,95 @@ public class ScriptGroup2 extends BaseObj { } /** - @hide Pending Android public API approval. - */ + * A class representing a binding of a value to a global variable in a + * kernel or invocable function. Such a binding can be used to create a + * closure. + */ + public static final class Binding { - public Script.FieldID mField; - public Object mValue; + private Script.FieldID mField; + private Object mValue; + + /** + * Returns a Binding object that binds value to field + * + * @param field the Script.FieldID of the global variable + * @param value the value + */ + public Binding(Script.FieldID field, Object value) { mField = field; mValue = value; } + + /** + * Returns the field ID + */ + + public Script.FieldID getField() { return mField; } + + /** + * Returns the value + */ + + public Object getValue() { return mValue; } } /** - @hide Pending Android public API approval. - */ + * The builder class to create a script group. + * <p> + * Closures are created using the {@link #addKernel} or {@link #addInvoke} + * methods. + * When a closure is created, futures from previously created closures + * can be used as inputs. + * Unbound values can be used as inputs to create closures as well. + * An unbound value is created using the {@link #addInput} method. + * Unbound values become inputs to the script group to be created, + * in the order that they are added. + * A script group is created by a call to the {@link #create} method, which + * accepts an array of futures as the outputs for the script group. + * <p> + * Closures in a script group can be evaluated in any order as long as the + * following conditions are met. + * First, a closure must be evaluated before any other closures that take its + * futures as inputs. + * Second, all closures added before an invoke closure must be evaluated + * before it. + * Third, all closures added after an invoke closure must be evaluated after + * it. + * <p> + * As a special case, the order that the closures are added is a legal + * evaluation order. However, other evaluation orders are allowed, including + * concurrently evaluating independent closures. + */ + public static final class Builder { RenderScript mRS; List<Closure> mClosures; List<UnboundValue> mInputs; private static final String TAG = "ScriptGroup2.Builder"; + /** + * Returns a Builder object + * + * @param rs the RenderScript context + */ public Builder(RenderScript rs) { mRS = rs; mClosures = new ArrayList<Closure>(); mInputs = new ArrayList<UnboundValue>(); } + /** + * Adds a closure for a kernel + * + * @param k Kernel ID for the kernel function + * @param returnType Allocation type for the return value + * @param args arguments to the kernel function + * @param globalBindings bindings for global variables + * @return a closure + */ + public Closure addKernel(Script.KernelID k, Type returnType, Object[] args, Map<Script.FieldID, Object> globalBindings) { Closure c = new Closure(mRS, k, returnType, args, globalBindings); @@ -383,6 +487,15 @@ public class ScriptGroup2 extends BaseObj { return c; } + /** + * Adds a closure for an invocable function + * + * @param invoke Invoke ID for the invocable function + * @param args arguments to the invocable function + * @param globalBindings bindings for global variables + * @return a closure + */ + public Closure addInvoke(Script.InvokeID invoke, Object[] args, Map<Script.FieldID, Object> globalBindings) { Closure c = new Closure(mRS, invoke, args, globalBindings); @@ -390,12 +503,25 @@ public class ScriptGroup2 extends BaseObj { return c; } + /** + * Adds a script group input + * + * @return a unbound value that can be used to create a closure + */ public UnboundValue addInput() { UnboundValue unbound = new UnboundValue(); mInputs.add(unbound); return unbound; } + /** + * Adds a closure for a kernel + * + * @param k Kernel ID for the kernel function + * @param argsAndBindings arguments followed by bindings for global variables + * @return a closure + */ + public Closure addKernel(Script.KernelID k, Type returnType, Object... argsAndBindings) { ArrayList<Object> args = new ArrayList<Object>(); Map<Script.FieldID, Object> bindingMap = new HashMap<Script.FieldID, Object>(); @@ -405,6 +531,14 @@ public class ScriptGroup2 extends BaseObj { return addKernel(k, returnType, args.toArray(), bindingMap); } + /** + * Adds a closure for an invocable function + * + * @param invoke Invoke ID for the invocable function + * @param argsAndBindings arguments followed by bindings for global variables + * @return a closure + */ + public Closure addInvoke(Script.InvokeID invoke, Object... argsAndBindings) { ArrayList<Object> args = new ArrayList<Object>(); Map<Script.FieldID, Object> bindingMap = new HashMap<Script.FieldID, Object>(); @@ -414,6 +548,15 @@ public class ScriptGroup2 extends BaseObj { return addInvoke(invoke, args.toArray(), bindingMap); } + /** + * Creates a script group + * + * @param name name for the script group. Legal names can only contain letters, digits, + * '-', or '_'. The name can be no longer than 100 characters. + * @param outputs futures intended as outputs of the script group + * @return a script group + */ + public ScriptGroup2 create(String name, Future... outputs) { if (name == null || name.isEmpty() || name.length() > 100 || !name.equals(name.replaceAll("[^a-zA-Z0-9-]", "_"))) { @@ -439,7 +582,7 @@ public class ScriptGroup2 extends BaseObj { return false; } Binding b = (Binding)argsAndBindings[i]; - bindingMap.put(b.mField, b.mValue); + bindingMap.put(b.getField(), b.getValue()); } return true; diff --git a/rs/java/android/renderscript/Type.java b/rs/java/android/renderscript/Type.java index a58e42c..cc9b58b 100644 --- a/rs/java/android/renderscript/Type.java +++ b/rs/java/android/renderscript/Type.java @@ -150,24 +150,29 @@ public class Type extends BaseObj { } /** - * @hide - */ - public int getArray(int dim) { - if ((dim < 0) || (dim >= mMaxArrays)) { + * Return the dimension of the specified array. + * + * @param arrayNum The array dimension to query + * @return int + */ + public int getArray(int arrayNum) { + if ((arrayNum < 0) || (arrayNum >= mMaxArrays)) { throw new RSIllegalArgumentException("Array dimension out of range."); } - if (mArrays == null || dim >= mArrays.length) { + if (mArrays == null || arrayNum >= mArrays.length) { // Dimension in range but no array for that dimension allocated return 0; } - return mArrays[dim]; + return mArrays[arrayNum]; } /** - * @hide - */ + * Return the number of array dimensions. + * + * @return int + */ public int getArrayCount() { if (mArrays != null) return mArrays.length; return 0; @@ -377,7 +382,7 @@ public class Type extends BaseObj { } /** - * @hide + * Adds an array dimension to the builder * * @param dim * @param value |