/* Format conversion API
    Copyright (C) 2005 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
 GNU Classpath is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2, or (at your option)
 any later version.
 
 GNU Classpath is distributed in the hope that it will be useful, but
 WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with GNU Classpath; see the file COPYING.  If not, write to the
 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
 02110-1301 USA.
 
 Linking this library statically or dynamically with other modules is
 making a combined work based on this library.  Thus, the terms and
 conditions of the GNU General Public License cover the whole
 combination.
 
 As a special exception, the copyright holders of this library give you
 permission to link this library with independent modules to produce an
 executable, regardless of the license terms of these independent
 modules, and to copy and distribute the resulting executable under
 terms of your choice, provided that you also meet, for each linked
 independent module, the terms and conditions of the license of that
 module.  An independent module is a module which is not derived from
 or based on this library.  If you modify this library, you may extend
 this exception to your version of the library, but you are not
 obligated to do so.  If you do not wish to do so, delete this
 exception statement from your version. */

package ddf.minim.javax.sound.sampled.spi;

import ddf.minim.javax.sound.sampled.AudioFormat;
import ddf.minim.javax.sound.sampled.AudioInputStream;

/**
 * A format conversion provider supplies methods for converting between
 * different audio formats. This abstract class defines the interface to this
 * functionality; concrete subclasses will implement the methods declared here.
 * 
 * @since 1.3
 */
public abstract class FormatConversionProvider {
	/**
	 * Create a new format conversion provider.
	 */
	public FormatConversionProvider() {
	}

	/**
	 * Return an audio input stream given the desired target encoding and
	 * another audio input stream. The data in the given stream will be
	 * converted to the desired encoding.
	 * 
	 * @param encoding
	 *            the encoding
	 * @param source
	 *            the source audio input stream
	 * @return a new audio input stream
	 * @throws IllegalArgumentException
	 *             if the conversion is not supported
	 */
	public abstract AudioInputStream getAudioInputStream(
			AudioFormat.Encoding encoding, AudioInputStream source);

	/**
	 * Return an audio input stream given the desired target format and another
	 * audio input stream. The data in the given stream will be converted to the
	 * desired format.
	 * 
	 * @param format
	 *            the format
	 * @param source
	 *            the source audio input stream
	 * @return a new audio input stream
	 * @throws IllegalArgumentException
	 *             if the conversion is not supported
	 */
	public abstract AudioInputStream getAudioInputStream(AudioFormat format,
			AudioInputStream source);

	/**
	 * Return an array of all the source encodings supported by this conversion
	 * provider.
	 */
	public abstract AudioFormat.Encoding[] getSourceEncodings();

	/**
	 * Return an array of all the target encodings supported by this conversion
	 * provider.
	 */
	public abstract AudioFormat.Encoding[] getTargetEncodings();

	/**
	 * Return an array of all the target encodings that are available for a
	 * given source format.
	 * 
	 * @param fmt
	 *            the source format
	 * @return an array of supported target encodings
	 */
	public abstract AudioFormat.Encoding[] getTargetEncodings(AudioFormat fmt);

	/**
	 * Return a array of all the target formats that match given target
	 * encoding, and to which this provider can convert the source format.
	 * 
	 * @param targ
	 *            the target encoding to match
	 * @param src
	 *            the source format
	 * @return an array of supported target formats
	 */
	public abstract AudioFormat[] getTargetFormats(AudioFormat.Encoding targ,
			AudioFormat src);

	/**
	 * Return true if this provider supports conversion from the given source
	 * format to the given target encoding.
	 * 
	 * @param targ
	 *            the target encoding
	 * @param src
	 *            the source format
	 * @return true if the conversion is supported
	 */
	public boolean isConversionSupported(AudioFormat.Encoding targ,
			AudioFormat src) {
		AudioFormat.Encoding[] encodings = getTargetEncodings(src);
		for (int i = 0; i < encodings.length; ++i) {
			if (targ.equals(encodings[i]))
				return true;
		}
		return false;
	}

	/**
	 * Return true if this provider supports conversions from the given source
	 * format to the given target format.
	 * 
	 * @param targ
	 *            the source format
	 * @param src
	 *            the target format
	 * @return true if the conversion is supported
	 */
	public boolean isConversionSupported(AudioFormat targ, AudioFormat src) {
		AudioFormat[] encodings = getTargetFormats(targ.getEncoding(), src);
		return encodings.length > 0;
	}

	/**
	 * Return true if an encoding matching the argument is supported as a source
	 * encoding by this provider.
	 * 
	 * @param src
	 *            the source encoding
	 * @return true if it is supported
	 */
	public boolean isSourceEncodingSupported(AudioFormat.Encoding src) {
		AudioFormat.Encoding[] srcs = getSourceEncodings();
		for (int i = 0; i < srcs.length; ++i) {
			if (src.equals(srcs[i]))
				return true;
		}
		return false;
	}

	/**
	 * Return true if an encoding matching the argument is supported as a target
	 * encoding by this provider.
	 * 
	 * @param targ
	 *            the target encoding
	 * @return true if it is supported
	 */
	public boolean isTargetEncodingSupported(AudioFormat.Encoding targ) {
		AudioFormat.Encoding[] encodings = getTargetEncodings();
		for (int i = 0; i < encodings.length; ++i) {
			if (targ.equals(encodings[i]))
				return true;
		}
		return false;
	}
}