Merge branch 'readonly-p4-donut' into donut

1 files changed, 95 insertions, 38 deletions

diff --git a/media/java/android/media/SoundPool.java b/media/java/android/media/SoundPool.java
index ab3274b..b13c2e6 100644
--- a/media/java/android/media/SoundPool.java
+++ b/media/java/android/media/SoundPool.java
@@ -46,6 +46,19 @@ import java.io.IOException;
  * number of streams helps to cap CPU loading and reducing the likelihood that
  * audio mixing will impact visuals or UI performance.</p> 
  *
+ * <p>Sounds can be looped by setting a non-zero loop value. A value of -1
+ * causes the sound to loop forever. In this case, the application must 
+ * explicitly call the stop() function to stop the sound. Any other non-zero
+ * value will cause the sound to repeat the specified number of times, e.g.
+ * a value of 3 causes the sound to play a total of 4 times.</p>
+ *
+ * <p>The playback rate can also be changed. A playback rate of 1.0 causes
+ * the sound to play at its original frequency (resampled, if necessary,
+ * to the hardware output frequency). A playback rate of 2.0 causes the
+ * sound to play at twice its original frequency, and a playback rate of
+ * 0.5 causes it to play at half its original frequency. The playback
+ * rate range is 0.5 to 2.0.</p>
+ *
  * <p>Priority runs low to high, i.e. higher numbers are higher priority.
  * Priority is used when a call to play() would cause the number of active
  * streams to exceed the value established by the maxStreams parameter when
@@ -72,6 +85,13 @@ import java.io.IOException;
  * adjusting the playback rate in real-time for doppler or synthesis
  * effects.</p>
  *
+ * <p>Note that since streams can be stopped due to resource constraints, the
+ * streamID is a reference to a particular instance of a stream. If the stream
+ * is stopped to allow a higher priority stream to play, the stream is no
+ * longer be valid. However, the application is allowed to call methods on
+ * the streamID without error. This may help simplify program logic since
+ * the application need not concern itself with the stream lifecycle.</p>
+ *
  * <p>In our example, when the player has completed the level, the game
  * logic should call SoundPool.release() to release all the native resources
  * in use and then set the SoundPool reference to null. If the player starts
@@ -104,10 +124,11 @@ public class SoundPool
     }
 
     /**
-     * Load the sound from the specified path
-     * 
+     * Load the sound from the specified path.
+     *
      * @param path the path to the audio file
-     * @param priority the priority of the sound. Currently has no effect.
+     * @param priority the priority of the sound. Currently has no effect. Use
+     *                 a value of 1 for future compatibility.
      * @return a sound ID. This value can be used to play or unload the sound.
      */
     public int load(String path, int priority)
