Merge "Basic 101 level compute example for RS." into honeycomb
diff --git a/core/java/android/nfc/NfcAdapter.java b/core/java/android/nfc/NfcAdapter.java
index d30a0c6..622bcdb 100644
--- a/core/java/android/nfc/NfcAdapter.java
+++ b/core/java/android/nfc/NfcAdapter.java
@@ -26,14 +26,17 @@
import android.content.IntentFilter;
import android.content.pm.IPackageManager;
import android.content.pm.PackageManager;
+import android.nfc.tech.MifareClassic;
+import android.nfc.tech.Ndef;
+import android.nfc.tech.NfcA;
+import android.nfc.tech.NfcF;
import android.os.IBinder;
-import android.os.Parcel;
import android.os.RemoteException;
import android.os.ServiceManager;
import android.util.Log;
/**
- * Represents the device's local NFC adapter.
+ * Represents the local NFC adapter.
* <p>
* Use the helper {@link #getDefaultAdapter(Context)} to get the default NFC
* adapter for this Android device.
@@ -43,30 +46,85 @@
/**
* Intent to start an activity when a tag with NDEF payload is discovered.
- * If the tag has and NDEF payload this intent is started before
- * {@link #ACTION_TECH_DISCOVERED}.
*
- * If any activities respond to this intent neither
+ * <p>The system inspects the first {@link NdefRecord} in the first {@link NdefMessage} and
+ * looks for a URI, SmartPoster, or MIME record. If a URI or SmartPoster record is found the
+ * intent will contain the URI in its data field. If a MIME record is found the intent will
+ * contain the MIME type in its type field. This allows activities to register
+ * {@link IntentFilter}s targeting specific content on tags. Activities should register the
+ * most specific intent filters possible to avoid the activity chooser dialog, which can
+ * disrupt the interaction with the tag as the user interacts with the screen.
+ *
+ * <p>If the tag has an NDEF payload this intent is started before
+ * {@link #ACTION_TECH_DISCOVERED}. If any activities respond to this intent neither
* {@link #ACTION_TECH_DISCOVERED} or {@link #ACTION_TAG_DISCOVERED} will be started.
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_NDEF_DISCOVERED = "android.nfc.action.NDEF_DISCOVERED";
/**
- * Intent to started when a tag is discovered. The data URI is formated as
- * {@code vnd.android.nfc://tag/} with the path having a directory entry for each technology
- * in the {@link Tag#getTechList()} is sorted ascending order.
+ * Intent to start an activity when a tag is discovered and activities are registered for the
+ * specific technologies on the tag.
*
- * This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before
- * {@link #ACTION_TAG_DISCOVERED}
+ * <p>To receive this intent an activity must include an intent filter
+ * for this action and specify the desired tech types in a
+ * manifest <code>meta-data</code> entry. Here is an example manfiest entry:
+ * <pre>
+ * <activity android:name=".nfc.TechFilter" android:label="NFC/TechFilter">
+ * <!-- Add a technology filter -->
+ * <intent-filter>
+ * <action android:name="android.nfc.action.TECH_DISCOVERED" />
+ * </intent-filter>
*
- * If any activities respond to this intent {@link #ACTION_TAG_DISCOVERED} will not be started.
+ * <meta-data android:name="android.nfc.action.TECH_DISCOVERED"
+ * android:resource="@xml/filter_nfc"
+ * />
+ * </activity>
+ * </pre>
+ *
+ * <p>The meta-data XML file should contain one or more <code>tech-list</code> entries
+ * each consisting or one or more <code>tech</code> entries. The <code>tech</code> entries refer
+ * to the qualified class name implementing the technology, for example "android.nfc.tech.NfcA".
+ *
+ * <p>A tag matches if any of the
+ * <code>tech-list</code> sets is a subset of {@link Tag#getTechList() Tag.getTechList()}. Each
+ * of the <code>tech-list</code>s is considered independently and the
+ * activity is considered a match is any single <code>tech-list</code> matches the tag that was
+ * discovered. This provides AND and OR semantics for filtering desired techs. Here is an
+ * example that will match any tag using {@link NfcF} or any tag using {@link NfcA},
+ * {@link MifareClassic}, and {@link Ndef}:
+ *
+ * <pre>
+ * <resources xmlns:xliff="urn:oasis:names:tc:xliff:document:1.2">
+ * <!-- capture anything using NfcF -->
+ * <tech-list>
+ * <tech>android.nfc.tech.NfcF</tech>
+ * </tech-list>
+ *
+ * <!-- OR -->
+ *
+ * <!-- capture all MIFARE Classics with NDEF payloads -->
+ * <tech-list>
+ * <tech>android.nfc.tech.NfcA</tech>
+ * <tech>android.nfc.tech.MifareClassic</tech>
+ * <tech>android.nfc.tech.Ndef</tech>
+ * </tech-list>
+ * </resources>
+ * </pre>
+ *
+ * <p>This intent is started after {@link #ACTION_NDEF_DISCOVERED} and before
+ * {@link #ACTION_TAG_DISCOVERED}. If any activities respond to {@link #ACTION_NDEF_DISCOVERED}
+ * this intent will not be started. If any activities respond to this intent
+ * {@link #ACTION_TAG_DISCOVERED} will not be started.
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_TECH_DISCOVERED = "android.nfc.action.TECH_DISCOVERED";
/**
* Intent to start an activity when a tag is discovered.
+ *
+ * <p>This intent will not be started when a tag is discovered if any activities respond to
+ * {@link #ACTION_NDEF_DISCOVERED} or {@link #ACTION_TECH_DISCOVERED} for the current tag.
*/
@SdkConstant(SdkConstantType.ACTIVITY_INTENT_ACTION)
public static final String ACTION_TAG_DISCOVERED = "android.nfc.action.TAG_DISCOVERED";
@@ -78,17 +136,23 @@
public static final String ACTION_TAG_LEFT_FIELD = "android.nfc.action.TAG_LOST";
/**
- * Mandatory Tag extra for the ACTION_TAG intents.
+ * Mandatory extra containing the {@link Tag} that was discovered for the
+ * {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+ * {@link #ACTION_TAG_DISCOVERED} intents.
*/
public static final String EXTRA_TAG = "android.nfc.extra.TAG";
/**
- * Optional NdefMessage[] extra for the ACTION_TAG intents.
+ * Optional extra containing an array of {@link NdefMessage} present on the discovered tag for
+ * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+ * {@link #ACTION_TAG_DISCOVERED} intents.
*/
public static final String EXTRA_NDEF_MESSAGES = "android.nfc.extra.NDEF_MESSAGES";
/**
- * Optional byte[] extra for the tag identifier.
+ * Optional extra containing a byte array containing the ID of the discovered tag for
+ * the {@link #ACTION_NDEF_DISCOVERED}, {@link #ACTION_TECH_DISCOVERED}, and
+ * {@link #ACTION_TAG_DISCOVERED} intents.
*/
public static final String EXTRA_ID = "android.nfc.extra.ID";
@@ -359,14 +423,13 @@
/**
* Return true if this NFC Adapter has any features enabled.
- * <p>
- * If this method returns false, then applications should request the user
- * turn on NFC tag discovery in Settings.
- * <p>
- * If this method returns false, the NFC hardware is guaranteed not to
- * perform or respond to any NFC communication.
*
- * @return true if this NFC Adapter is enabled to discover new tags
+ * <p>Application may use this as a helper to suggest that the user
+ * should turn on NFC in Settings.
+ * <p>If this method returns false, the NFC hardware is guaranteed not to
+ * generate or respond to any NFC transactions.
+ *
+ * @return true if this NFC Adapter has any features enabled
*/
public boolean isEnabled() {
try {
@@ -414,17 +477,37 @@
}
/**
- * Enables foreground dispatching to the given Activity. This will force all NFC Intents that
- * match the given filters to be delivered to the activity bypassing the standard dispatch
- * mechanism. If no IntentFilters are given all the PendingIntent will be invoked for every
- * dispatch Intent.
+ * Enable foreground dispatch to the given Activity.
*
- * This method must be called from the main thread.
+ * <p>This will give give priority to the foreground activity when
+ * dispatching a discovered {@link Tag} to an application.
+ *
+ * <p>If any IntentFilters are provided to this method they are used to match dispatch Intents
+ * for both the {@link NfcAdapter#ACTION_NDEF_DISCOVERED} and
+ * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. Since {@link NfcAdapter#ACTION_TECH_DISCOVERED}
+ * relies on meta data outside of the IntentFilter matching for that dispatch Intent is handled
+ * by passing in the tech lists separately. Each first level entry in the tech list represents
+ * an array of technologies that must all be present to match. If any of the first level sets
+ * match then the dispatch is routed through the given PendingIntent. In other words, the second
+ * level is ANDed together and the first level entries are ORed together.
+ *
+ * <p>If you pass {@code null} for both the {@code filters} and {@code techLists} parameters
+ * that acts a wild card and will cause the foreground activity to receive all tags via the
+ * {@link NfcAdapter#ACTION_TAG_DISCOVERED} intent.
+ *
+ * <p>This method must be called from the main thread, and only when the activity is in the
+ * foreground (resumed). Also, activities must call {@link #disableForegroundDispatch} before
+ * the completion of their {@link Activity#onPause} callback to disable foreground dispatch
+ * after it has been enabled.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param activity the Activity to dispatch to
* @param intent the PendingIntent to start for the dispatch
* @param filters the IntentFilters to override dispatching for, or null to always dispatch
- * @throws IllegalStateException
+ * @param techLists the tech lists used to perform matching for dispatching of the
+ * {@link NfcAdapter#ACTION_TECH_DISCOVERED} intent
+ * @throws IllegalStateException if the Activity is not currently in the foreground
*/
public void enableForegroundDispatch(Activity activity, PendingIntent intent,
IntentFilter[] filters, String[][] techLists) {
@@ -450,13 +533,18 @@
}
/**
- * Disables foreground activity dispatching setup with
- * {@link #enableForegroundDispatch}.
+ * Disable foreground dispatch to the given activity.
*
- * <p>This must be called before the Activity returns from
- * it's <code>onPause()</code> or this method will throw an IllegalStateException.
+ * <p>After calling {@link #enableForegroundDispatch}, an activity
+ * must call this method before its {@link Activity#onPause} callback
+ * completes.
*
* <p>This method must be called from the main thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param activity the Activity to disable dispatch to
+ * @throws IllegalStateException if the Activity has already been paused
*/
public void disableForegroundDispatch(Activity activity) {
ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,
@@ -484,13 +572,24 @@
}
/**
- * Enable NDEF message push over P2P while this Activity is in the foreground. For this to
- * function properly the other NFC device being scanned must support the "com.android.npp"
- * NDEF push protocol.
+ * Enable NDEF message push over P2P while this Activity is in the foreground.
*
- * <p><em>NOTE</em> While foreground NDEF push is active standard tag dispatch is disabled.
+ * <p>For this to function properly the other NFC device being scanned must
+ * support the "com.android.npp" NDEF push protocol. Support for this
+ * protocol is currently optional for Android NFC devices.
+ *
+ * <p>This method must be called from the main thread.
+ *
+ * <p class="note"><em>NOTE:</em> While foreground NDEF push is active standard tag dispatch is disabled.
* Only the foreground activity may receive tag discovered dispatches via
* {@link #enableForegroundDispatch}.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param activity the foreground Activity
+ * @param msg a NDEF Message to push over P2P
+ * @throws IllegalStateException if the Activity is not currently in the foreground
+ * @throws OperationNotSupportedException if this Android device does not support NDEF push
*/
public void enableForegroundNdefPush(Activity activity, NdefMessage msg) {
if (activity == null || msg == null) {
@@ -510,13 +609,19 @@
}
/**
- * Disables foreground NDEF push setup with
- * {@link #enableForegroundNdefPush}.
+ * Disable NDEF message push over P2P.
*
- * <p>This must be called before the Activity returns from
- * it's <code>onPause()</code> or this method will throw an IllegalStateException.
+ * <p>After calling {@link #enableForegroundNdefPush}, an activity
+ * must call this method before its {@link Activity#onPause} callback
+ * completes.
*
* <p>This method must be called from the main thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param activity the Foreground activity
+ * @throws IllegalStateException if the Activity has already been paused
+ * @throws OperationNotSupportedException if this Android device does not support NDEF push
*/
public void disableForegroundNdefPush(Activity activity) {
ActivityThread.currentActivityThread().unregisterOnActivityPausedListener(activity,
diff --git a/core/java/android/nfc/NfcSecureElement.java b/core/java/android/nfc/NfcSecureElement.java
index ea2846e..3b5f39e 100755
--- a/core/java/android/nfc/NfcSecureElement.java
+++ b/core/java/android/nfc/NfcSecureElement.java
@@ -35,8 +35,8 @@
private static final String TAG = "NfcSecureElement";
private INfcSecureElement mService;
-
-
+
+
/**
* @hide
*/
@@ -68,7 +68,7 @@
public byte [] exchangeAPDU(int handle,byte [] data) throws IOException {
-
+
// Perform exchange APDU
try {
@@ -85,7 +85,7 @@
}
public void closeSecureElementConnection(int handle) throws IOException {
-
+
try {
int status = mService.closeSecureElementConnection(handle);
// Handle potential errors
@@ -96,14 +96,14 @@
Log.e(TAG, "RemoteException in closeSecureElement(): ", e);
}
}
-
-
+
+
/**
* Returns target type. constants.
- *
+ *
* @return Secure Element technology type. The possible values are defined in
* {@link TagTechnology}
- *
+ *
*/
public int[] getSecureElementTechList(int handle) throws IOException {
try {
@@ -113,16 +113,16 @@
return null;
}
}
-
+
/**
* Returns Secure Element UID.
- *
+ *
* @return Secure Element UID.
*/
public byte[] getSecureElementUid(int handle) throws IOException {
-
+
byte[] uid = null;
- try {
+ try {
uid = mService.getSecureElementUid(handle);
// Handle potential errors
if (uid == null) {
diff --git a/core/java/android/nfc/Tag.java b/core/java/android/nfc/Tag.java
index 45a3447..b676975 100644
--- a/core/java/android/nfc/Tag.java
+++ b/core/java/android/nfc/Tag.java
@@ -16,6 +16,7 @@
package android.nfc;
+import android.content.Context;
import android.nfc.tech.IsoDep;
import android.nfc.tech.MifareClassic;
import android.nfc.tech.MifareUltralight;
@@ -33,27 +34,76 @@
import java.util.Arrays;
/**
- * Represents a (generic) discovered tag.
+ * Represents an NFC tag that has been discovered.
* <p>
- * A tag is a passive NFC element, such as NFC Forum Tag's, MIFARE class Tags,
- * Sony FeliCa Tags, etc.
+ * {@link Tag} is an immutable object that represents the state of a NFC tag at
+ * the time of discovery. It can be used as a handle to {@link TagTechnology} classes
+ * to perform advanced operations, or directly queried for its ID via {@link #getId} and the
+ * set of technologies it contains via {@link #getTechList}. Arrays passed to and
+ * returned by this class are <em>not</em> cloned, so be careful not to modify them.
* <p>
- * Tag's have a type and usually have a UID.
+ * A new tag object is created every time a tag is discovered (comes into range), even
+ * if it is the same physical tag. If a tag is removed and then returned into range, then
+ * only the most recent tag object can be successfully used to create a {@link TagTechnology}.
+ *
+ * <h3>Tag Dispatch</h3>
+ * When a tag is discovered, a {@link Tag} object is created and passed to a
+ * single activity via the {@link NfcAdapter#EXTRA_TAG} extra in an
+ * {@link android.content.Intent} via {@link Context#startActivity}. A four stage dispatch is used
+ * to select the
+ * most appropriate activity to handle the tag. The Android OS executes each stage in order,
+ * and completes dispatch as soon as a single matching activity is found. If there are multiple
+ * matching activities found at any one stage then the Android activity chooser dialog is shown
+ * to allow the user to select the activity to receive the tag.
+ *
+ * <p>The Tag dispatch mechanism was designed to give a high probability of dispatching
+ * a tag to the correct activity without showing the user an activity chooser dialog.
+ * This is important for NFC interactions because they are very transient -- if a user has to
+ * move the Android device to choose an application then the connection will likely be broken.
+ *
+ * <h4>1. Foreground activity dispatch</h4>
+ * A foreground activity that has called
+ * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} is
+ * given priority. See the documentation on
+ * {@link NfcAdapter#enableForegroundDispatch NfcAdapter.enableForegroundDispatch()} for
+ * its usage.
+ * <h4>2. NDEF data dispatch</h4>
+ * If the tag contains NDEF data the system inspects the first {@link NdefRecord} in the first
+ * {@link NdefMessage}. If the record is a URI, SmartPoster, or MIME data
+ * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_NDEF_DISCOVERED}. For URI
+ * and SmartPoster records the URI is put into the intent's data field. For MIME records the MIME
+ * type is put in the intent's type field. This allows activities to register to be launched only
+ * when data they know how to handle is present on a tag. This is the preferred method of handling
+ * data on a tag since NDEF data can be stored on many types of tags and doesn't depend on a
+ * specific tag technology.
+ * See {@link NfcAdapter#ACTION_NDEF_DISCOVERED} for more detail. If the tag does not contain
+ * NDEF data, or if no activity is registered
+ * for {@link NfcAdapter#ACTION_NDEF_DISCOVERED} with a matching data URI or MIME type then dispatch
+ * moves to stage 3.
+ * <h4>3. Tag Technology dispatch</h4>
+ * {@link Context#startActivity} is called with {@link NfcAdapter#ACTION_TECH_DISCOVERED} to
+ * dispatch the tag to an activity that can handle the technologies present on the tag.
+ * Technologies are defined as sub-classes of {@link TagTechnology}, see the package
+ * {@link android.nfc.tech}. The Android OS looks for an activity that can handle one or
+ * more technologies in the tag. See {@link NfcAdapter#ACTION_TECH_DISCOVERED} for more detail.
+ * <h4>4. Fall-back dispatch</h4>
+ * If no activity has been matched then {@link Context#startActivity} is called with
+ * {@link NfcAdapter#ACTION_TAG_DISCOVERED}. This is intended as a fall-back mechanism.
+ * See {@link NfcAdapter#ACTION_TAG_DISCOVERED}.
+ *
+ * <h3>NFC Tag Background</h3>
+ * An NFC tag is a passive NFC device, powered by the NFC field of this Android device while
+ * it is in range. Tag's can come in many forms, such as stickers, cards, key fobs, or
+ * even embedded in a more sophisticated device.
* <p>
- * {@link Tag} objects are passed to applications via the {@link NfcAdapter#EXTRA_TAG} extra
- * in {@link NfcAdapter#ACTION_TAG_DISCOVERED} intents. A {@link Tag} object is immutable
- * and represents the state of the tag at the time of discovery. It can be
- * directly queried for its UID and Type, or used to create a {@link TagTechnology} using the
- * static <code>get()</code> methods on the varios tech classes.
+ * Tags can have a wide range of capabilities. Simple tags just offer read/write semantics,
+ * and contain some one time
+ * programmable areas to make read-only. More complex tags offer math operations
+ * and per-sector access control and authentication. The most sophisticated tags
+ * contain operating environments allowing complex interactions with the
+ * code executing on the tag. Use {@link TagTechnology} classes to access a broad
+ * range of capabilities available in NFC tags.
* <p>
- * A {@link Tag} can be used to create a {@link TagTechnology} only while the tag is in
- * range. If it is removed and then returned to range, then the most recent
- * {@link Tag} object (in {@link NfcAdapter#ACTION_TAG_DISCOVERED}) should be used to create a
- * {@link TagTechnology}.
- * <p>This is an immutable data class. All properties are set at Tag discovery
- * time and calls on this class will retrieve those read-only properties, and
- * not cause any further RF activity or block. Note however that arrays passed to and
- * returned by this class are *not* cloned, so be careful not to modify them.
*/
public final class Tag implements Parcelable {
/*package*/ final byte[] mId;
@@ -149,21 +199,35 @@
/**
* Get the Tag Identifier (if it has one).
- * <p>Tag ID is usually a serial number for the tag.
- *
- * @return ID, or null if it does not exist
+ * <p>The tag identifier is a low level serial number, used for anti-collision
+ * and identification.
+ * <p> Most tags have a stable unique identifier
+ * (UID), but some tags will generate a random ID every time they are discovered
+ * (RID), and there are some tags with no ID at all (the byte array will be zero-sized).
+ * <p> The size and format of an ID is specific to the RF technology used by the tag.
+ * <p> This function retrieves the ID as determined at discovery time, and does not
+ * perform any further RF communication or block.
+ * @return ID as byte array, never null
*/
public byte[] getId() {
return mId;
}
/**
- * Returns technologies present in the tag that this implementation understands,
- * or a zero length array if there are no supported technologies on this tag.
- *
- * The elements of the list are the names of the classes implementing the technology.
- *
+ * Get the technologies available in this tag, as fully qualified class names.
+ * <p>
+ * A technology is an implementation of the {@link TagTechnology} interface,
+ * and can be instantiated by calling the static <code>get(Tag)</code>
+ * method on the implementation with this Tag. The {@link TagTechnology}
+ * object can then be used to perform advanced, technology-specific operations on a tag.
+ * <p>
+ * Android defines a mandatory set of technologies that must be correctly
+ * enumerated by all Android NFC devices, and an optional
+ * set of proprietary technologies.
+ * See {@link TagTechnology} for more details.
+ * <p>
* The ordering of the returned array is undefined and should not be relied upon.
+ * @return an array of fully-qualified {@link TagTechnology} class-names.
*/
public String[] getTechList() {
return mTechStringList;
@@ -176,7 +240,7 @@
}
return false;
}
-
+
/** @hide */
public Bundle getTechExtras(int tech) {
int pos = -1;
@@ -198,6 +262,9 @@
return mTagService;
}
+ /**
+ * Human-readable description of the tag, for debugging.
+ */
@Override
public String toString() {
StringBuilder sb = new StringBuilder("TAG ")
diff --git a/core/java/android/nfc/tech/IsoDep.java b/core/java/android/nfc/tech/IsoDep.java
index 774982e..9c3074b 100644
--- a/core/java/android/nfc/tech/IsoDep.java
+++ b/core/java/android/nfc/tech/IsoDep.java
@@ -24,18 +24,17 @@
import java.io.IOException;
/**
- * A low-level connection to a {@link Tag} using the ISO-DEP technology, also known as
- * ISO1443-4.
+ * Provides access to ISO-DEP (ISO 14443-4) properties and I/O operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
- * Use this class to send and receive data with {@link #transceive transceive()}.
+ * <p>Acquire an {@link IsoDep} object using {@link #get}.
+ * <p>The primary ISO-DEP I/O operation is {@link #transceive}. Applications must
+ * implement their own protocol stack on top of {@link #transceive}.
+ * <p>Tags that enumerate the {@link IsoDep} technology in {@link Tag#getTechList}
+ * will also enumerate
+ * {@link NfcA} or {@link NfcB} (since IsoDep builds on top of either of these).
*
- * <p>Applications must implement their own protocol stack on top of
- * {@link #transceive transceive()}.
- *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class IsoDep extends BasicTagTechnology {
private static final String TAG = "NFC";
@@ -49,10 +48,13 @@
private byte[] mHistBytes = null;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link IsoDep} for the given tag.
+ * <p>Does not cause any RF activity and does not block.
+ * <p>Returns null if {@link IsoDep} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag does not support ISO-DEP.
*
- * @param tag The tag to get the tech from
+ * @param tag an ISO-DEP compatible tag
+ * @return ISO-DEP object
*/
public static IsoDep get(Tag tag) {
if (!tag.hasTech(TagTechnology.ISO_DEP)) return null;
@@ -62,7 +64,7 @@
return null;
}
}
-
+
/** @hide */
public IsoDep(Tag tag)
throws RemoteException {
@@ -75,13 +77,16 @@
}
/**
- * Sets the timeout of an IsoDep transceive transaction in milliseconds.
- * If the transaction has not completed before the timeout,
- * any ongoing {@link #transceive} operation will be
- * aborted and the connection to the tag is lost. This setting is applied
- * only to the {@link Tag} object linked to this technology and will be
- * reset when {@link IsoDep#close} is called.
- * The default transaction timeout is 300 milliseconds.
+ * Set the timeout of {@link #transceive} in milliseconds.
+ * <p>The timeout only applies to ISO-DEP {@link #transceive}, and is
+ * reset to a default value when {@link #close} is called.
+ * <p>Setting a longer timeout may be useful when performing
+ * transactions that require a long processing time on the tag
+ * such as key generation.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param timeout timeout value in milliseconds
*/
public void setTimeout(int timeout) {
try {
@@ -102,29 +107,53 @@
}
/**
- * Return the historical bytes if the tag is using {@link NfcA}, null otherwise.
+ * Return the ISO-DEP historical bytes for {@link NfcA} tags.
+ * <p>Does not cause any RF activity and does not block.
+ * <p>The historical bytes can be used to help identify a tag. They are present
+ * only on {@link IsoDep} tags that are based on {@link NfcA} RF technology.
+ * If this tag is not {@link NfcA} then null is returned.
+ * <p>In ISO 14443-4 terminology, the historical bytes are a subset of the RATS
+ * response.
+ *
+ * @return ISO-DEP historical bytes, or null if this is not a {@link NfcA} tag
*/
public byte[] getHistoricalBytes() {
return mHistBytes;
}
/**
- * Return the hi layer response bytes if the tag is using {@link NfcB}, null otherwise.
+ * Return the higher layer response bytes for {@link NfcB} tags.
+ * <p>Does not cause any RF activity and does not block.
+ * <p>The higher layer response bytes can be used to help identify a tag.
+ * They are present only on {@link IsoDep} tags that are based on {@link NfcB}
+ * RF technology. If this tag is not {@link NfcB} then null is returned.
+ * <p>In ISO 14443-4 terminology, the higher layer bytes are a subset of the
+ * ATTRIB response.
+ *
+ * @return ISO-DEP historical bytes, or null if this is not a {@link NfcB} tag
*/
public byte[] getHiLayerResponse() {
return mHiLayerResponse;
}
/**
- * Send data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
+ * Send raw ISO-DEP data to the tag and receive the response.
*
- * @param data bytes to send
- * @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * <p>Applications must only send the INF payload, and not the start of frame and
+ * end of frame indicators. Applications do not need to fragment the payload, it
+ * will be automatically fragmented and defragmented by {@link #transceive} if
+ * it exceeds FSD/FSC limits.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param data command bytes to send, must not be null
+ * @return response bytes received, will not be null
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or this operation is canceled
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/MifareClassic.java b/core/java/android/nfc/tech/MifareClassic.java
index d337ead..9a2f2bd 100644
--- a/core/java/android/nfc/tech/MifareClassic.java
+++ b/core/java/android/nfc/tech/MifareClassic.java
@@ -25,32 +25,64 @@
import java.nio.ByteOrder;
/**
- * Technology class representing MIFARE Classic tags (also known as MIFARE Standard).
+ * Provides access to MIFARE Classic properties and I/O operations on a {@link Tag}.
*
- * <p>Support for this technology type is optional. If the NFC stack doesn't support this technology
- * MIFARE Classic tags will still be scanned, but will only show the NfcA technology.
+ * <p>Acquire a {@link MifareClassic} object using {@link #get}.
*
- * <p>MIFARE Classic tags have sectors that each contain blocks. The block size is constant at
- * 16 bytes, but the number of sectors and the sector size varies by product. MIFARE has encryption
- * built in and each sector has two keys associated with it, as well as ACLs to determine what
- * level acess each key grants. Before operating on a sector you must call either
- * {@link #authenticateSectorWithKeyA(int, byte[])} or
- * {@link #authenticateSectorWithKeyB(int, byte[])} to gain authorization for your request.
+ * <p>MIFARE Classic is also known as MIFARE Standard.
+ * <p>MIFARE Classic tags are divided into sectors, and each sector is sub-divided into
+ * blocks. Block size is always 16 bytes ({@link #BLOCK_SIZE}. Sector size varies.
+ * <ul>
+ * <li>MIFARE Classic Mini are 320 bytes ({@link #SIZE_MINI}), with 5 sectors each of 4 blocks.
+ * <li>MIFARE Classic 1k are 1024 bytes ({@link #SIZE_1K}), with 16 sectors each of 4 blocks.
+ * <li>MIFARE Classic 2k are 2048 bytes ({@link #SIZE_2K}), with 32 sectors each of 4 blocks.
+ * <li>MIFARE Classic 4k} are 4096 bytes ({@link #SIZE_4K}). The first 32 sectors contain 4 blocks
+ * and the last 8 sectors contain 16 blocks.
+ * </ul>
+ *
+ * <p>MIFARE Classic tags require authentication on a per-sector basis before any
+ * other I/O operations on that sector can be performed. There are two keys per sector,
+ * and ACL bits determine what I/O operations are allowed on that sector after
+ * authenticating with a key. {@see #authenticateSectorWithKeyA} and
+ * {@see #authenticateSectorWithKeyB}.
+ *
+ * <p>Three well-known authentication keys are defined in this class:
+ * {@link #KEY_DEFAULT}, {@link #KEY_MIFARE_APPLICATION_DIRECTORY},
+ * {@link #KEY_NFC_FORUM}.
+ * <ul>
+ * <li>{@link #KEY_DEFAULT} is the default factory key for MIFARE Classic.
+ * <li>{@link #KEY_MIFARE_APPLICATION_DIRECTORY} is the well-known key for
+ * MIFARE Classic cards that have been formatted according to the
+ * MIFARE Application Directory (MAD) specification.
+ * <li>{@link #KEY_NFC_FORUM} is the well-known key for MIFARE Classic cards that
+ * have been formatted according to the NXP specification for NDEF on MIFARE Classic.
+ *
+ * <p>Implementation of this class on a Android NFC device is optional.
+ * If it is not implemented, then
+ * {@link MifareClassic} will never be enumerated in {@link Tag#getTechList}.
+ * If it is enumerated, then all {@link MifareClassic} I/O operations will be supported,
+ * and {@link Ndef#MIFARE_CLASSIC} NDEF tags will also be supported. In either case,
+ * {@link NfcA} will also be enumerated on the tag, because all MIFARE Classic tags are also
+ * {@link NfcA}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class MifareClassic extends BasicTagTechnology {
/**
- * The well-known default MIFARE read key. All keys are set to this at the factory.
- * Using this key will effectively make the payload in the sector public.
+ * The default factory key.
*/
public static final byte[] KEY_DEFAULT =
{(byte)0xFF,(byte)0xFF,(byte)0xFF,(byte)0xFF,(byte)0xFF,(byte)0xFF};
/**
- * The well-known, default MIFARE Application Directory read key.
+ * The well-known key for tags formatted according to the
+ * MIFARE Application Directory (MAD) specification.
*/
public static final byte[] KEY_MIFARE_APPLICATION_DIRECTORY =
{(byte)0xA0,(byte)0xA1,(byte)0xA2,(byte)0xA3,(byte)0xA4,(byte)0xA5};
/**
- * The well-known, default read key for NDEF data on a MIFARE Classic
+ * The well-known key for tags formatted according to the
+ * NDEF on Mifare Classic specification.
*/
public static final byte[] KEY_NFC_FORUM =
{(byte)0xD3,(byte)0xF7,(byte)0xD3,(byte)0xF7,(byte)0xD3,(byte)0xF7};
@@ -64,19 +96,19 @@
/** A MIFARE Pro tag */
public static final int TYPE_PRO = 2;
- /** The tag contains 16 sectors, each holding 4 blocks. */
+ /** Tag contains 16 sectors, each with 4 blocks. */
public static final int SIZE_1K = 1024;
- /** The tag contains 32 sectors, each holding 4 blocks. */
+ /** Tag contains 32 sectors, each with 4 blocks. */
public static final int SIZE_2K = 2048;
/**
- * The tag contains 40 sectors. The first 32 sectors contain 4 blocks and the last 8 sectors
+ * Tag contains 40 sectors. The first 32 sectors contain 4 blocks and the last 8 sectors
* contain 16 blocks.
*/
public static final int SIZE_4K = 4096;
- /** The tag contains 5 sectors, each holding 4 blocks. */
+ /** Tag contains 5 sectors, each with 4 blocks. */
public static final int SIZE_MINI = 320;
- /** Size of a Mifare Classic block (in bytes) */
+ /** Size of a MIFARE Classic block (in bytes) */
public static final int BLOCK_SIZE = 16;
private static final int MAX_BLOCK_COUNT = 256;
@@ -87,10 +119,14 @@
private int mSize;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link MifareClassic} for the given tag.
+ * <p>Does not cause any RF activity and does not block.
+ * <p>Returns null if {@link MifareClassic} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag is not MIFARE Classic compatible, or this Android
+ * device does not support MIFARE Classic.
*
- * @param tag The tag to get the tech from
+ * @param tag an MIFARE Classic compatible tag
+ * @return MIFARE Classic object
*/
public static MifareClassic get(Tag tag) {
if (!tag.hasTech(TagTechnology.MIFARE_CLASSIC)) return null;
@@ -160,17 +196,31 @@
}
}
- /** Returns the type of the tag, determined at discovery time */
+ /**
+ * Return the type of this MIFARE Classic compatible tag.
+ * <p>One of {@link #TYPE_UNKNOWN}, {@link #TYPE_CLASSIC}, {@link #TYPE_PLUS} or
+ * {@link #TYPE_PRO}.
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return type
+ */
public int getType() {
return mType;
}
- /** Returns the size of the tag in bytes, determined at discovery time */
+ /**
+ * Return the size of the tag in bytes
+ * <p>One of {@link #SIZE_MINI}, {@link #SIZE_1K}, {@link #SIZE_2K}, {@link #SIZE_4K}.
+ * These constants are equal to their respective size in bytes.
+ * <p>Does not cause any RF activity and does not block.
+ * @return size in bytes
+ */
public int getSize() {
return mSize;
}
- /** Returns true if the tag is emulated, determined at discovery time.
+ /**
+ * Return true if the tag is emulated, determined at discovery time.
* These are actually smart-cards that emulate a Mifare Classic interface.
* They can be treated identically to a Mifare Classic tag.
* @hide
@@ -179,7 +229,11 @@
return mIsEmulated;
}
- /** Returns the number of sectors on this tag, determined at discovery time */
+ /**
+ * Return the number of MIFARE Classic sectors.
+ * <p>Does not cause any RF activity and does not block.
+ * @return number of sectors
+ */
public int getSectorCount() {
switch (mSize) {
case SIZE_1K:
@@ -195,12 +249,22 @@
}
}
- /** Returns the total block count, determined at discovery time */
+ /**
+ * Return the total number of MIFARE Classic blocks.
+ * <p>Does not cause any RF activity and does not block.
+ * @return total number of blocks
+ */
public int getBlockCount() {
return mSize / BLOCK_SIZE;
}
- /** Returns the block count for the given sector, determined at discovery time */
+ /**
+ * Return the number of blocks in the given sector.
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @param sectorIndex index of sector, starting from 0
+ * @return number of blocks in the sector
+ */
public int getBlockCountInSector(int sectorIndex) {
validateSector(sectorIndex);
@@ -211,7 +275,13 @@
}
}
- /** Return the sector index of a given block */
+ /**
+ * Return the sector that contains a given block.
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @param blockIndex index of block to lookup, starting from 0
+ * @return sector index that contains the block
+ */
public int blockToSector(int blockIndex) {
validateBlock(blockIndex);
@@ -222,7 +292,13 @@
}
}
- /** Return the first block of a given sector */
+ /**
+ * Return the first block of a given sector.
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @param sectorIndex index of sector to lookup, starting from 0
+ * @return block index of first block in sector
+ */
public int sectorToBlock(int sectorIndex) {
if (sectorIndex < 32) {
return sectorIndex * 4;
@@ -231,22 +307,55 @@
}
}
- // Methods that require connect()
/**
- * Authenticate a sector.
- * <p>Every sector has an A and B key with different access privileges,
- * this method attempts to authenticate against the A key.
- * <p>This requires a that the tag be connected.
+ * Authenticate a sector with key A.
+ *
+ * <p>Successful authentication of a sector with key A enables other
+ * I/O operations on that sector. The set of operations granted by key A
+ * key depends on the ACL bits set in that sector. For more information
+ * see the MIFARE Classic specification on {@see http://www.nxp.com}.
+ *
+ * <p>A failed authentication attempt causes an implicit reconnection to the
+ * tag, so authentication to other sectors will be lost.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param sectorIndex index of sector to authenticate, starting from 0
+ * @param key 6-byte authentication key
+ * @return true on success, false on authentication failure
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public boolean authenticateSectorWithKeyA(int sectorIndex, byte[] key) throws IOException {
return authenticate(sectorIndex, key, true);
}
/**
- * Authenticate a sector.
- * <p>Every sector has an A and B key with different access privileges,
- * this method attempts to authenticate against the B key.
- * <p>This requires a that the tag be connected.
+ * Authenticate a sector with key B.
+ *
+ * <p>Successful authentication of a sector with key B enables other
+ * I/O operations on that sector. The set of operations granted by key B
+ * depends on the ACL bits set in that sector. For more information
+ * see the MIFARE Classic specification on {@see http://www.nxp.com}.
+ *
+ * <p>A failed authentication attempt causes an implicit reconnection to the
+ * tag, so authentication to other sectors will be lost.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param sectorIndex index of sector to authenticate, starting from 0
+ * @param key 6-byte authentication key
+ * @return true on success, false on authentication failure
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public boolean authenticateSectorWithKeyB(int sectorIndex, byte[] key) throws IOException {
return authenticate(sectorIndex, key, false);
@@ -291,8 +400,17 @@
/**
* Read 16-byte block.
- * <p>This requires a that the tag be connected.
- * @throws IOException
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to read, starting from 0
+ * @return 16 byte block
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public byte[] readBlock(int blockIndex) throws IOException {
validateBlock(blockIndex);
@@ -304,8 +422,17 @@
/**
* Write 16-byte block.
- * <p>This requires a that the tag be connected.
- * @throws IOException
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to write, starting from 0
+ * @param data 16 bytes of data to write
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void writeBlock(int blockIndex, byte[] data) throws IOException {
validateBlock(blockIndex);
@@ -323,9 +450,18 @@
}
/**
- * Increment a value block, and store the result in temporary memory.
- * @param blockIndex
- * @throws IOException
+ * Increment a value block, storing the result in the temporary block on the tag.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to increment, starting from 0
+ * @param value non-negative to increment by
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void increment(int blockIndex, int value) throws IOException {
validateBlock(blockIndex);
@@ -342,9 +478,18 @@
}
/**
- * Decrement a value block, and store the result in temporary memory.
- * @param blockIndex
- * @throws IOException
+ * Decrement a value block, storing the result in the temporary block on the tag.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to decrement, starting from 0
+ * @param value non-negative to decrement by
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void decrement(int blockIndex, int value) throws IOException {
validateBlock(blockIndex);
@@ -361,9 +506,17 @@
}
/**
- * Copy from temporary memory to value block.
- * @param blockIndex
- * @throws IOException
+ * Copy from the temporary block to a value block.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to copy to
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void transfer(int blockIndex) throws IOException {
validateBlock(blockIndex);
@@ -375,9 +528,17 @@
}
/**
- * Copy from value block to temporary memory.
- * @param blockIndex
- * @throws IOException
+ * Copy from a value block to the temporary block.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param blockIndex index of block to copy from
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void restore(int blockIndex) throws IOException {
validateBlock(blockIndex);
@@ -390,15 +551,18 @@
/**
* Send raw NfcA data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
- * <p>This requires a that the tag be connected.
*
- * @param data bytes to send
- * @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * <p>This is equivalent to connecting to this tag via {@link NfcA}
+ * and calling {@link NfcA#transceive}. Note that all MIFARE Classic
+ * tags are based on {@link NfcA} technology.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @see NfcA#transceive
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/MifareUltralight.java b/core/java/android/nfc/tech/MifareUltralight.java
index b514f1c..f7fee72 100644
--- a/core/java/android/nfc/tech/MifareUltralight.java
+++ b/core/java/android/nfc/tech/MifareUltralight.java
@@ -17,6 +17,7 @@
package android.nfc.tech;
import android.nfc.Tag;
+import android.nfc.TagLostException;
import android.os.RemoteException;
import java.io.IOException;
@@ -24,14 +25,13 @@
//TOOD: Ultralight C 3-DES authentication, one-way counter
/**
- * Technology class representing MIFARE Ultralight and MIFARE Ultralight C tags.
+ * Provides access to MIFARE Ultralight properties and I/O operations on a {@link Tag}.
*
- * <p>Support for this technology type is optional. If the NFC stack doesn't support this technology
- * MIFARE Ultralight class tags will still be scanned, but will only show the NfcA technology.
+ * <p>Acquire a {@link MifareUltralight} object using {@link #get}.
*
- * <p>MIFARE Ultralight compatible tags have 4 byte pages. The read command
- * returns 4 pages (16 bytes) at a time, for speed. The write command operates
- * on a single page (4 bytes) to minimize EEPROM write cycles.
+ * <p>MIFARE Ultralight compatible tags have 4 byte pages {@link #PAGE_SIZE}.
+ * The primary operations on an Ultralight tag are {@link #readPages} and
+ * {@link #writePage}.
*
* <p>The original MIFARE Ultralight consists of a 64 byte EEPROM. The first
* 4 pages are for the OTP area, manufacturer data, and locking bits. They are
@@ -44,6 +44,16 @@
* and authentication configuration and are readable. The final 4 pages are for
* the authentication key and are not readable. For more information see the
* NXP data sheet MF0ICU2.
+ *
+ * <p>Implementation of this class on a Android NFC device is optional.
+ * If it is not implemented, then
+ * {@link MifareUltralight} will never be enumerated in {@link Tag#getTechList}.
+ * If it is enumerated, then all {@link MifareUltralight} I/O operations will be supported.
+ * In either case, {@link NfcA} will also be enumerated on the tag,
+ * because all MIFARE Ultralight tags are also {@link NfcA} tags.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class MifareUltralight extends BasicTagTechnology {
/** A MIFARE Ultralight compatible tag of unknown type */
@@ -62,10 +72,15 @@
private int mType;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link MifareUltralight} for the given tag.
+ * <p>Returns null if {@link MifareUltralight} was not enumerated in
+ * {@link Tag#getTechList} - this indicates the tag is not MIFARE
+ * Ultralight compatible, or that this Android
+ * device does not implement MIFARE Ultralight.
+ * <p>Does not cause any RF activity and does not block.
*
- * @param tag The tag to get the tech from
+ * @param tag an MIFARE Ultralight compatible tag
+ * @return MIFARE Ultralight object
*/
public static MifareUltralight get(Tag tag) {
if (!tag.hasTech(TagTechnology.MIFARE_ULTRALIGHT)) return null;
@@ -93,28 +108,43 @@
}
}
- /** Returns the type of the tag.
- * <p>It is very hard to always accurately classify a MIFARE Ultralight
- * compatible tag as Ultralight original or Ultralight C. So consider
- * {@link #getType} a hint. */
+ /**
+ * Return the MIFARE Ultralight type of the tag.
+ * <p>One of {@link #TYPE_ULTRALIGHT} or {@link #TYPE_ULTRALIGHT_C} or
+ * {@link #TYPE_UNKNOWN}.
+ * <p>Depending on how the tag has been formatted, it can be impossible
+ * to accurately classify between original MIFARE Ultralight and
+ * Ultralight C. So treat this method as a hint.
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return the type
+ */
public int getType() {
return mType;
}
- // Methods that require connect()
/**
* Read 4 pages (16 bytes).
- * <p>The MIFARE Ultralight protocol always reads 4 pages at a time.
- * <p>If the read spans past the last readable block, then the tag will
+ *
+ * <p>The MIFARE Ultralight protocol always reads 4 pages at a time, to
+ * reduce the number of commands required to read an entire tag.
+ * <p>If a read spans past the last readable block, then the tag will
* return pages that have been wrapped back to the first blocks. MIFARE
* Ultralight tags have readable blocks 0x00 through 0x0F. So a read to
* block offset 0x0E would return blocks 0x0E, 0x0F, 0x00, 0x01. MIFARE
* Ultralight C tags have readable blocks 0x00 through 0x2B. So a read to
* block 0x2A would return blocks 0x2A, 0x2B, 0x00, 0x01.
- * <p>This requires that the tag be connected.
*
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param pageOffset index of first page to read, starting from 0
* @return 4 pages (16 bytes)
- * @throws IOException
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public byte[] readPages(int pageOffset) throws IOException {
validatePageOffset(pageOffset);
@@ -126,12 +156,20 @@
/**
* Write 1 page (4 bytes).
- * <p>The MIFARE Ultralight protocol always writes 1 page at a time.
- * <p>This requires that the tag be connected.
*
- * @param pageOffset The offset of the page to write
- * @param data The data to write
- * @throws IOException
+ * <p>The MIFARE Ultralight protocol always writes 1 page at a time, to
+ * minimize EEPROM write cycles.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param pageOffset index of page to write, starting from 0
+ * @param data 4 bytes to write
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public void writePage(int pageOffset, byte[] data) throws IOException {
validatePageOffset(pageOffset);
@@ -147,15 +185,18 @@
/**
* Send raw NfcA data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
- * <p>This requires a that the tag be connected.
*
- * @param data bytes to send
- * @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * <p>This is equivalent to connecting to this tag via {@link NfcA}
+ * and calling {@link NfcA#transceive}. Note that all MIFARE Classic
+ * tags are based on {@link NfcA} technology.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @see NfcA#transceive
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/Ndef.java b/core/java/android/nfc/tech/Ndef.java
index 39ff282..6727d6ad 100644
--- a/core/java/android/nfc/tech/Ndef.java
+++ b/core/java/android/nfc/tech/Ndef.java
@@ -22,6 +22,7 @@
import android.nfc.NdefMessage;
import android.nfc.NfcAdapter;
import android.nfc.Tag;
+import android.nfc.TagLostException;
import android.os.Bundle;
import android.os.RemoteException;
import android.util.Log;
@@ -29,15 +30,44 @@
import java.io.IOException;
/**
- * A high-level connection to a {@link Tag} using one of the NFC type 1, 2, 3, or 4 technologies
- * to interact with NDEF data. MiFare Classic cards that present NDEF data may also be used
- * via this class. To determine the exact technology being used call {@link #getType()}
+ * Provides access to NDEF content and operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
+ * <p>Acquire a {@link Ndef} object using {@link #get}.
*
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p>NDEF is an NFC Forum data format. The data formats are implemented in
+ * {@link android.nfc.NdefMessage} and
+ * {@link android.nfc.NdefRecord}. This class provides methods to
+ * retrieve and modify the {@link android.nfc.NdefMessage}
+ * on a tag.
+ *
+ * <p>There are currently four NFC Forum standardized tag types that can be
+ * formatted to contain NDEF data.
+ * <ul>
+ * <li>NFC Forum Type 1 Tag ({@link #NFC_FORUM_TYPE_1}), such as the Innovision Topaz
+ * <li>NFC Forum Type 2 Tag ({@link #NFC_FORUM_TYPE_2}), such as the NXP MIFARE Ultralight
+ * <li>NFC Forum Type 3 Tag ({@link #NFC_FORUM_TYPE_3}), such as Sony Felica
+ * <li>NFC Forum Type 4 Tag ({@link #NFC_FORUM_TYPE_4}), such as NXP MIFARE Desfire
+ * </ul>
+ * It is mandatory for all Android devices with NFC to correctly enumerate
+ * {@link Ndef} on NFC Forum Tag Types 1-4, and implement all NDEF operations
+ * as defined in this class.
+ *
+ * <p>Some vendors have there own well defined specifications for storing NDEF data
+ * on tags that do not fall into the above categories. Android devices with NFC
+ * should enumerate and implement {@link Ndef} under these vendor specifications
+ * where possible, but it is not mandatory. {@link #getType} returns a String
+ * describing this specification, for example {@link #MIFARE_CLASSIC} is
+ * <code>com.nxp.ndef.mifareclassic</code>.
+ *
+ * <p>Android devices that support MIFARE Classic must also correctly
+ * implement {@link Ndef} on MIFARE Classic tags formatted to NDEF.
+ *
+ * <p>For guaranteed compatibility across all Android devices with NFC, it is
+ * recommended to use NFC Forum Types 1-4 in new deployments of NFC tags
+ * with NDEF payload. Vendor NDEF formats will not work on all Android devices.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class Ndef extends BasicTagTechnology {
private static final String TAG = "NFC";
@@ -77,14 +107,15 @@
/** @hide */
public static final String UNKNOWN = "android.ndef.unknown";
+ /** NFC Forum Tag Type 1 */
public static final String NFC_FORUM_TYPE_1 = "org.nfcforum.ndef.type1";
-
+ /** NFC Forum Tag Type 2 */
public static final String NFC_FORUM_TYPE_2 = "org.nfcforum.ndef.type2";
-
+ /** NFC Forum Tag Type 4 */
public static final String NFC_FORUM_TYPE_3 = "org.nfcforum.ndef.type3";
-
+ /** NFC Forum Tag Type 4 */
public static final String NFC_FORUM_TYPE_4 = "org.nfcforum.ndef.type4";
-
+ /** NDEF on MIFARE Classic */
public static final String MIFARE_CLASSIC = "com.nxp.ndef.mifareclassic";
private final int mMaxNdefSize;
@@ -93,10 +124,17 @@
private final int mNdefType;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link Ndef} for the given tag.
*
- * @param tag The tag to get the tech from
+ * <p>Returns null if {@link Ndef} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag is not NDEF formatted, or that this tag
+ * is NDEF formatted but under a vendor specification that this Android
+ * device does not implement.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @param tag an MIFARE Classic compatible tag
+ * @return MIFARE Classic object
*/
public static Ndef get(Tag tag) {
if (!tag.hasTech(TagTechnology.NDEF)) return null;
@@ -126,22 +164,29 @@
}
/**
- * Get the primary NDEF message on this tag. This data is read at discovery time
- * and does not require a connection.
+ * Get the {@link NdefMessage} that was read from the tag at discovery time.
+ *
+ * <p>If the NDEF Message is modified by an I/O operation then it
+ * will not be updated here, this function only returns what was discovered
+ * when the tag entered the field.
+ * <p>Does not cause any RF activity and does not block.
+ * @return NDEF Message read from the tag at discovery time
*/
public NdefMessage getCachedNdefMessage() {
return mNdefMsg;
}
/**
- * Get NDEF tag type.
+ * Get the NDEF tag type.
+ *
* <p>Returns one of {@link #NFC_FORUM_TYPE_1}, {@link #NFC_FORUM_TYPE_2},
* {@link #NFC_FORUM_TYPE_3}, {@link #NFC_FORUM_TYPE_4},
- * {@link #MIFARE_CLASSIC} or another NDEF tag type that is not yet in the
- * Android API.
- * <p>Android devices with NFC support must always correctly enumerate
- * NFC Forum tag types, and may optionally enumerate
- * {@link #MIFARE_CLASSIC} since it requires proprietary technology.
+ * {@link #MIFARE_CLASSIC} or another NDEF tag type that has not yet been
+ * formalized in this Android API.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return a string representing the NDEF tag type
*/
public String getType() {
switch (mNdefType) {
@@ -161,25 +206,44 @@
}
/**
- * Get maximum NDEF message size in bytes
+ * Get the maximum NDEF message size in bytes.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return size in bytes
*/
public int getMaxSize() {
return mMaxNdefSize;
}
/**
- * Provides a hint on whether writes are likely to succeed.
+ * Determine if the tag is writable.
+ *
+ * <p>NFC Forum tags can be in read-only or read-write states.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
* <p>Requires {@link android.Manifest.permission#NFC} permission.
- * @return true if write is likely to succeed
+ *
+ * @return true if the tag is writable
*/
public boolean isWritable() {
return (mCardState == NDEF_MODE_READ_WRITE);
}
- // Methods that require connect()
/**
- * Get the primary NDEF message on this tag. This data is read actively
- * and requires a connection.
+ * Read the current {@link android.nfc.NdefMessage} on this tag.
+ *
+ * <p>This always reads the current NDEF Message stored on the tag.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * @return the NDEF Message, never null
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
+ * @throws FormatException if the NDEF Message on the tag is malformed
*/
public NdefMessage getNdefMessage() throws IOException, FormatException {
checkConnected();
@@ -212,8 +276,18 @@
}
/**
- * Overwrite the primary NDEF message
- * @throws IOException
+ * Overwrite the {@link NdefMessage} on this tag.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param msg the NDEF Message to write, must not be null
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
+ * @throws FormatException if the NDEF Message to write is malformed
*/
public void writeNdefMessage(NdefMessage msg) throws IOException, FormatException {
checkConnected();
@@ -244,8 +318,11 @@
}
/**
- * Indicates whether a tag can be made read-only with
- * {@link #makeReadOnly()}
+ * Indicates whether a tag can be made read-only with {@link #makeReadOnly()}.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return true if it is possible to make this tag read-only
*/
public boolean canMakeReadOnly() {
if (mNdefType == TYPE_1 || mNdefType == TYPE_2) {
@@ -256,11 +333,22 @@
}
/**
- * Sets the CC field to indicate this tag is read-only
- * and permanently sets the lock bits to prevent any further NDEF
- * modifications.
- * This is a one-way process and can not be reverted!
- * @throws IOException
+ * Make a tag read-only.
+ *
+ * <p>This sets the CC field to indicate the tag is read-only,
+ * and where possible permanently sets the lock bits to prevent
+ * any further modification of the memory.
+ * <p>This is a one-way process and cannot be reverted!
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @return true on success, false if it is not possible to make this tag read-only
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
*/
public boolean makeReadOnly() throws IOException {
checkConnected();
diff --git a/core/java/android/nfc/tech/NdefFormatable.java b/core/java/android/nfc/tech/NdefFormatable.java
index e2828b5..bb2eb94 100644
--- a/core/java/android/nfc/tech/NdefFormatable.java
+++ b/core/java/android/nfc/tech/NdefFormatable.java
@@ -22,28 +22,39 @@
import android.nfc.NdefMessage;
import android.nfc.NfcAdapter;
import android.nfc.Tag;
+import android.nfc.TagLostException;
import android.os.RemoteException;
import android.util.Log;
import java.io.IOException;
/**
- * An interface to a {@link Tag} allowing to format the tag as NDEF.
+ * Provide access to NDEF format operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
+ * <p>Acquire a {@link NdefFormatable} object using {@link #get}.
*
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p>Android devices with NFC must only enumerate and implement this
+ * class for tags for which it can format to NDEF.
+ *
+ * <p>Unfortunately the procedures to convert unformated tags to NDEF formatted
+ * tags are not specified by NFC Forum, and are not generally well-known. So
+ * there is no mandatory set of tags for which all Android devices with NFC
+ * must support {@link NdefFormatable}.
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class NdefFormatable extends BasicTagTechnology {
private static final String TAG = "NFC";
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link NdefFormatable} for the given tag.
+ * <p>Does not cause any RF activity and does not block.
+ * <p>Returns null if {@link NdefFormatable} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag is not NDEF formatable by this Android device.
*
- * @param tag The tag to get the tech from
+ * @param tag an NDEF formatable tag
+ * @return NDEF formatable object
*/
public static NdefFormatable get(Tag tag) {
if (!tag.hasTech(TagTechnology.NDEF_FORMATABLE)) return null;
@@ -63,20 +74,44 @@
}
/**
- * Formats a tag as NDEF, if possible. You may supply a first
- * NdefMessage to be written on the tag.
- * <p>Either all steps succeed, or an IOException is thrown if any one step
- * fails.
+ * Format a tag as NDEF, and write a {@link NdefMessage}.
+ *
+ * <p>This is a multi-step process, an IOException is thrown
+ * if any one step fails.
+ * <p>The card is left in a read-write state after this operation.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param firstMessage the NDEF message to write after formatting, can be null
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
+ * @throws FormatException if the NDEF Message to write is malformed
*/
public void format(NdefMessage firstMessage) throws IOException, FormatException {
format(firstMessage, false);
}
/**
- * Formats a tag as NDEF, if possible. You may supply a first
- * NdefMessage to be written on the tag.
- * <p>Either all steps succeed, or an IOException is thrown if any one step
- * fails.
+ * Formats a tag as NDEF, write a {@link NdefMessage}, and make read-only.
+ *
+ * <p>This is a multi-step process, an IOException is thrown
+ * if any one step fails.
+ * <p>The card is left in a read-only state if this method returns successfully.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
+ *
+ * @param firstMessage the NDEF message to write after formatting
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or the operation is canceled
+ * @throws FormatException if the NDEF Message to write is malformed
*/
public void formatReadOnly(NdefMessage firstMessage) throws IOException, FormatException {
format(firstMessage, true);
diff --git a/core/java/android/nfc/tech/NfcA.java b/core/java/android/nfc/tech/NfcA.java
index 24badc4..1843eae 100644
--- a/core/java/android/nfc/tech/NfcA.java
+++ b/core/java/android/nfc/tech/NfcA.java
@@ -23,18 +23,14 @@
import java.io.IOException;
/**
- * A low-level connection to a {@link Tag} using the NFC-A technology, also known as
- * ISO1443-3A.
+ * Provides access to NFC-A (ISO 14443-3A) properties and I/O operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
- * Use this class to send and receive data with {@link #transceive transceive()}.
+ * <p>Acquire a {@link NfcA} object using {@link #get}.
+ * <p>The primary NFC-A I/O operation is {@link #transceive}. Applications must
+ * implement their own protocol stack on top of {@link #transceive}.
*
- * <p>Applications must implement their own protocol stack on top of
- * {@link #transceive transceive()}.
- *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class NfcA extends BasicTagTechnology {
/** @hide */
@@ -46,10 +42,13 @@
private byte[] mAtqa;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link NfcA} for the given tag.
+ * <p>Returns null if {@link NfcA} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag does not support NFC-A.
+ * <p>Does not cause any RF activity and does not block.
*
- * @param tag The tag to get the tech from
+ * @param tag an NFC-A compatible tag
+ * @return NFC-A object
*/
public static NfcA get(Tag tag) {
if (!tag.hasTech(TagTechnology.NFC_A)) return null;
@@ -69,29 +68,46 @@
}
/**
- * Returns the ATQA/SENS_RES bytes discovered at tag discovery.
+ * Return the ATQA/SENS_RES bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return ATQA/SENS_RES bytes
*/
public byte[] getAtqa() {
return mAtqa;
}
/**
- * Returns the SAK/SEL_RES discovered at tag discovery.
+ * Return the SAK/SEL_RES bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return SAK bytes
*/
public short getSak() {
return mSak;
}
/**
- * Send data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
+ * Send raw NFC-A commands to the tag and receive the response.
+ *
+ * <p>Applications must not append the EoD (CRC) to the payload,
+ * it will be automatically calculated.
+ * <p>Applications must only send commands that are complete bytes,
+ * for example a SENS_REQ is not possible (these are used to
+ * manage tag polling and initialization).
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param data bytes to send
* @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or this operation is canceled
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/NfcB.java b/core/java/android/nfc/tech/NfcB.java
index abeef32..22cb11d 100644
--- a/core/java/android/nfc/tech/NfcB.java
+++ b/core/java/android/nfc/tech/NfcB.java
@@ -23,18 +23,14 @@
import java.io.IOException;
/**
- * A low-level connection to a {@link Tag} using the NFC-B technology, also known as
- * ISO1443-3B.
+ * Provides access to NFC-B (ISO 14443-3B) properties and I/O operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
- * Use this class to send and receive data with {@link #transceive transceive()}.
+ * <p>Acquire a {@link NfcB} object using {@link #get}.
+ * <p>The primary NFC-B I/O operation is {@link #transceive}. Applications must
+ * implement their own protocol stack on top of {@link #transceive}.
*
- * <p>Applications must implement their own protocol stack on top of
- * {@link #transceive transceive()}.
- *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class NfcB extends BasicTagTechnology {
/** @hide */
@@ -46,10 +42,13 @@
private byte[] mProtInfo;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link NfcB} for the given tag.
+ * <p>Returns null if {@link NfcB} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag does not support NFC-B.
+ * <p>Does not cause any RF activity and does not block.
*
- * @param tag The tag to get the tech from
+ * @param tag an NFC-B compatible tag
+ * @return NFC-B object
*/
public static NfcB get(Tag tag) {
if (!tag.hasTech(TagTechnology.NFC_B)) return null;
@@ -69,31 +68,45 @@
}
/**
- * Returns the Application Data bytes from the ATQB/SENSB_RES
- * bytes discovered at tag discovery.
+ * Return the Application Data bytes from ATQB/SENSB_RES at tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return Application Data bytes from ATQB/SENSB_RES bytes
*/
public byte[] getApplicationData() {
return mAppData;
}
/**
- * Returns the Protocol Info bytes from the ATQB/SENSB_RES
- * bytes discovered at tag discovery.
+ * Return the Protocol Info bytes from ATQB/SENSB_RES at tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return Protocol Info bytes from ATQB/SENSB_RES bytes
*/
public byte[] getProtocolInfo() {
return mProtInfo;
}
/**
- * Send data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
+ * Send raw NFC-B commands to the tag and receive the response.
+ *
+ * <p>Applications must not append the EoD (CRC) to the payload,
+ * it will be automatically calculated.
+ * <p>Applications must not send commands that manage the polling
+ * loop and initialization (SENSB_REQ, SLOT_MARKER etc).
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param data bytes to send
* @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or this operation is canceled
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/NfcF.java b/core/java/android/nfc/tech/NfcF.java
index f617739..e0ebbe8 100644
--- a/core/java/android/nfc/tech/NfcF.java
+++ b/core/java/android/nfc/tech/NfcF.java
@@ -23,18 +23,14 @@
import java.io.IOException;
/**
- * A low-level connection to a {@link Tag} using the NFC-F technology, also known as
- * JIS6319-4.
+ * Provides access to NFC-F (JIS 6319-4) properties and I/O operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
- * Use this class to send and receive data with {@link #transceive transceive()}.
+ * <p>Acquire a {@link NfcF} object using {@link #get}.
+ * <p>The primary NFC-F I/O operation is {@link #transceive}. Applications must
+ * implement their own protocol stack on top of {@link #transceive}.
*
- * <p>Applications must implement their own protocol stack on top of
- * {@link #transceive transceive()}.
- *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class NfcF extends BasicTagTechnology {
/** @hide */
@@ -46,10 +42,13 @@
private byte[] mManufacturer = null;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link NfcF} for the given tag.
+ * <p>Returns null if {@link NfcF} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag does not support NFC-F.
+ * <p>Does not cause any RF activity and does not block.
*
- * @param tag The tag to get the tech from
+ * @param tag an NFC-F compatible tag
+ * @return NFC-F object
*/
public static NfcF get(Tag tag) {
if (!tag.hasTech(TagTechnology.NFC_F)) return null;
@@ -70,24 +69,44 @@
}
}
+ /**
+ * Return the System Code bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return System Code bytes
+ */
public byte[] getSystemCode() {
return mSystemCode;
}
+ /**
+ * Return the Manufacturer bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return Manufacturer bytes
+ */
public byte[] getManufacturer() {
return mManufacturer;
}
/**
- * Send data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
+ * Send raw NFC-F commands to the tag and receive the response.
+ *
+ * <p>Applications must not append the SoD (length) or EoD (CRC) to the payload,
+ * it will be automatically calculated.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param data bytes to send
* @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or this operation is canceled
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/NfcV.java b/core/java/android/nfc/tech/NfcV.java
index 8e1f066..fe721c8 100644
--- a/core/java/android/nfc/tech/NfcV.java
+++ b/core/java/android/nfc/tech/NfcV.java
@@ -23,18 +23,14 @@
import java.io.IOException;
/**
- * A low-level connection to a {@link Tag} using NFC vicinity technology, also known as
- * ISO15693.
+ * Provides access to NFC-V (ISO 15693) properties and I/O operations on a {@link Tag}.
*
- * <p>You can acquire this kind of connection with {@link #get}.
- * Use this class to send and receive data with {@link #transceive transceive()}.
+ * <p>Acquire a {@link NfcV} object using {@link #get}.
+ * <p>The primary NFC-V I/O operation is {@link #transceive}. Applications must
+ * implement their own protocol stack on top of {@link #transceive}.
*
- * <p>Applications must implement their own protocol stack on top of
- * {@link #transceive transceive()}.
- *
- * <p class="note"><strong>Note:</strong>
- * Use of this class requires the {@link android.Manifest.permission#NFC}
- * permission.
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
*/
public final class NfcV extends BasicTagTechnology {
/** @hide */
@@ -47,10 +43,13 @@
private byte mDsfId;
/**
- * Returns an instance of this tech for the given tag. If the tag doesn't support
- * this tech type null is returned.
+ * Get an instance of {@link NfcV} for the given tag.
+ * <p>Returns null if {@link NfcV} was not enumerated in {@link Tag#getTechList}.
+ * This indicates the tag does not support NFC-V.
+ * <p>Does not cause any RF activity and does not block.
*
- * @param tag The tag to get the tech from
+ * @param tag an NFC-V compatible tag
+ * @return NFC-V object
*/
public static NfcV get(Tag tag) {
if (!tag.hasTech(TagTechnology.NFC_V)) return null;
@@ -69,24 +68,45 @@
mDsfId = extras.getByte(EXTRA_DSFID);
}
+ /**
+ * Return the Response Flag bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return Response Flag bytes
+ */
public byte getResponseFlags() {
return mRespFlags;
}
+ /**
+ * Return the DSF ID bytes from tag discovery.
+ *
+ * <p>Does not cause any RF activity and does not block.
+ *
+ * @return DSF ID bytes
+ */
public byte getDsfId() {
return mDsfId;
}
/**
- * Send data to a tag and receive the response.
- * <p>
- * This method will block until the response is received. It can be canceled
- * with {@link #close}.
- * <p>Requires {@link android.Manifest.permission#NFC} permission.
+ * Send raw NFC-V commands to the tag and receive the response.
+ *
+ * <p>Applications must not append the CRC to the payload,
+ * it will be automatically calculated. The application does
+ * provide FLAGS, CMD and PARAMETER bytes.
+ *
+ * <p>This is an I/O operation and will block until complete. It must
+ * not be called from the main application thread. A blocked call will be canceled with
+ * {@link IOException} if {@link #close} is called from another thread.
+ *
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @param data bytes to send
* @return bytes received in response
- * @throws IOException if the target is lost or connection closed
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or this operation is canceled
*/
public byte[] transceive(byte[] data) throws IOException {
return transceive(data, true);
diff --git a/core/java/android/nfc/tech/TagTechnology.java b/core/java/android/nfc/tech/TagTechnology.java
index 50df865..be5cbd2 100644
--- a/core/java/android/nfc/tech/TagTechnology.java
+++ b/core/java/android/nfc/tech/TagTechnology.java
@@ -21,6 +21,64 @@
import java.io.Closeable;
import java.io.IOException;
+/**
+ * {@link TagTechnology} is an interface to a technology in a {@link Tag}.
+ * <p>
+ * Obtain a {@link TagTechnology} implementation by calling the static method <code>get()</code>
+ * on the implementation class.
+ * <p>
+ * NFC tags are based on a number of independently developed technologies and offer a
+ * wide range of capabilities. The
+ * {@link TagTechnology} implementations provide access to these different
+ * technologies and capabilities. Some sub-classes map to technology
+ * specification (for example {@link NfcA}, {@link IsoDep}, others map to
+ * pseudo-technologies or capabilities (for example {@link Ndef}, {@link NdefFormatable}).
+ * <p>
+ * It is mandatory for all Android NFC devices to provide the following
+ * {@link TagTechnology} implementations.
+ * <ul>
+ * <li>{@link NfcA} (also known as ISO 14443-3A)
+ * <li>{@link NfcB} (also known as ISO 14443-3B)
+ * <li>{@link NfcF} (also known as JIS 6319-4)
+ * <li>{@link NfcV} (also known as ISO 15693)
+ * <li>{@link IsoDep}
+ * <li>{@link Ndef} on NFC Forum Type 1, Type 2, Type 3 or Type 4 compliant tags
+ * </ul>
+ * It is optional for Android NFC devices to provide the following
+ * {@link TagTechnology} implementations. If it is not provided, the
+ * Android device will never enumerate that class via {@link Tag#getTechList}.
+ * <ul>
+ * <li>{@link MifareClassic}
+ * <li>{@link MifareUltralight}
+ * <li>{@link NdefFormatable} must only be enumerated on tags for which this Android device
+ * is capable of formatting. Proprietary knowledge is often required to format a tag
+ * to make it NDEF compatible.
+ * </ul>
+ * <p>
+ * {@link TagTechnology} implementations provide methods that fall into two classes:
+ * <em>cached getters</em> and <em>I/O operations</em>.
+ * <h4>Cached getters</h4>
+ * These methods (usually prefixed by <code>get</code> or <code>is</code>) return
+ * properties of the tag, as determined at discovery time. These methods will never
+ * block or cause RF activity, and do not require {@link #connect} to have been called.
+ * They also never update, for example if a property is changed by an I/O operation with a tag
+ * then the cached getter will still return the result from tag discovery time.
+ * <h4>I/O operations</h4>
+ * I/O operations may require RF activity, and may block. They have the following semantics.
+ * <ul>
+ * <li>{@link #connect} must be called before using any other I/O operation.
+ * <li>{@link #close} must be called after completing I/O operations with a
+ * {@link TagTechnology}, and it will cancel all other blocked I/O operations on other threads
+ * (including {@link #connect} with {@link IOException}.
+ * <li>Only one {@link TagTechnology} can be connected at a time. Other calls to
+ * {@link #connect} will return {@link IOException}.
+ * <li>I/O operations may block, and should never be called on the main application
+ * thread.
+ * </ul>
+ *
+ * <p class="note"><strong>Note:</strong> Methods that perform I/O operations
+ * require the {@link android.Manifest.permission#NFC} permission.
+ */
public interface TagTechnology extends Closeable {
/**
* This technology is an instance of {@link NfcA}.
@@ -90,22 +148,24 @@
public static final int MIFARE_ULTRALIGHT = 9;
/**
- * Get the {@link Tag} object this technology came from.
+ * Get the {@link Tag} object backing this {@link TagTechnology} object.
+ * @return the {@link Tag} backing this {@link TagTechnology} object.
*/
public Tag getTag();
/**
- * Opens a connection to the {@link Tag} enabling interactive commands. The command set
- * varies by the technology type.
+ * Enable I/O operations to the tag from this {@link TagTechnology} object.
+ * <p>May cause RF activity and may block. Must not be called
+ * from the main application thread. A blocked call will be canceled with
+ * {@link IOException} by calling {@link #close} from another thread.
+ * <p>Only one {@link TagTechnology} object can be connected to a {@link Tag} at a time.
+ * <p>Applications must call {@link #close} when I/O operations are complete.
*
- * <p>This method blocks until the connection has been established.
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
- * <p>A call to {@link #close} from another thread will cancel a blocked call and cause an
- * IOException to be thrown on the thread that is blocked.
- *
- * @see #reconnect()
* @see #close()
- * @throws IOException if the target is lost, or connect canceled
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or connect is canceled
*/
public void connect() throws IOException;
@@ -113,40 +173,39 @@
* Re-connect to the {@link Tag} associated with this connection. Reconnecting to a tag can be
* used to reset the state of the tag itself.
*
- * <p>This method blocks until the connection is re-established.
+ * <p>May cause RF activity and may block. Must not be called
+ * from the main application thread. A blocked call will be canceled with
+ * {@link IOException} by calling {@link #close} from another thread.
*
- * <p>A call to {@link #close} from another thread will cancel a blocked call and cause an
- * IOException to be thrown on the thread that is blocked.
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @see #connect()
* @see #close()
- * @throws IOException
+ * @throws TagLostException if the tag leaves the field
+ * @throws IOException if there is an I/O failure, or connect is canceled
* @hide
*/
public void reconnect() throws IOException;
/**
- * Closes the connection to the {@link Tag}. This call is non-blocking and causes all blocking
- * operations such as {@link #connect} to be canceled and immediately throw
- * {@link java.io.IOException} on the thread that is blocked.
+ * Disable I/O operations to the tag from this {@link TagTechnology} object, and release resources.
+ * <p>Also causes all blocked I/O operations on other thread to be canceled and
+ * return with {@link IOException}.
*
- * <p>
- * Once this method is called, this object cannot be re-used and should be discarded. Further
- * calls to {@link #connect} will fail.
+ * <p class="note">Requires the {@link android.Manifest.permission#NFC} permission.
*
* @see #connect()
- * @see #reconnect()
*/
public void close() throws IOException;
/**
- * Helper to indicate if {@link #connect} has succeeded.
- * <p>
- * Does not cause RF activity, and does not block.
- * @return true if {@link #connect} has completed successfully and the {@link Tag} is believed
- * to be within range. Applications must still handle {@link java.io.IOException}
- * while using methods that require a connection in case the connection is lost after this
- * method returns.
+ * Helper to indicate if I/O operations should be possible.
+ *
+ * <p>Returns true if {@link #connect} has completed, and {@link #close} has not been
+ * called, and the {@link Tag} is not known to be out of range.
+ * <p>Does not cause RF activity, and does not block.
+ *
+ * @return true if I/O operations should be possible
*/
public boolean isConnected();
}
diff --git a/docs/html/sdk/android-3.0-highlights.jd b/docs/html/sdk/android-3.0-highlights.jd
index 0378c35..591f088 100644
--- a/docs/html/sdk/android-3.0-highlights.jd
+++ b/docs/html/sdk/android-3.0-highlights.jd
@@ -112,7 +112,7 @@
<h3>New connectivity options</h3>
-<p>Android 3.0 includes new connectivity features that add versatility and convenience for users. Built-in support for Media/Photo Transfer Protocol lets users instantly sync media files with a USB-connected camera or desktop computer, without needing to mount a USB mass-storage device. Users can also connect full keyboards over either USB or Bluetooth, for a familiar text-input environment. For improved wi-fi connectivity, a new combo scan reduces scan times across bands and filters. New support for Bluetooth tethering means that more types of devices can share the network connection of an Android-powered device.</p>
+<p>Android 3.0 includes new connectivity features that add versatility and convenience for users. Built-in support for Media/Picture Transfer Protocol lets users instantly sync media files with a USB-connected camera or desktop computer, without needing to mount a USB mass-storage device. Users can also connect full keyboards over either USB or Bluetooth, for a familiar text-input environment. For improved wi-fi connectivity, a new combo scan reduces scan times across bands and filters. New support for Bluetooth tethering means that more types of devices can share the network connection of an Android-powered device.</p>
<h3>Updated set of standard apps</h3>
diff --git a/docs/html/sdk/images/3.0/browser.png b/docs/html/sdk/images/3.0/browser.png
index 5d3ba31..0f16b27 100644
--- a/docs/html/sdk/images/3.0/browser.png
+++ b/docs/html/sdk/images/3.0/browser.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/browser_full.png b/docs/html/sdk/images/3.0/browser_full.png
index 495a23d..08a329d6 100644
--- a/docs/html/sdk/images/3.0/browser_full.png
+++ b/docs/html/sdk/images/3.0/browser_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/camera.png b/docs/html/sdk/images/3.0/camera.png
index a549182..7dabdfc 100644
--- a/docs/html/sdk/images/3.0/camera.png
+++ b/docs/html/sdk/images/3.0/camera.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/camera_full.png b/docs/html/sdk/images/3.0/camera_full.png
index a549182..3ee95c9 100644
--- a/docs/html/sdk/images/3.0/camera_full.png
+++ b/docs/html/sdk/images/3.0/camera_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/contacts.png b/docs/html/sdk/images/3.0/contacts.png
index 0dcd164..9304701 100644
--- a/docs/html/sdk/images/3.0/contacts.png
+++ b/docs/html/sdk/images/3.0/contacts.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/contacts_full.png b/docs/html/sdk/images/3.0/contacts_full.png
index 829ad11..b5eaf5b 100644
--- a/docs/html/sdk/images/3.0/contacts_full.png
+++ b/docs/html/sdk/images/3.0/contacts_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/copy.png b/docs/html/sdk/images/3.0/copy.png
index 363aa8e..a15c1cd 100644
--- a/docs/html/sdk/images/3.0/copy.png
+++ b/docs/html/sdk/images/3.0/copy.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/copy_full.png b/docs/html/sdk/images/3.0/copy_full.png
index a8db8a2..124cf52 100644
--- a/docs/html/sdk/images/3.0/copy_full.png
+++ b/docs/html/sdk/images/3.0/copy_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/home_hero1.png b/docs/html/sdk/images/3.0/home_hero1.png
index c81e7ef..c00391f 100644
--- a/docs/html/sdk/images/3.0/home_hero1.png
+++ b/docs/html/sdk/images/3.0/home_hero1.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/home_hero1_full.png b/docs/html/sdk/images/3.0/home_hero1_full.png
index e280b81..1910ed2 100644
--- a/docs/html/sdk/images/3.0/home_hero1_full.png
+++ b/docs/html/sdk/images/3.0/home_hero1_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/homescreen_cust_port.png b/docs/html/sdk/images/3.0/homescreen_cust_port.png
index ef7f5ab..b003a30 100644
--- a/docs/html/sdk/images/3.0/homescreen_cust_port.png
+++ b/docs/html/sdk/images/3.0/homescreen_cust_port.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/homescreen_cust_port_full.png b/docs/html/sdk/images/3.0/homescreen_cust_port_full.png
index 22433a3e..9c64edd 100644
--- a/docs/html/sdk/images/3.0/homescreen_cust_port_full.png
+++ b/docs/html/sdk/images/3.0/homescreen_cust_port_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/mail_drag.png b/docs/html/sdk/images/3.0/mail_drag.png
index 6084caa..1f09a7a 100644
--- a/docs/html/sdk/images/3.0/mail_drag.png
+++ b/docs/html/sdk/images/3.0/mail_drag.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/mail_drag_full.png b/docs/html/sdk/images/3.0/mail_drag_full.png
index f99c612..be4472f 100644
--- a/docs/html/sdk/images/3.0/mail_drag_full.png
+++ b/docs/html/sdk/images/3.0/mail_drag_full.png
Binary files differ
diff --git a/docs/html/sdk/images/3.0/tasks.png b/docs/html/sdk/images/3.0/tasks.png
index 9e82dcb..a4ba1ba 100644
--- a/docs/html/sdk/images/3.0/tasks.png
+++ b/docs/html/sdk/images/3.0/tasks.png
Binary files differ
diff --git a/graphics/java/android/renderscript/Allocation.java b/graphics/java/android/renderscript/Allocation.java
index 3dcfe88..4b8c58e 100644
--- a/graphics/java/android/renderscript/Allocation.java
+++ b/graphics/java/android/renderscript/Allocation.java
@@ -26,19 +26,41 @@
import android.util.TypedValue;
/**
- * Memory allocation class for renderscript. An allocation combines a Type with
- * memory to provide storage for user data and objects.
+ * <p>
+ * Memory allocation class for renderscript. An allocation combines a
+ * {@link android.renderscript.Type} with the memory to provide storage for user data and objects.
+ * This implies that all memory in Renderscript is typed.
+ * </p>
*
- * Allocations may exist in one or more memory spaces. Currently those are
- * Script: accessable by RS scripts.
- * Graphics Texture: accessable as a graphics texture.
- * Graphics Vertex: accessable as graphical vertex data.
- * Graphics Constants: Accessable as constants in user shaders
+ * <p>Allocations are the primary way data moves into and out of scripts. Memory is user
+ * synchronized and it's possible for allocations to exist in multiple memory spaces
+ * concurrently. Currently those spaces are:</p>
+ * <ul>
+ * <li>Script: accessable by RS scripts.</li>
+ * <li>Graphics Texture: accessable as a graphics texture.</li>
+ * <li>Graphics Vertex: accessable as graphical vertex data.</li>
+ * <li>Graphics Constants: Accessable as constants in user shaders</li>
+ * </ul>
+ * </p>
+ * <p>
+ * For example, when creating a allocation for a texture, the user can
+ * specify its memory spaces as both script and textures. This means that it can both
+ * be used as script binding and as a GPU texture for rendering. To maintain
+ * synchronization if a script modifies an allocation used by other targets it must
+ * call a synchronizing function to push the updates to the memory, otherwise the results
+ * are undefined.
+ * </p>
+ * <p>By default, Android system side updates are always applied to the script accessable
+ * memory. If this is not present, they are then applied to the various HW
+ * memory types. A {@link android.renderscript.Allocation#syncAll syncAll()}
+ * call is necessary after the script data is updated to
+ * keep the other memory spaces in sync.</p>
*
- * By default java side updates are always applied to the script accessable
- * memory. If this is not present they are then applied to the various HW
- * memory types. A syncAll call is necessary after the script data is update to
- * keep the other memory spaces in sync.
+ * <p>Allocation data is uploaded in one of two primary ways. For simple
+ * arrays there are copyFrom() functions that take an array from the control code and
+ * copy it to the slave memory store. Both type checked and unchecked copies are provided.
+ * The unchecked variants exist to allow apps to copy over arrays of structures from a
+ * control language that does not support structures.</p>
*
**/
public class Allocation extends BaseObj {
diff --git a/graphics/java/android/renderscript/Byte2.java b/graphics/java/android/renderscript/Byte2.java
index 6d2994d..7ec6cb0 100644
--- a/graphics/java/android/renderscript/Byte2.java
+++ b/graphics/java/android/renderscript/Byte2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs byte2 type back to java applications.
+ * Class for exposing the native Renderscript byte2 type back to the Android system.
*
**/
public class Byte2 {
diff --git a/graphics/java/android/renderscript/Byte3.java b/graphics/java/android/renderscript/Byte3.java
index dd73914..7bcd4b4 100644
--- a/graphics/java/android/renderscript/Byte3.java
+++ b/graphics/java/android/renderscript/Byte3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs byte3 type back to java applications.
+ * Class for exposing the native Renderscript byte3 type back to the Android system.
*
**/
public class Byte3 {
diff --git a/graphics/java/android/renderscript/Byte4.java b/graphics/java/android/renderscript/Byte4.java
index ebea589..c6e7f63 100644
--- a/graphics/java/android/renderscript/Byte4.java
+++ b/graphics/java/android/renderscript/Byte4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs byte4 type back to java applications.
+ * Class for exposing the native Renderscript byte4 type back to the Android system.
*
**/
public class Byte4 {
diff --git a/graphics/java/android/renderscript/Element.java b/graphics/java/android/renderscript/Element.java
index 10dc35b..4fc419c 100644
--- a/graphics/java/android/renderscript/Element.java
+++ b/graphics/java/android/renderscript/Element.java
@@ -20,25 +20,26 @@
import android.util.Log;
/**
- * Element is the basic data type of RenderScript. An element can be of 2
- * forms. Basic elements contain a single component of data. This can be of
- * any of the legal RS types. Examples of basic element types.
- * Single float value
- * 4 element float vector
- * single RGB-565 color
- * single unsigned int 16
- *
- * Complex elements will contain a list of sub-elements and names. This in
- * effect represents a structure of data. The fields can be accessed by name
- * from a script or shader. The memory layout is defined and ordered. Data
- * alignment is determinied by the most basic primitive type. i.e. a float4
+ * <p>The most basic data type. An element represents one cell of a memory allocation.
+ * Element is the basic data type of Renderscript. An element can be of two forms: Basic elements or Complex forms.
+ * Examples of basic elements are:</p>
+ * <ul>
+ * <li>Single float value</li>
+ * <li>4 element float vector</li>
+ * <li>single RGB-565 color</li>
+ * <li>single unsigned int 16</li>
+ * </ul>
+ * <p>Complex elements contain a list of sub-elements and names that
+ * represents a structure of data. The fields can be accessed by name
+ * from a script or shader. The memory layout is defined and ordered. Data
+ * alignment is determinied by the most basic primitive type. i.e. a float4
* vector will be alligned to sizeof(float) and not sizeof(float4). The
* ordering of elements in memory will be the order in which they were added
- * with each component aligned as necessary. No re-ordering will be done.
+ * with each component aligned as necessary. No re-ordering will be done.</p>
*
- * The primary source of elements will be from scripts. A script that exports a
- * bind point for a data structure will generate a RS element to represent the
- * data exported by the script.
+ * <p>The primary source of elements are from scripts. A script that exports a
+ * bind point for a data structure generates a Renderscript element to represent the
+ * data exported by the script. The other common source of elements is from bitmap formats.</p>
**/
public class Element extends BaseObj {
int mSize;
diff --git a/graphics/java/android/renderscript/FieldPacker.java b/graphics/java/android/renderscript/FieldPacker.java
index 40628bc..bdda830 100644
--- a/graphics/java/android/renderscript/FieldPacker.java
+++ b/graphics/java/android/renderscript/FieldPacker.java
@@ -18,8 +18,8 @@
/**
- * Utility class for packing arguments and structures from java objects to rs
- * objects.
+ * Utility class for packing arguments and structures from Android system objects to
+ * Renderscript objects.
*
**/
public class FieldPacker {
diff --git a/graphics/java/android/renderscript/FileA3D.java b/graphics/java/android/renderscript/FileA3D.java
index 79ee997..b5419a7 100644
--- a/graphics/java/android/renderscript/FileA3D.java
+++ b/graphics/java/android/renderscript/FileA3D.java
@@ -28,9 +28,9 @@
import android.util.TypedValue;
/**
- * FileA3D allows users to load renderscript objects from files
+ * FileA3D allows users to load Renderscript objects from files
* or resources stored on disk. It could be used to load items
- * such as 3d geometry data converted a renderscript format from
+ * such as 3D geometry data converted to a Renderscript format from
* content creation tools. Currently only meshes are supported
* in FileA3D.
*
@@ -66,9 +66,9 @@
}
/**
- * IndexEntry contains information about one of the renderscript
+ * IndexEntry contains information about one of the Renderscript
* objects inside the file's index. It could be used to query the
- * object's type and name and load the object itself if
+ * object's type and also name and load the object itself if
* necessary.
*/
public static class IndexEntry {
diff --git a/graphics/java/android/renderscript/Float2.java b/graphics/java/android/renderscript/Float2.java
index 0a099f1..1d4ce36 100644
--- a/graphics/java/android/renderscript/Float2.java
+++ b/graphics/java/android/renderscript/Float2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs float2 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
*
**/
public class Float2 {
diff --git a/graphics/java/android/renderscript/Float3.java b/graphics/java/android/renderscript/Float3.java
index 2ffa326..ffd1135 100644
--- a/graphics/java/android/renderscript/Float3.java
+++ b/graphics/java/android/renderscript/Float3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs float3 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
*
**/
public class Float3 {
diff --git a/graphics/java/android/renderscript/Float4.java b/graphics/java/android/renderscript/Float4.java
index 19d91dc..c7cc3ae 100644
--- a/graphics/java/android/renderscript/Float4.java
+++ b/graphics/java/android/renderscript/Float4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs float4 type back to java applications.
+ * Class for exposing the native Renderscript float2 type back to the Android system.
*
**/
public class Float4 {
diff --git a/graphics/java/android/renderscript/Font.java b/graphics/java/android/renderscript/Font.java
index 252ffc1..fa27590 100644
--- a/graphics/java/android/renderscript/Font.java
+++ b/graphics/java/android/renderscript/Font.java
@@ -30,7 +30,20 @@
import android.util.TypedValue;
/**
- *
+ * <p>This class gives users a simple way to draw hardware accelerated text.
+ * Internally, the glyphs are rendered using the Freetype library and an internal cache of
+ * rendered glyph bitmaps is maintained. Each font object represents a combination of a typeface,
+ * and point size. You can create multiple font objects to represent styles such as bold or italic text,
+ * faces, and different font sizes. During creation, the Android system quieries device's screen DPI to
+ * ensure proper sizing across multiple device configurations.</p>
+ * <p>Fonts are rendered using screen-space positions and no state setup beyond binding a
+ * font to the Renderscript is required. A note of caution on performance, though the state changes
+ * are transparent to the user, they do happen internally, and it is more efficient to
+ * render large batches of text in sequence. It is also more efficient to render multiple
+ * characters at once instead of one by one to improve draw call batching.</p>
+ * <p>Font color and transparency are not part of the font object and you can freely modify
+ * them in the script to suit the user's rendering needs. Font colors work as a state machine.
+ * Every new call to draw text uses the last color set in the script.</p>
**/
public class Font extends BaseObj {
diff --git a/graphics/java/android/renderscript/Int2.java b/graphics/java/android/renderscript/Int2.java
index 8eceb71..7aaa4e8 100644
--- a/graphics/java/android/renderscript/Int2.java
+++ b/graphics/java/android/renderscript/Int2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs int2 type back to java applications.
+ * Class for exposing the native Renderscript int2 type back to the Android system.
*
**/
public class Int2 {
diff --git a/graphics/java/android/renderscript/Int3.java b/graphics/java/android/renderscript/Int3.java
index bbd296e..e5c1cdf 100644
--- a/graphics/java/android/renderscript/Int3.java
+++ b/graphics/java/android/renderscript/Int3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs int3 type back to java applications.
+ * Class for exposing the native Renderscript int3 type back to the Android system.
*
**/
public class Int3 {
diff --git a/graphics/java/android/renderscript/Int4.java b/graphics/java/android/renderscript/Int4.java
index c3ae112c..5289a89 100644
--- a/graphics/java/android/renderscript/Int4.java
+++ b/graphics/java/android/renderscript/Int4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs int4 type back to java applications.
+ * Class for exposing the native Renderscript int4 type back to the Android system.
*
**/
public class Int4 {
diff --git a/graphics/java/android/renderscript/Long2.java b/graphics/java/android/renderscript/Long2.java
index 834d13c..8590b96 100644
--- a/graphics/java/android/renderscript/Long2.java
+++ b/graphics/java/android/renderscript/Long2.java
@@ -21,7 +21,7 @@
/**
- *
+ * Class for exposing the native Renderscript long2 type back to the Android system.
**/
public class Long2 {
public Long2() {
diff --git a/graphics/java/android/renderscript/Long3.java b/graphics/java/android/renderscript/Long3.java
index c6d7289..6ae837a 100644
--- a/graphics/java/android/renderscript/Long3.java
+++ b/graphics/java/android/renderscript/Long3.java
@@ -21,7 +21,7 @@
/**
- *
+ * Class for exposing the native Renderscript long3 type back to the Android system.
**/
public class Long3 {
public Long3() {
diff --git a/graphics/java/android/renderscript/Long4.java b/graphics/java/android/renderscript/Long4.java
index 032c1d3..04c12f2 100644
--- a/graphics/java/android/renderscript/Long4.java
+++ b/graphics/java/android/renderscript/Long4.java
@@ -21,7 +21,7 @@
/**
- *
+ * Class for exposing the native Renderscript long4 type back to the Android system.
**/
public class Long4 {
public Long4() {
diff --git a/graphics/java/android/renderscript/Matrix2f.java b/graphics/java/android/renderscript/Matrix2f.java
index c9a0ea8..78ff97b 100644
--- a/graphics/java/android/renderscript/Matrix2f.java
+++ b/graphics/java/android/renderscript/Matrix2f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs_matrix2x2 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix2x2 type back to the Android system.
*
**/
public class Matrix2f {
diff --git a/graphics/java/android/renderscript/Matrix3f.java b/graphics/java/android/renderscript/Matrix3f.java
index 2ec8c62..253506df 100644
--- a/graphics/java/android/renderscript/Matrix3f.java
+++ b/graphics/java/android/renderscript/Matrix3f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs_matrix3x3 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix3x3 type back to the Android system.
*
**/
public class Matrix3f {
diff --git a/graphics/java/android/renderscript/Matrix4f.java b/graphics/java/android/renderscript/Matrix4f.java
index 2afd72e..adc1806 100644
--- a/graphics/java/android/renderscript/Matrix4f.java
+++ b/graphics/java/android/renderscript/Matrix4f.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs_matrix4x4 type back to java applications.
+ * Class for exposing the native Renderscript rs_matrix4x4 type back to the Android system.
*
**/
public class Matrix4f {
diff --git a/graphics/java/android/renderscript/Mesh.java b/graphics/java/android/renderscript/Mesh.java
index 7269cea..bb910cc 100644
--- a/graphics/java/android/renderscript/Mesh.java
+++ b/graphics/java/android/renderscript/Mesh.java
@@ -22,22 +22,21 @@
import android.util.Log;
/**
- * Mesh class is a container for geometric data displayed in
- * renderscript.
- *
- * Internally, mesh is a collection of allocations that
+ * <p>This class is a container for geometric data displayed with
+ * Renderscript. Internally, a mesh is a collection of allocations that
* represent vertex data (positions, normals, texture
- * coordinates) and index data such as triangles and lines.
- *
- * Vertex data could either be interlieved within one
- * allocation, provided separately as multiple allocation
- * objects or done as a combination of the above. When a
+ * coordinates) and index data such as triangles and lines. </p>
+ * <p>
+ * Vertex data could either be interleaved within one
+ * allocation that is provided separately, as multiple allocation
+ * objects, or done as a combination of both. When a
* vertex channel name matches an input in the vertex program,
- * renderscript will automatically connect the two together.
- *
- * Parts of the mesh could be rendered with either explicit
+ * Renderscript automatically connects the two together.
+ * </p>
+ * <p>
+ * Parts of the mesh can be rendered with either explicit
* index sets or primitive types.
- *
+ * </p>
**/
public class Mesh extends BaseObj {
@@ -170,9 +169,9 @@
}
/**
- * Mesh builder object. It starts empty and requires the user to
+ * Mesh builder object. It starts empty and requires you to
* add the types necessary to create vertex and index
- * allocations
+ * allocations.
*
*/
public static class Builder {
diff --git a/graphics/java/android/renderscript/ProgramFragment.java b/graphics/java/android/renderscript/ProgramFragment.java
index 333880d..a48c2e3 100644
--- a/graphics/java/android/renderscript/ProgramFragment.java
+++ b/graphics/java/android/renderscript/ProgramFragment.java
@@ -22,9 +22,19 @@
/**
- * ProgramFragment, also know as a fragment shader, describes a
- * stage in the graphics pipeline responsible for manipulating
- * pixel data in a user-defined way.
+ * <p>The Renderscript fragment program, also known as fragment shader is responsible
+ * for manipulating pixel data in a user defined way. It's constructed from a GLSL
+ * shader string containing the program body, textures inputs, and a Type object
+ * that describes the constants used by the program. Similar to the vertex programs,
+ * when an allocation with constant input values is bound to the shader, its values
+ * are sent to the graphics program automatically.</p>
+ * <p> The values inside the allocation are not explicitly tracked. If they change between two draw
+ * calls using the same program object, the runtime needs to be notified of that
+ * change by calling rsgAllocationSyncAll so it could send the new values to hardware.
+ * Communication between the vertex and fragment programs is handled internally in the
+ * GLSL code. For example, if the fragment program is expecting a varying input called
+ * varTex0, the GLSL code inside the program vertex must provide it.
+ * </p>
*
**/
public class ProgramFragment extends Program {
diff --git a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
index 666a3e6..f99cd7b 100644
--- a/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
+++ b/graphics/java/android/renderscript/ProgramFragmentFixedFunction.java
@@ -22,13 +22,11 @@
/**
- * ProgramFragmentFixedFunction is a helper class that provides
+ * <p>ProgramFragmentFixedFunction is a helper class that provides
* a way to make a simple fragment shader without writing any
- * GLSL code.
- *
- * This class allows for display of constant color, interpolated
- * color from vertex shader, or combinations of the above
- * blended with results of up to two texture lookups.
+ * GLSL code. This class allows for display of constant color, interpolated
+ * color from the vertex shader, or combinations of the both
+ * blended with results of up to two texture lookups.</p
*
**/
public class ProgramFragmentFixedFunction extends ProgramFragment {
diff --git a/graphics/java/android/renderscript/ProgramRaster.java b/graphics/java/android/renderscript/ProgramRaster.java
index 71c527d..b89d36d 100644
--- a/graphics/java/android/renderscript/ProgramRaster.java
+++ b/graphics/java/android/renderscript/ProgramRaster.java
@@ -22,7 +22,8 @@
/**
- *
+ * Program raster is primarily used to specify whether point sprites are enabled and to control
+ * the culling mode. By default, back faces are culled.
**/
public class ProgramRaster extends BaseObj {
diff --git a/graphics/java/android/renderscript/ProgramStore.java b/graphics/java/android/renderscript/ProgramStore.java
index 9128f9b..c46e6b9 100644
--- a/graphics/java/android/renderscript/ProgramStore.java
+++ b/graphics/java/android/renderscript/ProgramStore.java
@@ -22,16 +22,17 @@
/**
- * ProgarmStore contains a set of parameters that control how
+ * <p>ProgramStore contains a set of parameters that control how
* the graphics hardware handles writes to the framebuffer.
- *
- * It could be used to:
- * - enable/diable depth testing
- * - specify wheather depth writes are performed
- * - setup various blending modes for use in effects like
- * transparency
- * - define write masks for color components written into the
- * framebuffer
+ * It could be used to:</p>
+ * <ul>
+ * <li>enable/disable depth testing</li>
+ * <li>specify wheather depth writes are performed</li>
+ * <li>setup various blending modes for use in effects like
+ * transparency</li>
+ * <li>define write masks for color components written into the
+ * framebuffer</li>
+ * </ul>
*
**/
public class ProgramStore extends BaseObj {
diff --git a/graphics/java/android/renderscript/ProgramVertex.java b/graphics/java/android/renderscript/ProgramVertex.java
index a965b81..55653f7 100644
--- a/graphics/java/android/renderscript/ProgramVertex.java
+++ b/graphics/java/android/renderscript/ProgramVertex.java
@@ -14,6 +14,27 @@
* limitations under the License.
*/
+ /**
+ * <p>The Renderscript vertex program, also known as a vertex shader, describes a stage in
+ * the graphics pipeline responsible for manipulating geometric data in a user-defined way.
+ * The object is constructed by providing the Renderscript system with the following data:</p>
+ * <ul>
+ * <li>Element describing its varying inputs or attributes</li>
+ * <li>GLSL shader string that defines the body of the program</li>
+ * <li>a Type that describes the layout of an Allocation containing constant or uniform inputs</li>
+ * </ul>
+ *
+ * <p>Once the program is created, you bind it to the graphics context, RenderScriptGL, and it will be used for
+ * all subsequent draw calls until you bind a new program. If the program has constant inputs,
+ * the user needs to bind an allocation containing those inputs. The allocation's type must match
+ * the one provided during creation. The Renderscript library then does all the necessary plumbing
+ * to send those constants to the graphics hardware. Varying inputs to the shader, such as position, normal,
+ * and texture coordinates are matched by name between the input Element and the Mesh object being drawn.
+ * The signatures don't have to be exact or in any strict order. As long as the input name in the shader
+ * matches a channel name and size available on the mesh, the runtime takes care of connecting the
+ * two. Unlike OpenGL, there is no need to link the vertex and fragment programs.</p>
+ *
+ **/
package android.renderscript;
diff --git a/graphics/java/android/renderscript/RSSurfaceView.java b/graphics/java/android/renderscript/RSSurfaceView.java
index be893bb..199952c 100644
--- a/graphics/java/android/renderscript/RSSurfaceView.java
+++ b/graphics/java/android/renderscript/RSSurfaceView.java
@@ -30,7 +30,7 @@
import android.view.SurfaceView;
/**
- *
+ * The Surface View for a graphics renderscript (RenderScriptGL) to draw on.
*/
public class RSSurfaceView extends SurfaceView implements SurfaceHolder.Callback {
private SurfaceHolder mSurfaceHolder;
diff --git a/graphics/java/android/renderscript/Sampler.java b/graphics/java/android/renderscript/Sampler.java
index c656d75..8ee4d72 100644
--- a/graphics/java/android/renderscript/Sampler.java
+++ b/graphics/java/android/renderscript/Sampler.java
@@ -29,8 +29,8 @@
import android.graphics.BitmapFactory;
/**
- * Sampler object which defines how data is extracted from textures. Samplers
- * are attached to Program objects (currently only fragment) when those objects
+ * Sampler object which defines how data is extracted from textures. Samplers
+ * are attached to Program objects (currently only ProgramFragment) when those objects
* need to access texture data.
**/
public class Sampler extends BaseObj {
diff --git a/graphics/java/android/renderscript/Short2.java b/graphics/java/android/renderscript/Short2.java
index 82d897e..7094edd 100644
--- a/graphics/java/android/renderscript/Short2.java
+++ b/graphics/java/android/renderscript/Short2.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs short2 type back to java applications.
+ * Class for exposing the native Renderscript Short2 type back to the Android system.
*
**/
public class Short2 {
diff --git a/graphics/java/android/renderscript/Short3.java b/graphics/java/android/renderscript/Short3.java
index 00da5741..f34500c 100644
--- a/graphics/java/android/renderscript/Short3.java
+++ b/graphics/java/android/renderscript/Short3.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs short3 type back to java applications.
+ * Class for exposing the native Renderscript short3 type back to the Android system.
*
**/
public class Short3 {
diff --git a/graphics/java/android/renderscript/Short4.java b/graphics/java/android/renderscript/Short4.java
index 450258d..5698fee 100644
--- a/graphics/java/android/renderscript/Short4.java
+++ b/graphics/java/android/renderscript/Short4.java
@@ -21,7 +21,7 @@
/**
- * Class for exposing the rs short4 type back to java applications.
+ * Class for exposing the native Renderscript short4 type back to the Android system.
*
**/
public class Short4 {
diff --git a/graphics/java/android/renderscript/Type.java b/graphics/java/android/renderscript/Type.java
index bec76d0..9979e2a 100644
--- a/graphics/java/android/renderscript/Type.java
+++ b/graphics/java/android/renderscript/Type.java
@@ -21,19 +21,19 @@
import android.util.Log;
/**
- * Type is an allocation template. It consists of an Element and one or more
- * dimensions. It describes only the layout of memory but does not allocate and
- * storage for the data thus described.
+ * <p>Type is an allocation template. It consists of an Element and one or more
+ * dimensions. It describes only the layout of memory but does not allocate any
+ * storage for the data that is described.</p>
*
- * A Type consists of several dimensions. Those are X, Y, Z, LOD (level of
+ * <p>A Type consists of several dimensions. Those are X, Y, Z, LOD (level of
* detail), Faces (faces of a cube map). The X,Y,Z dimensions can be assigned
* any positive integral value within the constraints of available memory. A
* single dimension allocation would have an X dimension of greater than zero
* while the Y and Z dimensions would be zero to indicate not present. In this
* regard an allocation of x=10, y=1 would be considered 2 dimensionsal while
- * x=10, y=0 would be considered 1 dimensional.
+ * x=10, y=0 would be considered 1 dimensional.</p>
*
- * The LOD and Faces dimensions are booleans to indicate present or not present.
+ * <p>The LOD and Faces dimensions are booleans to indicate present or not present.</p>
*
**/
public class Type extends BaseObj {
diff --git a/graphics/java/android/renderscript/package.html b/graphics/java/android/renderscript/package.html
new file mode 100644
index 0000000..36a24ff
--- /dev/null
+++ b/graphics/java/android/renderscript/package.html
@@ -0,0 +1,85 @@
+<HTML>
+<BODY>
+<p>The Renderscript rendering and computational APIs offer a low-level, high performance means of
+carrying out mathematical calculations and 3D graphics rendering. An example of Renderscript in
+applications include the 3D carousel view that is present in Android 3.0 applications such as the
+Books and YouTube applications. This API is intended for developers who are comfortable working with
+native code and want to maximize their performance critical applications.</p>
+
+<p>Renderscript adopts a control and slave architecture where the low-level native code is controlled by the
+higher level Android system that runs in the virtual machine (VM). The VM code handles resource
+allocation and lifecycle management of the Renderscript enabled application and calls the Renderscript
+code through high level entry points. The Android build tools generate these entry points through reflection on
+the native Renderscript code, which you write in C (C99 standard). The Renderscript code
+does the intensive computation and returns the result back to the Android VM.</p>
+
+<p>You can find the Renderscript native
+APIs in the <code><sdk_root>/platforms/android-3.0/renderscript</code> directory.
+The Android system APIs are broken into a few main groups:</p>
+
+<h4>Core</h4>
+<p>These classes are used internally by the system for memory allocation. They are used by the classes that
+are generated by the build tools:</p>
+<ul>
+ <li>Allocation</li>
+ <li>Element</li>
+ <li>Type</li>
+ <li>Script</li>
+</ul>
+
+
+<h4>Data Types</h4>
+<p>These data types are used by the classes that are generated
+by the build tools. They are the reflected counterparts of the native data types that
+are defined by the native Renderscript APIs and used by your Renderscript code. The
+classes include:</p>
+<ul>
+ <li>Byte2, Byte3, and Byte4</li>
+ <li>Float2, Float3, Float4</li>
+ <li>Int2, Int3, Int4</li>
+ <li>Long2, Long3, Long4</li>
+ <li>Matrix2f, Matrix3f, Matrix4f</li>
+ <li>Short2, Short3, Short4</li>
+</ul>
+
+<p>For example, if you declared the following struct in your .rs Renderscript file:</p>
+
+<pre>struct Hello { float3 position; rs_matrix4x4 transform; }</pre>
+
+<p>The build tools generate a class through reflection that looks like the following:</p>
+<pre>
+class Hello {
+ static public class Item {
+ Float4 position;
+ Matrix4f transform;
+ }
+Element createElement(RenderScript rs) {
+ Element.Builder eb = new Element.Builder(rs);
+ eb.add(Element.F32_3(rs), "position");
+ eb.add(Element.MATRIX_4X4(rs), "transform");
+ return eb.create();
+ }
+}
+</pre>
+
+<h4>Graphics</h4>
+<p>These classes are specific to graphics Renderscripts and support a typical rendering
+pipeline.</p>
+<ul>
+<li>Mesh</li>
+<li>ProgramFragment</li>
+<li>ProgramRaster</li>
+<li>ProgramStore</li>
+<li>ProgramVertex</li>
+<li>RSSurfaceView</li>
+<li>Sampler</li>
+</ul>
+
+</p>
+<p>
+For information on how to create an application that uses Renderscript, and also the
+see <a href="../../../guide/topics/graphics/renderscript.html">3D with
+Renderscript</a> dev guide.
+</p>
+</BODY>
+</HTML>
diff --git a/include/utils/RefBase.h b/include/utils/RefBase.h
index 9c64ac0..c24c0db 100644
--- a/include/utils/RefBase.h
+++ b/include/utils/RefBase.h
@@ -31,13 +31,10 @@
// ---------------------------------------------------------------------------
-#define COMPARE(_op_) \
+#define COMPARE_WEAK(_op_) \
inline bool operator _op_ (const sp<T>& o) const { \
return m_ptr _op_ o.m_ptr; \
} \
-inline bool operator _op_ (const wp<T>& o) const { \
- return m_ptr _op_ o.m_ptr; \
-} \
inline bool operator _op_ (const T* o) const { \
return m_ptr _op_ o; \
} \
@@ -46,12 +43,18 @@
return m_ptr _op_ o.m_ptr; \
} \
template<typename U> \
-inline bool operator _op_ (const wp<U>& o) const { \
+inline bool operator _op_ (const U* o) const { \
+ return m_ptr _op_ o; \
+}
+
+#define COMPARE(_op_) \
+COMPARE_WEAK(_op_) \
+inline bool operator _op_ (const wp<T>& o) const { \
return m_ptr _op_ o.m_ptr; \
} \
template<typename U> \
-inline bool operator _op_ (const U* o) const { \
- return m_ptr _op_ o; \
+inline bool operator _op_ (const wp<U>& o) const { \
+ return m_ptr _op_ o.m_ptr; \
}
// ---------------------------------------------------------------------------
@@ -274,13 +277,43 @@
inline T* unsafe_get() const { return m_ptr; }
// Operators
-
- COMPARE(==)
- COMPARE(!=)
- COMPARE(>)
- COMPARE(<)
- COMPARE(<=)
- COMPARE(>=)
+
+ COMPARE_WEAK(==)
+ COMPARE_WEAK(!=)
+ COMPARE_WEAK(>)
+ COMPARE_WEAK(<)
+ COMPARE_WEAK(<=)
+ COMPARE_WEAK(>=)
+
+ inline bool operator == (const wp<T>& o) const {
+ return (m_ptr == o.m_ptr) && (m_refs == o.m_refs);
+ }
+ template<typename U>
+ inline bool operator == (const wp<U>& o) const {
+ return m_ptr == o.m_ptr;
+ }
+
+ inline bool operator > (const wp<T>& o) const {
+ return (m_ptr == o.m_ptr) ? (m_refs > o.m_refs) : (m_ptr > o.m_ptr);
+ }
+ template<typename U>
+ inline bool operator > (const wp<U>& o) const {
+ return (m_ptr == o.m_ptr) ? (m_refs > o.m_refs) : (m_ptr > o.m_ptr);
+ }
+
+ inline bool operator < (const wp<T>& o) const {
+ return (m_ptr == o.m_ptr) ? (m_refs < o.m_refs) : (m_ptr < o.m_ptr);
+ }
+ template<typename U>
+ inline bool operator < (const wp<U>& o) const {
+ return (m_ptr == o.m_ptr) ? (m_refs < o.m_refs) : (m_ptr < o.m_ptr);
+ }
+ inline bool operator != (const wp<T>& o) const { return m_refs != o.m_refs; }
+ template<typename U> inline bool operator != (const wp<U>& o) const { return !operator == (o); }
+ inline bool operator <= (const wp<T>& o) const { return !operator > (o); }
+ template<typename U> inline bool operator <= (const wp<U>& o) const { return !operator > (o); }
+ inline bool operator >= (const wp<T>& o) const { return !operator < (o); }
+ template<typename U> inline bool operator >= (const wp<U>& o) const { return !operator < (o); }
private:
template<typename Y> friend class sp;
@@ -294,6 +327,7 @@
TextOutput& operator<<(TextOutput& to, const wp<T>& val);
#undef COMPARE
+#undef COMPARE_WEAK
// ---------------------------------------------------------------------------
// No user serviceable parts below here.
diff --git a/libs/rs/java/HelloWorld/Android.mk b/libs/rs/java/HelloWorld/Android.mk
new file mode 100644
index 0000000..72f0f03b
--- /dev/null
+++ b/libs/rs/java/HelloWorld/Android.mk
@@ -0,0 +1,30 @@
+#
+# Copyright (C) 2011 The Android Open Source Project
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+ifneq ($(TARGET_SIMULATOR),true)
+
+LOCAL_PATH := $(call my-dir)
+include $(CLEAR_VARS)
+
+LOCAL_MODULE_TAGS := optional
+
+LOCAL_SRC_FILES := $(call all-java-files-under, src) $(call all-renderscript-files-under, src)
+
+LOCAL_PACKAGE_NAME := HelloWorld
+
+include $(BUILD_PACKAGE)
+
+endif
diff --git a/libs/rs/java/HelloWorld/AndroidManifest.xml b/libs/rs/java/HelloWorld/AndroidManifest.xml
new file mode 100644
index 0000000..e7c9a95
--- /dev/null
+++ b/libs/rs/java/HelloWorld/AndroidManifest.xml
@@ -0,0 +1,31 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- Copyright (C) 2011 The Android Open Source Project
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+ package="com.android.rs.helloworld">
+ <uses-sdk android:minSdkVersion="11" />
+ <application android:label="HelloWorld"
+ android:icon="@drawable/test_pattern">
+ <activity android:name="HelloWorld"
+ android:label="HelloWorld"
+ android:theme="@android:style/Theme.Black.NoTitleBar">
+ <intent-filter>
+ <action android:name="android.intent.action.MAIN" />
+ <category android:name="android.intent.category.LAUNCHER" />
+ </intent-filter>
+ </activity>
+ </application>
+</manifest>
diff --git a/libs/rs/java/HelloWorld/res/drawable/test_pattern.png b/libs/rs/java/HelloWorld/res/drawable/test_pattern.png
new file mode 100644
index 0000000..e7d1455
--- /dev/null
+++ b/libs/rs/java/HelloWorld/res/drawable/test_pattern.png
Binary files differ
diff --git a/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorld.java b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorld.java
new file mode 100644
index 0000000..f63015e7
--- /dev/null
+++ b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorld.java
@@ -0,0 +1,54 @@
+/*
+ * Copyright (C) 2011 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.rs.helloworld;
+
+import android.app.Activity;
+import android.os.Bundle;
+
+// Renderscript activity
+public class HelloWorld extends Activity {
+
+ // Custom view to use with RenderScript
+ private HelloWorldView mView;
+
+ @Override
+ public void onCreate(Bundle icicle) {
+ super.onCreate(icicle);
+
+ // Create our view and set it as the content of our Activity
+ mView = new HelloWorldView(this);
+ setContentView(mView);
+ }
+
+ @Override
+ protected void onResume() {
+ // Ideally an app should implement onResume() and onPause()
+ // to take appropriate action when the activity loses focus
+ super.onResume();
+ mView.resume();
+ }
+
+ @Override
+ protected void onPause() {
+ // Ideally an app should implement onResume() and onPause()
+ // to take appropriate action when the activity loses focus
+ super.onPause();
+ mView.pause();
+ }
+
+}
+
diff --git a/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldRS.java b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldRS.java
new file mode 100644
index 0000000..c9c1316
--- /dev/null
+++ b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldRS.java
@@ -0,0 +1,52 @@
+/*
+ * Copyright (C) 2011 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.rs.helloworld;
+
+import android.content.res.Resources;
+import android.renderscript.*;
+
+// This is the renderer for the HelloWorldView
+public class HelloWorldRS {
+ private Resources mRes;
+ private RenderScriptGL mRS;
+
+ private ScriptC_helloworld mScript;
+
+ public HelloWorldRS() {
+ }
+
+ // This provides us with the renderscript context and resources that
+ // allow us to create the script that does rendering
+ public void init(RenderScriptGL rs, Resources res) {
+ mRS = rs;
+ mRes = res;
+ initRS();
+ }
+
+ public void onActionDown(int x, int y) {
+ mScript.set_gTouchX(x);
+ mScript.set_gTouchY(y);
+ }
+
+ private void initRS() {
+ mScript = new ScriptC_helloworld(mRS, mRes, R.raw.helloworld);
+ mRS.bindRootScript(mScript);
+ }
+}
+
+
+
diff --git a/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldView.java b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldView.java
new file mode 100644
index 0000000..8cddb2a
--- /dev/null
+++ b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/HelloWorldView.java
@@ -0,0 +1,76 @@
+/*
+ * Copyright (C) 2011 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.android.rs.helloworld;
+
+import android.renderscript.RSSurfaceView;
+import android.renderscript.RenderScriptGL;
+
+import android.content.Context;
+import android.view.MotionEvent;
+
+public class HelloWorldView extends RSSurfaceView {
+ // Renderscipt context
+ private RenderScriptGL mRS;
+ // Script that does the rendering
+ private HelloWorldRS mRender;
+
+ public HelloWorldView(Context context) {
+ super(context);
+ ensureRenderScript();
+ }
+
+ private void ensureRenderScript() {
+ if (mRS == null) {
+ // Initialize renderscript with desired surface characteristics.
+ // In this case, just use the defaults
+ RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig();
+ mRS = createRenderScriptGL(sc);
+ // Create an instance of the script that does the rendering
+ mRender = new HelloWorldRS();
+ mRender.init(mRS, getResources());
+ }
+ }
+
+ @Override
+ protected void onAttachedToWindow() {
+ super.onAttachedToWindow();
+ ensureRenderScript();
+ }
+
+ @Override
+ protected void onDetachedFromWindow() {
+ // Handle the system event and clean up
+ mRender = null;
+ if (mRS != null) {
+ mRS = null;
+ destroyRenderScriptGL();
+ }
+ }
+
+ @Override
+ public boolean onTouchEvent(MotionEvent ev) {
+ // Pass touch events from the system to the rendering script
+ if (ev.getAction() == MotionEvent.ACTION_DOWN) {
+ mRender.onActionDown((int)ev.getX(), (int)ev.getY());
+ return true;
+ }
+
+ return false;
+ }
+}
+
+
diff --git a/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/helloworld.rs b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/helloworld.rs
new file mode 100644
index 0000000..fa171f5
--- /dev/null
+++ b/libs/rs/java/HelloWorld/src/com/android/rs/helloworld/helloworld.rs
@@ -0,0 +1,47 @@
+// Copyright (C) 2011 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+#pragma version(1)
+
+// Tell which java package name the reflected files should belong to
+#pragma rs java_package_name(com.android.rs.helloworld)
+
+// Built-in header with graphics API's
+#include "rs_graphics.rsh"
+
+// gTouchX and gTouchY are variables that will be reflected for use
+// by the java API. We can use them to notify the script of touch events.
+int gTouchX;
+int gTouchY;
+
+// This is invoked automatically when the script is created
+void init() {
+ gTouchX = 50.0f;
+ gTouchY = 50.0f;
+}
+
+int root(int launchID) {
+
+ // Clear the background color
+ rsgClearColor(0.0f, 0.0f, 0.0f, 0.0f);
+ // Tell the runtime what the font color should be
+ rsgFontColor(1.0f, 1.0f, 1.0f, 1.0f);
+ // Introuduce ourselves to the world by drawing a greeting
+ // at the position user touched on the screen
+ rsgDrawText("Hello World!", gTouchX, gTouchY);
+
+ // Return value tells RS roughly how often to redraw
+ // in this case 20 ms
+ return 20;
+}
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsList.java b/libs/rs/java/Samples/src/com/android/samples/RsList.java
index d47be42..2d7add0 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsList.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsList.java
@@ -16,26 +16,8 @@
package com.android.samples;
-import android.renderscript.RSSurfaceView;
-import android.renderscript.RenderScript;
-
import android.app.Activity;
-import android.content.res.Configuration;
import android.os.Bundle;
-import android.os.Handler;
-import android.os.Looper;
-import android.os.Message;
-import android.provider.Settings.System;
-import android.util.Config;
-import android.util.Log;
-import android.view.Menu;
-import android.view.MenuItem;
-import android.view.View;
-import android.view.Window;
-import android.widget.Button;
-import android.widget.ListView;
-
-import java.lang.Runtime;
public class RsList extends Activity {
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsListRS.java b/libs/rs/java/Samples/src/com/android/samples/RsListRS.java
index 8e2d51f..6ee545ac 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsListRS.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsListRS.java
@@ -73,17 +73,12 @@
"Yemen", "Yugoslavia", "Zambia", "Zimbabwe"
};
- int mWidth;
- int mHeight;
-
public RsListRS() {
}
- public void init(RenderScriptGL rs, Resources res, int width, int height) {
+ public void init(RenderScriptGL rs, Resources res) {
mRS = rs;
mRes = res;
- mWidth = width;
- mHeight = height;
initRS();
}
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsListView.java b/libs/rs/java/Samples/src/com/android/samples/RsListView.java
index 00b1723..b67bd48 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsListView.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsListView.java
@@ -15,55 +15,40 @@
*/
package com.android.samples;
-
-import java.io.Writer;
-import java.util.ArrayList;
-import java.util.concurrent.Semaphore;
-
import android.renderscript.RSSurfaceView;
-import android.renderscript.RenderScript;
import android.renderscript.RenderScriptGL;
import android.content.Context;
-import android.content.res.Resources;
-import android.graphics.Bitmap;
-import android.graphics.drawable.BitmapDrawable;
-import android.graphics.drawable.Drawable;
-import android.os.Handler;
-import android.os.Message;
-import android.util.AttributeSet;
-import android.util.Log;
-import android.view.Surface;
-import android.view.SurfaceHolder;
-import android.view.SurfaceView;
-import android.view.KeyEvent;
import android.view.MotionEvent;
public class RsListView extends RSSurfaceView {
public RsListView(Context context) {
super(context);
- //setFocusable(true);
+ ensureRenderScript();
}
private RenderScriptGL mRS;
private RsListRS mRender;
-
- public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
- super.surfaceChanged(holder, format, w, h);
+ private void ensureRenderScript() {
if (mRS == null) {
RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig();
- sc.setDepth(16, 24);
mRS = createRenderScriptGL(sc);
- mRS.setSurface(holder, w, h);
mRender = new RsListRS();
- mRender.init(mRS, getResources(), w, h);
+ mRender.init(mRS, getResources());
}
}
@Override
+ protected void onAttachedToWindow() {
+ super.onAttachedToWindow();
+ ensureRenderScript();
+ }
+
+ @Override
protected void onDetachedFromWindow() {
+ mRender = null;
if (mRS != null) {
mRS = null;
destroyRenderScriptGL();
@@ -71,23 +56,14 @@
}
@Override
- public boolean onKeyDown(int keyCode, KeyEvent event)
- {
- // break point at here
- // this method doesn't work when 'extends View' include 'extends ScrollView'.
- return super.onKeyDown(keyCode, event);
- }
-
-
- @Override
public boolean onTouchEvent(MotionEvent ev)
{
boolean ret = false;
int act = ev.getAction();
- if (act == ev.ACTION_DOWN) {
+ if (act == MotionEvent.ACTION_DOWN) {
mRender.onActionDown((int)ev.getX(), (int)ev.getY());
ret = true;
- } else if (act == ev.ACTION_MOVE) {
+ } else if (act == MotionEvent.ACTION_MOVE) {
mRender.onActionMove((int)ev.getX(), (int)ev.getY());
ret = true;
}
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsRenderStates.java b/libs/rs/java/Samples/src/com/android/samples/RsRenderStates.java
index 33c1719..ff8c2de 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsRenderStates.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsRenderStates.java
@@ -16,26 +16,8 @@
package com.android.samples;
-import android.renderscript.RSSurfaceView;
-import android.renderscript.RenderScript;
-
import android.app.Activity;
-import android.content.res.Configuration;
import android.os.Bundle;
-import android.os.Handler;
-import android.os.Looper;
-import android.os.Message;
-import android.provider.Settings.System;
-import android.util.Config;
-import android.util.Log;
-import android.view.Menu;
-import android.view.MenuItem;
-import android.view.View;
-import android.view.Window;
-import android.widget.Button;
-import android.widget.ListView;
-
-import java.lang.Runtime;
public class RsRenderStates extends Activity {
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesRS.java b/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesRS.java
index 87840a7..49b65d6 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesRS.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesRS.java
@@ -16,8 +16,6 @@
package com.android.samples;
-import java.io.Writer;
-
import android.content.res.Resources;
import android.graphics.Bitmap;
import android.graphics.BitmapFactory;
@@ -39,11 +37,11 @@
public RsRenderStatesRS() {
}
- public void init(RenderScriptGL rs, Resources res, int width, int height) {
+ public void init(RenderScriptGL rs, Resources res) {
mRS = rs;
+ mWidth = mRS.getWidth();
+ mHeight = mRS.getHeight();
mRes = res;
- mWidth = width;
- mHeight = height;
mOptionsARGB.inScaled = false;
mOptionsARGB.inPreferredConfig = Bitmap.Config.ARGB_8888;
mMode = 0;
@@ -51,6 +49,15 @@
initRS();
}
+ public void surfaceChanged() {
+ mWidth = mRS.getWidth();
+ mHeight = mRS.getHeight();
+
+ Matrix4f proj = new Matrix4f();
+ proj.loadOrthoWindow(mWidth, mHeight);
+ mPVA.setProjection(proj);
+ }
+
private Resources mRes;
private RenderScriptGL mRS;
diff --git a/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesView.java b/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesView.java
index 235d29b..4d339dd 100644
--- a/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesView.java
+++ b/libs/rs/java/Samples/src/com/android/samples/RsRenderStatesView.java
@@ -16,54 +16,48 @@
package com.android.samples;
-import java.io.Writer;
-import java.util.ArrayList;
-import java.util.concurrent.Semaphore;
-
import android.renderscript.RSSurfaceView;
-import android.renderscript.RenderScript;
import android.renderscript.RenderScriptGL;
import android.content.Context;
-import android.content.res.Resources;
-import android.graphics.Bitmap;
-import android.graphics.drawable.BitmapDrawable;
-import android.graphics.drawable.Drawable;
-import android.os.Handler;
-import android.os.Message;
-import android.util.AttributeSet;
-import android.util.Log;
-import android.view.Surface;
-import android.view.SurfaceHolder;
-import android.view.SurfaceView;
-import android.view.KeyEvent;
import android.view.MotionEvent;
+import android.view.SurfaceHolder;
public class RsRenderStatesView extends RSSurfaceView {
public RsRenderStatesView(Context context) {
super(context);
- //setFocusable(true);
+ ensureRenderScript();
}
private RenderScriptGL mRS;
private RsRenderStatesRS mRender;
-
- public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
- super.surfaceChanged(holder, format, w, h);
+ private void ensureRenderScript() {
if (mRS == null) {
RenderScriptGL.SurfaceConfig sc = new RenderScriptGL.SurfaceConfig();
sc.setDepth(16, 24);
mRS = createRenderScriptGL(sc);
- mRS.setSurface(holder, w, h);
mRender = new RsRenderStatesRS();
- mRender.init(mRS, getResources(), w, h);
+ mRender.init(mRS, getResources());
}
}
@Override
+ protected void onAttachedToWindow() {
+ super.onAttachedToWindow();
+ ensureRenderScript();
+ }
+
+ @Override
+ public void surfaceChanged(SurfaceHolder holder, int format, int w, int h) {
+ super.surfaceChanged(holder, format, w, h);
+ mRender.surfaceChanged();
+ }
+
+ @Override
protected void onDetachedFromWindow() {
+ mRender = null;
if (mRS != null) {
mRS = null;
destroyRenderScriptGL();
@@ -71,25 +65,13 @@
}
@Override
- public boolean onKeyDown(int keyCode, KeyEvent event)
- {
- // break point at here
- // this method doesn't work when 'extends View' include 'extends ScrollView'.
- return super.onKeyDown(keyCode, event);
- }
-
-
- @Override
- public boolean onTouchEvent(MotionEvent ev)
- {
- boolean ret = false;
- int act = ev.getAction();
- if (act == ev.ACTION_DOWN) {
+ public boolean onTouchEvent(MotionEvent ev) {
+ if (ev.getAction() == MotionEvent.ACTION_DOWN) {
mRender.onActionDown((int)ev.getX(), (int)ev.getY());
- ret = true;
+ return true;
}
- return ret;
+ return false;
}
}
diff --git a/libs/rs/java/Samples/src/com/android/samples/rslist.rs b/libs/rs/java/Samples/src/com/android/samples/rslist.rs
index b79f4fc..52c870a 100644
--- a/libs/rs/java/Samples/src/com/android/samples/rslist.rs
+++ b/libs/rs/java/Samples/src/com/android/samples/rslist.rs
@@ -37,7 +37,6 @@
int root(int launchID) {
rsgClearColor(0.0f, 0.0f, 0.0f, 0.0f);
- rsgClearDepth(1.0f);
textPos -= (int)gDY*2;
gDY *= 0.95;
