Java tutorial
/******************************************************************************* * Copyright 2011 See AUTHORS file. * * 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.badlogic.gdx.audio; import com.badlogic.gdx.Audio; import com.badlogic.gdx.files.FileHandle; import com.badlogic.gdx.utils.Disposable; /** <p> * A Sound is a short audio clip that can be played numerous times in parallel. It's completely loaded into memory so only load * small audio files. Call the {@link #dispose()} method when you're done using the Sound. * </p> * * <p> * Sound instances are created via a call to {@link Audio#newSound(FileHandle)}. * </p> * * <p> * Calling the {@link #play()} or {@link #play(float)} method will return a long which is an id to that instance of the sound. You * can use this id to modify the playback of that sound instance. * </p> * * <p> * <b>Note<b>: any values provided will not be clamped, it is the developer's responsibility to do so * </p> * * @author badlogicgames@gmail.com */ public interface Sound extends Disposable { /** Plays the sound. If the sound is already playing, it will be played again, concurrently. * @return the id of the sound instance if successful, or -1 on failure. */ public long play(); /** Plays the sound. If the sound is already playing, it will be played again, concurrently. * @param volume the volume in the range [0,1] * @return the id of the sound instance if successful, or -1 on failure. */ public long play(float volume); /** Plays the sound. If the sound is already playing, it will be played again, concurrently. * @param volume the volume in the range [0,1] * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. * @return the id of the sound instance if successful, or -1 on failure. */ public long play(float volume, float pitch, float pan); /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. * @return the id of the sound instance if successful, or -1 on failure. */ public long loop(); /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound * via a call to {@link #stop(long)} using the returned id. * @param volume the volume in the range [0, 1] * @return the id of the sound instance if successful, or -1 on failure. */ public long loop(float volume); /** Plays the sound, looping. If the sound is already playing, it will be played again, concurrently. You need to stop the sound * via a call to {@link #stop(long)} using the returned id. * @param volume the volume in the range [0,1] * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. * @return the id of the sound instance if successful, or -1 on failure. */ public long loop(float volume, float pitch, float pan); /** Stops playing all instances of this sound. */ public void stop(); /** Pauses all instances of this sound. */ public void pause(); /** Resumes all paused instances of this sound. */ public void resume(); /** Releases all the resources. */ public void dispose(); /** Stops the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no longer * playing, this has no effect. * @param soundId the sound id */ public void stop(long soundId); /** Pauses the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is no * longer playing, this has no effect. * @param soundId the sound id */ public void pause(long soundId); /** Resumes the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the sound is not * paused, this has no effect. * @param soundId the sound id */ public void resume(long soundId); /** Sets the sound instance with the given id to be looping. If the sound is no longer playing this has no effect.s * @param soundId the sound id * @param looping whether to loop or not. */ public void setLooping(long soundId, boolean looping); /** Changes the pitch multiplier of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. * If the sound is no longer playing, this has no effect. * @param soundId the sound id * @param pitch the pitch multiplier, 1 == default, >1 == faster, <1 == slower, the value has to be between 0.5 and 2.0 */ public void setPitch(long soundId, float pitch); /** Changes the volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. If the * sound is no longer playing, this has no effect. * @param soundId the sound id * @param volume the volume in the range 0 (silent) to 1 (max volume). */ public void setVolume(long soundId, float volume); /** Sets the panning and volume of the sound instance with the given id as returned by {@link #play()} or {@link #play(float)}. * If the sound is no longer playing, this has no effect. * @param soundId the sound id * @param pan panning in the range -1 (full left) to 1 (full right). 0 is center position. * @param volume the volume in the range [0,1]. */ public void setPan(long soundId, float pan, float volume); /** Sets the priority of a sound currently being played back. Higher priority sounds will be considered last if the maximum * number of concurrently playing sounds is exceeded. This is only a hint and might not be honored by a backend implementation. * @param soundId the sound id as returned by {@link #play()} or {@link #loop()} and their overloaded equivalents. * @param priority the priority (0 == lowest) */ public void setPriority(long soundId, int priority); }