Loading media/java/android/media/SoundPool.java +95 −38 Original line number Diff line number Diff line Loading @@ -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 Loading @@ -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 Loading Loading @@ -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) Loading @@ -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) { Loading @@ -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) { Loading @@ -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) { Loading @@ -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 Loading @@ -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) Loading @@ -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, Loading Loading
media/java/android/media/SoundPool.java +95 −38 Original line number Diff line number Diff line Loading @@ -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 Loading @@ -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 Loading Loading @@ -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) Loading @@ -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) { Loading @@ -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) { Loading @@ -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) { Loading @@ -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 Loading @@ -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) Loading @@ -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, Loading
