Unhide new ScriptGroup API (4470d68a) · Commits · e / os / android_frameworks_base

api/current.txt

+35 −0

Original line number	Diff line number	Diff line
		@@ -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 {
		}

api/system-current.txt

+35 −0

Original line number	Diff line number	Diff line
		@@ -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 {
		}

rs/java/android/renderscript/ScriptGroup2.java

+165 −24

Original line number	Diff line number	Diff line
		@@ -24,24 +24,38 @@ 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.
		******************************
		public class ScriptGroup2 extends BaseObj {

		@hide Pending Android public API approval.
		/**
		* An opaque class for closures
		*/
		public class ScriptGroup2 extends BaseObj {

		public static class Closure extends BaseObj {
		private Allocation mReturnValue;
		@@ -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;