@@ -133,17 +154,18 @@ public class SoundPool
     }
 
     /**
-     * Load the sound from the specified APK resource
+     * Load the sound from the specified APK resource.
      *
-     * <p>Note that the extension is dropped. For example, if you want to load
+     * Note that the extension is dropped. For example, if you want to load
      * a sound from the raw resource file "explosion.mp3", you would specify
      * "R.raw.explosion" as the resource ID. Note that this means you cannot
      * have both an "explosion.wav" and an "explosion.mp3" in the res/raw
-     * directory.</p>
+     * directory.
      * 
      * @param context the application context
      * @param resId the resource ID
-     * @param priority the priority of the sound. Currently has no effect.
+     * @param priority the priority of the sound. Currently has no effect. Use
+     *                 a value of 1 for future compatibility.
      * @return a sound ID. This value can be used to play or unload the sound.
      */
     public int load(Context context, int resId, int priority) {
@@ -162,10 +184,11 @@ public class SoundPool
     }
 
     /**
-     * Load the sound from an asset file descriptor
+     * Load the sound from an asset file descriptor.
      *
      * @param afd an asset file descriptor
-     * @param priority the priority of the sound. Currently has no effect.
+     * @param priority the priority of the sound. Currently has no effect. Use
+     *                 a value of 1 for future compatibility.
      * @return a sound ID. This value can be used to play or unload the sound.
      */
     public int load(AssetFileDescriptor afd, int priority) {
@@ -181,16 +204,17 @@ public class SoundPool
     }
 
     /**
-     * Load the sound from a FileDescriptor
+     * Load the sound from a FileDescriptor.
      *
-     * <p>This version is useful if you store multiple sounds in a single
+     * This version is useful if you store multiple sounds in a single
      * binary. The offset specifies the offset from the start of the file
-     * and the length specifies the length of the sound within the file.</p>
+     * and the length specifies the length of the sound within the file.
      *
      * @param fd a FileDescriptor object
      * @param offset offset to the start of the sound
      * @param length length of the sound
-     * @param priority the priority of the sound. Currently has no effect.
+     * @param priority the priority of the sound. Currently has no effect. Use
+     *                 a value of 1 for future compatibility.
      * @return a sound ID. This value can be used to play or unload the sound.
      */
     public int load(FileDescriptor fd, long offset, long length, int priority) {
@@ -202,11 +226,11 @@ public class SoundPool
     private native final int _load(FileDescriptor fd, long offset, long length, int priority);
 
     /**
-     * Unload a sound from a sound ID
+     * Unload a sound from a sound ID.
      *
-     * <p>Unloads the sound specified by the soundID. This is the value
+     * Unloads the sound specified by the soundID. This is the value
      * returned by the load() function. Returns true if the sound is
-     * successfully unloaded, false if the sound was already unloaded.</p>
+     * successfully unloaded, false if the sound was already unloaded.
      *
      * @param soundID a soundID returned by the load() function
      * @return true if just unloaded, false if previously unloaded
@@ -214,66 +238,77 @@ public class SoundPool
     public native final boolean unload(int soundID);
 
     /**
-     * Play a sound from a sound ID
+     * Play a sound from a sound ID.
      *
-     * <p>Play the sound specified by the soundID. This is the value 
+     * Play the sound specified by the soundID. This is the value 
      * returned by the load() function. Returns a non-zero streamID
      * if successful, zero if it fails. The streamID can be used to
      * further control playback. Note that calling play() may cause
      * another sound to stop playing if the maximum number of active
-     * streams is exceeded.</p>
+     * streams is exceeded. A loop value of -1 means loop forever,
+     * a value of 0 means don't loop, other values indicate the
+     * number of repeats, e.g. a value of 1 plays the audio twice.
+     * The playback rate allows the application to vary the playback
+     * rate (pitch) of the sound. A value of 1.0 means play back at
+     * the original frequency. A value of 2.0 means play back twice
+     * as fast, and a value of 0.5 means playback at half speed.
      *
      * @param soundID a soundID returned by the load() function
+     * @param leftVolume left volume value (range = 0.0 to 1.0)
+     * @param rightVolume right volume value (range = 0.0 to 1.0)
+     * @param priority stream priority (0 = lowest priority)
+     * @param loop loop mode (0 = no loop, -1 = loop forever)
+     * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0)
      * @return non-zero streamID if successful, zero if failed
      */
     public native final int play(int soundID, float leftVolume, float rightVolume,
             int priority, int loop, float rate);
 
     /**
-     * Pause a playback stream
+     * Pause a playback stream.
      *
-     * <p>Pause the stream specified by the streamID. This is the
+     * Pause the stream specified by the streamID. This is the
      * value returned by the play() function. If the stream is
      * playing, it will be paused. If the stream is not playing
      * (e.g. is stopped or was previously paused), calling this
-     * function will have no effect.</p>
+     * function will have no effect.
      *
      * @param streamID a streamID returned by the play() function
      */
     public native final void pause(int streamID);
 
     /**
-     * Resume a playback stream
+     * Resume a playback stream.
      *
-     * <p>Resume the stream specified by the streamID. This
+     * Resume the stream specified by the streamID. This
      * is the value returned by the play() function. If the stream
      * is paused, this will resume playback. If the stream was not
-     * previously paused, calling this function will have no effect.</p>
+     * previously paused, calling this function will have no effect.
      *
      * @param streamID a streamID returned by the play() function
      */
     public native final void resume(int streamID);
 
     /**
-     * Stop a playback stream
+     * Stop a playback stream.
      *
-     * <p>Stop the stream specified by the streamID. This
+     * Stop the stream specified by the streamID. This
      * is the value returned by the play() function. If the stream
      * is playing, it will be stopped. It also releases any native
      * resources associated with this stream. If the stream is not
-     * playing, it will have no effect.</p>
+     * playing, it will have no effect.
      *
      * @param streamID a streamID returned by the play() function
      */
     public native final void stop(int streamID);
 
     /**
-     * Set stream volume
+     * Set stream volume.
      *
-     * <p>Sets the volume on the stream specified by the streamID.
+     * Sets the volume on the stream specified by the streamID.
      * This is the value returned by the play() function. The
      * value must be in the range of 0.0 to 1.0. If the stream does
-     * not exist, it will have no effect.</p>
+     * not exist, it will have no effect.
      *
      * @param streamID a streamID returned by the play() function
      * @param leftVolume left volume value (range = 0.0 to 1.0)
@@ -283,29 +318,51 @@ public class SoundPool
             float leftVolume, float rightVolume);
 
     /**
-     * Change stream priority
+     * Change stream priority.
      *
-     * <p>Change the priority of the stream specified by the streamID.
+     * Change the priority of the stream specified by the streamID.
      * This is the value returned by the play() function. Affects the
-     * order in which streams are re-used to play new sounds.
+     * order in which streams are re-used to play new sounds. If the
+     * stream does not exist, it will have no effect.
      *
      * @param streamID a streamID returned by the play() function
      */
     public native final void setPriority(int streamID, int priority);
 
     /**
-     * Change stream priority
+     * Set loop mode.
      *
-     * <p>Change the priority of the stream specified by the streamID.
-     * This is the value returned by the play() function. Affects the
-     * order in which streams are re-used to play new sounds.
+     * Change the loop mode. A loop value of -1 means loop forever,
+     * a value of 0 means don't loop, other values indicate the
+     * number of repeats, e.g. a value of 1 plays the audio twice.
+     * If the stream does not exist, it will have no effect.
      *
      * @param streamID a streamID returned by the play() function
+     * @param loop loop mode (0 = no loop, -1 = loop forever)
      */
     public native final void setLoop(int streamID, int loop);
 
+    /**
+     * Change playback rate.
+     *
+     * The playback rate allows the application to vary the playback
+     * rate (pitch) of the sound. A value of 1.0 means playback at
+     * the original frequency. A value of 2.0 means playback twice
+     * as fast, and a value of 0.5 means playback at half speed.
+     * If the stream does not exist, it will have no effect.
+     *
+     * @param streamID a streamID returned by the play() function
+     * @param rate playback rate (1.0 = normal playback, range 0.5 to 2.0)
+     */
     public native final void setRate(int streamID, float rate);
 
+    /**
+     * Release the SoundPool resources.
+     *
+     * Release all memory and native resources used by the SoundPool
+     * object. The SoundPool can no longer be used and the reference
+     * should be set to null.
+     */
     public native final void release();
 
     private native final void native_setup(Object mediaplayer_this,