com.badlogic.gdx.Audio.java Source code

Introduction

Here is the source code for com.badlogic.gdx.Audio.java

Source

/*******************************************************************************
 * 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;

import com.badlogic.gdx.audio.AudioDevice;
import com.badlogic.gdx.audio.AudioRecorder;
import com.badlogic.gdx.audio.Music;
import com.badlogic.gdx.audio.Sound;
import com.badlogic.gdx.files.FileHandle;
import com.badlogic.gdx.utils.GdxRuntimeException;

/** This interface encapsulates the creation and management of audio resources. It allows you to get direct access to the audio
 * hardware via the {@link AudioDevice} and {@link AudioRecorder} interfaces, create sound effects via the {@link Sound} interface
 * and play music streams via the {@link Music} interface.
 * 
 * <p>
 * All resources created via this interface have to be disposed as soon as they are no longer used.
 * </p>
 * 
 * <p>
 * Note that all {@link Music} instances will be automatically paused when the {@link ApplicationListener#pause()} method is
 * called, and automatically resumed when the {@link ApplicationListener#resume()} method is called.
 * </p>
 * 
 * @author mzechner */
public interface Audio {
    /** Creates a new {@link AudioDevice} either in mono or stereo mode. The AudioDevice has to be disposed via its
     * {@link AudioDevice#dispose()} method when it is no longer used.
     * 
     * @param samplingRate the sampling rate.
     * @param isMono whether the AudioDevice should be in mono or stereo mode
     * @return the AudioDevice
     * 
     * @throws GdxRuntimeException in case the device could not be created */
    public AudioDevice newAudioDevice(int samplingRate, boolean isMono);

    /** Creates a new {@link AudioRecorder}. The AudioRecorder has to be disposed after it is no longer used.
     * 
     * @param samplingRate the sampling rate in Hertz
     * @param isMono whether the recorder records in mono or stereo
     * @return the AudioRecorder
     * 
     * @throws GdxRuntimeException in case the recorder could not be created */
    public AudioRecorder newAudioRecorder(int samplingRate, boolean isMono);

    /** <p>
     * Creates a new {@link Sound} which is used to play back audio effects such as gun shots or explosions. The Sound's audio data
     * is retrieved from the file specified via the {@link FileHandle}. Note that the complete audio data is loaded into RAM. You
     * should therefore not load big audio files with this methods. The current upper limit for decoded audio is 1 MB.
     * </p>
     * 
     * <p>
     * Currently supported formats are WAV, MP3 and OGG.
     * </p>
     * 
     * <p>
     * The Sound has to be disposed if it is no longer used via the {@link Sound#dispose()} method.
     * </p>
     * 
     * @return the new Sound
     * @throws GdxRuntimeException in case the sound could not be loaded */
    public Sound newSound(FileHandle fileHandle);

    /** Creates a new {@link Music} instance which is used to play back a music stream from a file. Currently supported formats are
     * WAV, MP3 and OGG. The Music instance has to be disposed if it is no longer used via the {@link Music#dispose()} method.
     * Music instances are automatically paused when {@link ApplicationListener#pause()} is called and resumed when
     * {@link ApplicationListener#resume()} is called.
     * 
     * @param file the FileHandle
     * @return the new Music or null if the Music could not be loaded
     * @throws GdxRuntimeException in case the music could not be loaded */
    public Music newMusic(FileHandle file);
}