Unhide new ScriptGroup API
This includes the new class ScriptGroup2 and a related change in
class Script to add InvokeID.
Change-Id: I012dc0a32c65803453022fa534ef05f855ea5ace
diff --git a/rs/java/android/renderscript/ScriptGroup2.java b/rs/java/android/renderscript/ScriptGroup2.java
index 4a56572..a5da519 100644
--- a/rs/java/android/renderscript/ScriptGroup2.java
+++ b/rs/java/android/renderscript/ScriptGroup2.java
@@ -24,25 +24,39 @@
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 Allocation mReturnValue;
private Map<Script.FieldID, Object> mBindings;
@@ -132,7 +146,6 @@
UnboundValue unbound = (UnboundValue)obj;
unbound.addReference(this, fieldID);
} else {
- // TODO(yangni): Verify obj not a future.
retrieveValueAndDependenceInfo(rs, i, obj, values,
sizes, depClosures, depFieldIDs);
}
@@ -174,6 +187,12 @@
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);
@@ -182,6 +201,13 @@
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);
@@ -234,6 +260,10 @@
}
}
+ /**
+ * An opaque class for futures
+ */
+
public static class Future {
Closure mClosure;
Script.FieldID mFieldID;
@@ -250,6 +280,10 @@
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;
@@ -309,6 +343,13 @@
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, " +
@@ -343,32 +384,95 @@
}
/**
- @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);
@@ -376,6 +480,15 @@
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);
@@ -383,12 +496,25 @@
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>();
@@ -398,6 +524,14 @@
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>();
@@ -407,6 +541,13 @@
return addInvoke(invoke, args.toArray(), bindingMap);
}
+ /**
+ * Creates a script group
+ *
+ * @param outputs futures intended as outputs of the script group
+ * @return a script group
+ */
+
public ScriptGroup2 create(Future... outputs) {
ScriptGroup2 ret = new ScriptGroup2(mRS, mClosures, mInputs, outputs);
return ret;
@@ -428,7 +569,7 @@
return false;
}
Binding b = (Binding)argsAndBindings[i];
- bindingMap.put(b.mField, b.mValue);
+ bindingMap.put(b.getField(), b.getValue());
}
return true;