Improve RS documentation.
bug 8570568
Change-Id: I465fcc8ec3e2cc892dc3cb0067aacf5224338102
diff --git a/graphics/java/android/renderscript/ScriptGroup.java b/graphics/java/android/renderscript/ScriptGroup.java
index 7afdb39..1416641 100644
--- a/graphics/java/android/renderscript/ScriptGroup.java
+++ b/graphics/java/android/renderscript/ScriptGroup.java
@@ -20,24 +20,26 @@
import java.util.ArrayList;
/**
- * ScriptGroup creates a groups of scripts which are executed
- * together based upon upon one execution call as if they were
- * all part of a single script. The scripts may be connected
- * internally or to an external allocation. For the internal
- * connections the intermediate results are not observable after
- * the execution of the script.
+ * ScriptGroup creates a group of kernels that are executed
+ * together with one execution call as if they were a single kernel.
+ * The kernels may be connected internally or to an external allocation.
+ * The intermediate results for internal connections are not observable
+ * after the execution of the script.
* <p>
- * The external connections are grouped into inputs and outputs.
+ * External connections are grouped into inputs and outputs.
* All outputs are produced by a script kernel and placed into a
- * user supplied allocation. Inputs are similar but supply the
- * input of a kernal. Inputs bounds to a script are set directly
- * upon the script.
+ * user-supplied allocation. Inputs provide the input of a kernel.
+ * Inputs bound to script globals are set directly upon the script.
* <p>
* A ScriptGroup must contain at least one kernel. A ScriptGroup
* must contain only a single directed acyclic graph (DAG) of
* script kernels and connections. Attempting to create a
* ScriptGroup with multiple DAGs or attempting to create
* a cycle within a ScriptGroup will throw an exception.
+ * <p>
+ * Currently, all kernels in a ScriptGroup must be from separate
+ * Script objects. Attempting to use multiple kernels from the same
+ * Script object will result in an {@link android.renderscript.RSInvalidStateException}.
*
**/
public final class ScriptGroup extends BaseObj {
@@ -93,8 +95,8 @@
/**
* Sets an input of the ScriptGroup. This specifies an
- * Allocation to be used for the kernels which require a kernel
- * input and that input is provided external to the group.
+ * Allocation to be used for kernels that require an input
+ * Allocation provided from outside of the ScriptGroup.
*
* @param s The ID of the kernel where the allocation should be
* connected.
@@ -113,8 +115,8 @@
/**
* Sets an output of the ScriptGroup. This specifies an
- * Allocation to be used for the kernels which require a kernel
- * output and that output is provided external to the group.
+ * Allocation to be used for the kernels that require an output
+ * Allocation visible after the ScriptGroup is executed.
*
* @param s The ID of the kernel where the allocation should be
* connected.
@@ -133,8 +135,8 @@
/**
* Execute the ScriptGroup. This will run all the kernels in
- * the script. The state of the connecting lines will not be
- * observable after this operation.
+ * the ScriptGroup. No internal connection results will be visible
+ * after execution of the ScriptGroup.
*/
public void execute() {
mRS.nScriptGroupExecute(getID(mRS));
@@ -142,20 +144,25 @@
/**
- * Create a ScriptGroup. There are two steps to creating a
- * ScriptGoup.
+ * Helper class to build a ScriptGroup. A ScriptGroup is
+ * created in two steps.
* <p>
- * First all the Kernels to be used by the group should be
- * added. Once this is done the kernels should be connected.
- * Kernels cannot be added once a connection has been made.
+ * First, all kernels to be used by the ScriptGroup should be added.
* <p>
- * Second, add connections. There are two forms of connections.
- * Kernel to Kernel and Kernel to Field. Kernel to Kernel is
- * higher performance and should be used where possible. The
- * line of connections cannot form a loop. If a loop is detected
- * an exception is thrown.
+ * Second, add connections between kernels. There are two types
+ * of connections: kernel to kernel and kernel to field.
+ * Kernel to kernel allows a kernel's output to be passed to
+ * another kernel as input. Kernel to field allows the output of
+ * one kernel to be bound as a script global. Kernel to kernel is
+ * higher performance and should be used where possible.
* <p>
- * Once all the connections are made a call to create will
+ * A ScriptGroup must contain a single directed acyclic graph (DAG); it
+ * cannot contain cycles. Currently, all kernels used in a ScriptGroup
+ * must come from different Script objects. Additionally, all kernels
+ * in a ScriptGroup must have at least one input, output, or internal
+ * connection.
+ * <p>
+ * Once all connections are made, a call to {@link #create} will
* return the ScriptGroup object.
*
*/
@@ -166,10 +173,10 @@
private int mKernelCount;
/**
- * Create a builder for generating a ScriptGroup.
+ * Create a Builder for generating a ScriptGroup.
*
*
- * @param rs The Renderscript context.
+ * @param rs The RenderScript context.
*/
public Builder(RenderScript rs) {
mRS = rs;