gdx/src/com/badlogic/gdx/audio/Sound.java

   1 /*******************************************************************************\r
   2  * Copyright 2011 See AUTHORS file.\r
   3  * \r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  * \r
   8  *   http://www.apache.org/licenses/LICENSE-2.0\r
   9  * \r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  ******************************************************************************/\r
  16 \r
  17 package com.badlogic.gdx.audio;\r
  18 \r
  19 import com.badlogic.gdx.Audio;\r
  20 import com.badlogic.gdx.files.FileHandle;\r
  21 import com.badlogic.gdx.utils.Disposable;\r
  22 \r
  23 /** <p>\r
  24  * A Sound is a short audio clip that can be played numerous times in parallel. It's completely loaded into memory so only load\r
  25  * small audio files. Call the {@link #dispose()} method when you're done using the Sound.\r
  26  * </p>\r
  27  * \r
  28  * <p>\r
  29  * Sound instances are created via a call to {@link Audio#newSound(FileHandle)}.\r
  30  * </p>\r
  31  * \r
  32  * <p>\r
  33  * Calling the {@link #play()} or {@link #play(float)} method will return a long which is an id to that instance of the sound. You\r
  34  * can use this id to modify the playback of that sound instance.\r
  35  * </p>\r
  36  * \r
  37  * @author badlogicgames@gmail.com */\r
  38 public interface Sound extends Disposable {\r
  39         /** Plays the sound. If the sound is already playing, it will be played again, concurrently.\r
  40          * @return the id of the sound instance if successful, or -1 on failure. */\r
  41         public long play ();\r
  42 \r
  43         /** Plays the sound. If the sound is already playing, it will be played again, concurrently.\r
  44          * @param volume the volume in the range [0,1]\r
  45          * @return the id of the sound instance if successful, or -1 on failure. */\r
  46         public long play (float volume);\r
  47 \r
  48         /** Plays the sound. If the sound is already playing, it will be played again, concurrently.\r
  49          * @param volume the volume in the range [0,1]\r
  50          * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0\r
  51          * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position.\r
  52          * @return the id of the sound instance if successful, or -1 on failure. */\r
  53         public long play (float volume, float pitch, float pan);\r
  54 \r
  55         /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently.\r
  56          * @return the id of the sound instance if successful, or -1 on failure. */\r
  57         public long loop ();\r
  58 \r
  59         /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound\r
  60          * via a call to {@link #stop(long)} using the returned id.\r
  61          * @param volume the volume in the range [0, 1]\r
  62          * @return the id of the sound instance if successful, or -1 on failure. */\r
  63         public long loop (float volume);\r
  64 \r
  65         /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound\r
  66          * via a call to {@link #stop(long)} using the returned id.\r
  67          * @param volume the volume in the range [0,1]\r
  68          * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0\r
  69          * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position.\r
  70          * @return the id of the sound instance if successful, or -1 on failure. */\r
  71         public long loop (float volume, float pitch, float pan);\r
  72 \r
  73         /** Stops playing all instances of this sound. */\r
  74         public void stop ();\r
  75         \r
  76         /** Pauses all instances of this sound. */\r
  77         public void pause ();\r
  78         \r
  79         /** Resumes all paused instances of this sound. */\r
  80         public void resume ();\r
  81 \r
  82         /** Releases all the resources. */\r
  83         public void dispose ();\r
  84 \r
  85         /** Stops the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no longer\r
  86          * playing, this has no effect.\r
  87          * @param soundId the sound id */\r
  88         public void stop (long soundId);\r
  89 \r
  90         /** Pauses the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no longer\r
  91          * playing, this has no effect.\r
  92          * @param soundId the sound id */\r
  93         public void pause (long soundId);\r
  94         \r
  95         /** Resumes the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is not\r
  96          * paused, this has no effect.\r
  97          * @param soundId the sound id */\r
  98         public void resume (long soundId);\r
  99         \r
 100         /** Sets the sound instance with the given id to be looping. If the sound is no longer playing this has no effect.s\r
 101          * @param soundId the sound id\r
 102          * @param looping whether to loop or not. */\r
 103         public void setLooping (long soundId, boolean looping);\r
 104 \r
 105         /** Changes the pitch multiplier of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}.\r
 106          * If the sound is no longer playing, this has no effect.\r
 107          * @param soundId the sound id\r
 108          * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 */\r
 109         public void setPitch (long soundId, float pitch);\r
 110 \r
 111         /** Changes the volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the\r
 112          * sound is no longer playing, this has no effect.\r
 113          * @param soundId the sound id\r
 114          * @param volume the volume in the range 0 (silent) to 1 (max volume). */\r
 115         public void setVolume (long soundId, float volume);\r
 116 \r
 117         /** Sets the panning and volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}.\r
 118          * If the sound is no longer playing, this has no effect.\r
 119          * @param soundId the sound id\r
 120          * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position.\r
 121          * @param volume the volume in the range [0,1]. */\r
 122         public void setPan (long soundId, float pan, float volume);\r
 123         \r
 124         /**\r
 125          * Sets the priority of a sound currently being played back. Higher priority sounds will be considered last\r
 126          * if the maximum number of concurrently playing sounds is exceeded. This is only a \r
 127          * hint and might not be honored by a backend implementation.\r
 128          * @param soundId the sound id as returned by {@link #play()} or {@link #loop()} and their overloaded equivalents.\r
 129          * @param priority the priority (0 == lowest)\r
 130          */\r
 131         public void setPriority(long soundId, int priority);\r
 132 }\r