Merge "More documentation."
diff --git a/graphics/java/android/renderscript/BaseObj.java b/graphics/java/android/renderscript/BaseObj.java
index 026f7de..78b5617 100644
--- a/graphics/java/android/renderscript/BaseObj.java
+++ b/graphics/java/android/renderscript/BaseObj.java
@@ -41,6 +41,13 @@
mID = id;
}
+ /**
+ * Lookup the native object ID for this object. Primarily used by the
+ * generated reflected code.
+ *
+ *
+ * @return int
+ */
public int getID() {
if (mDestroyed) {
throw new RSInvalidStateException("using a destroyed object.");
@@ -53,8 +60,15 @@
private String mName;
RenderScript mRS;
- public void setName(String s) {
- if(s.length() < 1) {
+ /**
+ * setName assigns a name to an object. This object can later be looked up
+ * by this name. This name will also be retained if the object is written
+ * to an A3D file.
+ *
+ * @param name The name to assign to the object.
+ */
+ public void setName(String name) {
+ if(name.length() < 1) {
throw new RSIllegalArgumentException("setName does not accept a zero length string.");
}
if(mName != null) {
@@ -62,9 +76,9 @@
}
try {
- byte[] bytes = s.getBytes("UTF-8");
+ byte[] bytes = name.getBytes("UTF-8");
mRS.nAssignName(mID, bytes);
- mName = s;
+ mName = name;
} catch (java.io.UnsupportedEncodingException e) {
throw new RuntimeException(e);
}
@@ -84,6 +98,12 @@
super.finalize();
}
+ /**
+ * destroy disconnects the object from the native object effectivly
+ * rendering this java object dead. The primary use is to force immediate
+ * cleanup of resources when its believed the GC will not respond quickly
+ * enough.
+ */
synchronized public void destroy() {
if(mDestroyed) {
throw new RSInvalidStateException("Object already destroyed.");
@@ -92,8 +112,10 @@
mRS.nObjDestroy(mID);
}
- // If an object came from an a3d file, java fields need to be
- // created with objects from the native layer
+ /**
+ * If an object came from an a3d file, java fields need to be
+ * created with objects from the native layer
+ */
void updateFromNative() {
mRS.validate();
mName = mRS.nGetName(getID());
diff --git a/graphics/java/android/renderscript/RenderScript.java b/graphics/java/android/renderscript/RenderScript.java
index 64afb6f..df03e13 100644
--- a/graphics/java/android/renderscript/RenderScript.java
+++ b/graphics/java/android/renderscript/RenderScript.java
@@ -28,6 +28,13 @@
/**
* @hide
*
+ * RenderScript base master class. An instance of this class creates native
+ * worker threads for processing commands from this object. This base class
+ * does not provide any extended capabilities beyond simple data processing.
+ * For extended capabilities use derived classes such as RenderScriptGL.
+ *
+ *
+ *
**/
public class RenderScript {
static final String LOG_TAG = "RenderScript_jni";
@@ -581,6 +588,14 @@
///////////////////////////////////////////////////////////////////////////////////
//
+ /**
+ * Base class application should derive from for handling RS messages
+ * comming from their scripts. When a script calls sendToClient the data
+ * fields will be filled in and then the run method called by a message
+ * handling thread. This will occur some time after sendToClient completes
+ * in the script.
+ *
+ */
public static class RSMessage implements Runnable {
protected int[] mData;
protected int mID;
@@ -588,16 +603,42 @@
public void run() {
}
}
+ /**
+ * If an application is expecting messages it should set this field to an
+ * instance of RSMessage. This instance will receive all the user messages
+ * sent from sendToClient by scripts from this context.
+ *
+ */
public RSMessage mMessageCallback = null;
+ /**
+ * Runtime error base class. An application should derive from this class
+ * if it wishes to install an error handler. When errors occur at runtime
+ * the fields in this class will be filled and the run method called.
+ *
+ */
public static class RSAsyncError implements Runnable {
protected String mErrorMessage;
protected int mErrorNum;
public void run() {
}
}
+
+ /**
+ * Application Error handler. All runtime errors will be dispatched to the
+ * instance of RSAsyncError set here. If this field is null a
+ * RSRuntimeException will instead be thrown with details about the error.
+ * This will cause program termaination.
+ *
+ */
public RSAsyncError mErrorCallback = null;
+ /**
+ * RenderScript worker threads priority enumeration. The default value is
+ * NORMAL. Applications wishing to do background processing such as
+ * wallpapers should set their priority to LOW to avoid starving forground
+ * processes.
+ */
public enum Priority {
LOW (5), //ANDROID_PRIORITY_BACKGROUND + 5
NORMAL (-4); //ANDROID_PRIORITY_DISPLAY
@@ -614,6 +655,12 @@
}
}
+
+ /**
+ * Change the priority of the worker threads for this context.
+ *
+ * @param p New priority to be set.
+ */
public void contextSetPriority(Priority p) {
validate();
nContextSetPriority(p.mID);
@@ -690,9 +737,15 @@
}
}
- protected RenderScript() {
+ RenderScript() {
}
+ /**
+ * Create a basic RenderScript context.
+ *
+ *
+ * @return RenderScript
+ */
public static RenderScript create() {
RenderScript rs = new RenderScript();
@@ -704,15 +757,32 @@
return rs;
}
+ /**
+ * Print the currently available debugging information about the state of
+ * the RS context to the log.
+ *
+ *
+ * @param bits Currently ignored.
+ */
public void contextDump(int bits) {
validate();
nContextDump(bits);
}
+ /**
+ * Wait for any commands in the fifo between the java bindings and native to
+ * be processed.
+ *
+ */
public void finish() {
nContextFinish();
}
+ /**
+ * Destroy this renderscript context. Once this function is called its no
+ * longer legal to use this or any objects created by this context.
+ *
+ */
public void destroy() {
validate();
nContextDeinitToClient(mContext);
@@ -733,9 +803,6 @@
return mContext != 0;
}
- ///////////////////////////////////////////////////////////////////////////////////
- // Root state
-
protected int safeID(BaseObj o) {
if(o != null) {
return o.getID();
diff --git a/graphics/java/android/renderscript/RenderScriptGL.java b/graphics/java/android/renderscript/RenderScriptGL.java
index cace063..181d4bd 100644
--- a/graphics/java/android/renderscript/RenderScriptGL.java
+++ b/graphics/java/android/renderscript/RenderScriptGL.java
@@ -30,12 +30,22 @@
/**
* @hide
*
+ * The Graphics derivitive of RenderScript. Extends the basic context to add a
+ * root script which is the display window for graphical output. When the
+ * system needs to update the display the currently bound root script will be
+ * called. This script is expected to issue the rendering commands to repaint
+ * the screen.
**/
public class RenderScriptGL extends RenderScript {
private Surface mSurface;
int mWidth;
int mHeight;
+ /**
+ * Class which is used to describe a pixel format for a graphical buffer.
+ * This is used to describe the intended format of the display surface.
+ *
+ */
public static class SurfaceConfig {
int mDepthMin = 0;
int mDepthPref = 0;