Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Unhide new ScriptGroup API

Browse Source 
This includes the new class ScriptGroup2 and a related change in
class Script to add InvokeID.

Change-Id: I012dc0a32c65803453022fa534ef05f855ea5ace
This commit is contained in:
Yang Ni
2015-03-16 16:23:50 -07:00
parent eb9a10c829
commit 4470d68a89
3 changed files with 235 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
api/current.txt
View File

@@ -27501,6 +27501,41 @@ package android.renderscript {
method public android.renderscript.ScriptGroup create();
}
public class ScriptGroup2 extends android.renderscript.BaseObj {
ctor public ScriptGroup2(long, android.renderscript.RenderScript);
method public java.lang.Object[] execute(java.lang.Object...);
}
public static final class ScriptGroup2.Binding {
ctor public ScriptGroup2.Binding(android.renderscript.Script.FieldID, java.lang.Object);
method public android.renderscript.Script.FieldID getField();
method public java.lang.Object getValue();
}
public static final class ScriptGroup2.Builder {
ctor public ScriptGroup2.Builder(android.renderscript.RenderScript);
method public android.renderscript.ScriptGroup2.UnboundValue addInput();
method public android.renderscript.ScriptGroup2.Closure addInvoke(android.renderscript.Script.InvokeID, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Closure addInvoke(android.renderscript.Script.InvokeID, java.lang.Object...);
method public android.renderscript.ScriptGroup2.Closure addKernel(android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Closure addKernel(android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object...);
method public android.renderscript.ScriptGroup2 create(android.renderscript.ScriptGroup2.Future...);
}
public static class ScriptGroup2.Closure extends android.renderscript.BaseObj {
ctor public ScriptGroup2.Closure(long, android.renderscript.RenderScript);
ctor public ScriptGroup2.Closure(android.renderscript.RenderScript, android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
ctor public ScriptGroup2.Closure(android.renderscript.RenderScript, android.renderscript.Script.InvokeID, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Future getGlobal(android.renderscript.Script.FieldID);
method public android.renderscript.ScriptGroup2.Future getReturn();
}
public static class ScriptGroup2.Future {
}
public static class ScriptGroup2.UnboundValue {
}
public abstract class ScriptIntrinsic extends android.renderscript.Script {
}

35
api/system-current.txt
View File

@@ -29480,6 +29480,41 @@ package android.renderscript {
method public android.renderscript.ScriptGroup create();
}
public class ScriptGroup2 extends android.renderscript.BaseObj {
ctor public ScriptGroup2(long, android.renderscript.RenderScript);
method public java.lang.Object[] execute(java.lang.Object...);
}
public static final class ScriptGroup2.Binding {
ctor public ScriptGroup2.Binding(android.renderscript.Script.FieldID, java.lang.Object);
method public android.renderscript.Script.FieldID getField();
method public java.lang.Object getValue();
}
public static final class ScriptGroup2.Builder {
ctor public ScriptGroup2.Builder(android.renderscript.RenderScript);
method public android.renderscript.ScriptGroup2.UnboundValue addInput();
method public android.renderscript.ScriptGroup2.Closure addInvoke(android.renderscript.Script.InvokeID, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Closure addInvoke(android.renderscript.Script.InvokeID, java.lang.Object...);
method public android.renderscript.ScriptGroup2.Closure addKernel(android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Closure addKernel(android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object...);
method public android.renderscript.ScriptGroup2 create(android.renderscript.ScriptGroup2.Future...);
}
public static class ScriptGroup2.Closure extends android.renderscript.BaseObj {
ctor public ScriptGroup2.Closure(long, android.renderscript.RenderScript);
ctor public ScriptGroup2.Closure(android.renderscript.RenderScript, android.renderscript.Script.KernelID, android.renderscript.Type, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
ctor public ScriptGroup2.Closure(android.renderscript.RenderScript, android.renderscript.Script.InvokeID, java.lang.Object[], java.util.Map<android.renderscript.Script.FieldID, java.lang.Object>);
method public android.renderscript.ScriptGroup2.Future getGlobal(android.renderscript.Script.FieldID);
method public android.renderscript.ScriptGroup2.Future getReturn();
}
public static class ScriptGroup2.Future {
}
public static class ScriptGroup2.UnboundValue {
}
public abstract class ScriptIntrinsic extends android.renderscript.Script {
}

189
rs/java/android/renderscript/ScriptGroup2.java
View File

@@ -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 Allocation mReturnValue;
private Map<Script.FieldID, Object> mBindings;
@@ -132,7 +146,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);
}
@@ -174,6 +187,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);
@@ -182,6 +201,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);
@@ -234,6 +260,10 @@ public class ScriptGroup2 extends BaseObj {
}
}
/**
* An opaque class for futures
*/
public static class Future {
Closure mClosure;
Script.FieldID mFieldID;
@@ -250,6 +280,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;
@@ -309,6 +343,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, " +
@@ -343,32 +384,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);
@@ -376,6 +480,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);
@@ -383,12 +496,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>();
@@ -398,6 +524,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>();
@@ -407,6 +541,13 @@ public class ScriptGroup2 extends BaseObj {
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 @@ 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;