/*

 * Copyright (c) 1999, 2013, Oracle and/or its affiliates. All rights reserved.

 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

 *

 * This code is free software; you can redistribute it and/or modify it

 * under the terms of the GNU General Public License version 2 only, as

 * published by the Free Software Foundation.  Oracle designates this

 * particular file as subject to the "Classpath" exception as provided

 * by Oracle in the LICENSE file that accompanied this code.

 *

 * This code 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

 * version 2 for more details (a copy is included in the LICENSE file that

 * accompanied this code).

 *

 * You should have received a copy of the GNU General Public License version

 * 2 along with this work; if not, write to the Free Software Foundation,

 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

 *

 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA

 * or visit www.oracle.com if you need additional information or have any

 * questions.

 */

package javax.sound.midi;

import javax.sound.sampled.Control;

/**

 * A <code>Synthesizer</code> generates sound.  This usually happens when one of

 * the <code>Synthesizer</code>'s {@link MidiChannel} objects receives a

 * {@link MidiChannel#noteOn(int, int) noteOn} message, either

 * directly or via the <code>Synthesizer</code> object.

 * Many <code>Synthesizer</code>s support <code>Receivers</code>, through which

 * MIDI events can be delivered to the <code>Synthesizer</code>.

 * In such cases, the <code>Synthesizer</code> typically responds by sending

 * a corresponding message to the appropriate <code>MidiChannel</code>, or by

 * processing the event itself if the event isn't one of the MIDI channel

 * messages.

 * <p>

 * The <code>Synthesizer</code> interface includes methods for loading and

 * unloading instruments from soundbanks.  An instrument is a specification for synthesizing a

 * certain type of sound, whether that sound emulates a traditional instrument or is

 * some kind of sound effect or other imaginary sound. A soundbank is a collection of instruments, organized

 * by bank and program number (via the instrument's <code>Patch</code> object).

 * Different <code>Synthesizer</code> classes might implement different sound-synthesis

 * techniques, meaning that some instruments and not others might be compatible with a

 * given synthesizer.

 * Also, synthesizers may have a limited amount of memory for instruments, meaning

 * that not every soundbank and instrument can be used by every synthesizer, even if

 * the synthesis technique is compatible.

 * To see whether the instruments from

 * a certain soundbank can be played by a given synthesizer, invoke the

 * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} method of

 * <code>Synthesizer</code>.

 * <p>

 * "Loading" an instrument means that that instrument becomes available for

 * synthesizing notes.  The instrument is loaded into the bank and

 * program location specified by its <code>Patch</code> object.  Loading does

 * not necessarily mean that subsequently played notes will immediately have

 * the sound of this newly loaded instrument.  For the instrument to play notes,

 * one of the synthesizer's <code>MidiChannel</code> objects must receive (or have received)

 * a program-change message that causes that particular instrument's

 * bank and program number to be selected.

 *

 * @see MidiSystem#getSynthesizer

 * @see Soundbank

 * @see Instrument

 * @see MidiChannel#programChange(int, int)

 * @see Receiver

 * @see Transmitter

 * @see MidiDevice

 *

 * @author Kara Kytle

 */

public interface Synthesizer extends MidiDevice {

    // SYNTHESIZER METHODS

    /**

     * Obtains the maximum number of notes that this synthesizer can sound simultaneously.

     * @return the maximum number of simultaneous notes

     * @see #getVoiceStatus

     */

    public int getMaxPolyphony();

    /**

     * Obtains the processing latency incurred by this synthesizer, expressed in

     * microseconds.  This latency measures the worst-case delay between the

     * time a MIDI message is delivered to the synthesizer and the time that the

     * synthesizer actually produces the corresponding result.

     * <p>

     * Although the latency is expressed in microseconds, a synthesizer's actual measured

     * delay may vary over a wider range than this resolution suggests.  For example,

     * a synthesizer might have a worst-case delay of a few milliseconds or more.

     *

     * @return the worst-case delay, in microseconds

     */

    public long getLatency();

    /**

     * Obtains the set of MIDI channels controlled by this synthesizer.  Each

     * non-null element in the returned array is a <code>MidiChannel</code> that

     * receives the MIDI messages sent on that channel number.

     * <p>

     * The MIDI 1.0 specification provides for 16 channels, so this

     * method returns an array of at least 16 elements.  However, if this synthesizer

     * doesn't make use of all 16 channels, some of the elements of the array

     * might be <code>null</code>, so you should check each element

     * before using it.

     * @return an array of the <code>MidiChannel</code> objects managed by this

     * <code>Synthesizer</code>.  Some of the array elements may be <code>null</code>.

     */

    public MidiChannel[] getChannels();

    /**

     * Obtains the current status of the voices produced by this synthesizer.

     * If this class of <code>Synthesizer</code> does not provide voice

     * information, the returned array will always be of length 0.  Otherwise,

     * its length is always equal to the total number of voices, as returned by

     * <code>getMaxPolyphony()</code>.  (See the <code>VoiceStatus</code> class

     * description for an explanation of synthesizer voices.)

     *

     * @return an array of <code>VoiceStatus</code> objects that supply

     * information about the corresponding synthesizer voices

     * @see #getMaxPolyphony

     * @see VoiceStatus

     */

    public VoiceStatus[] getVoiceStatus();

    /**

     * Informs the caller whether this synthesizer is capable of loading

     * instruments from the specified soundbank.

     * If the soundbank is unsupported, any attempts to load instruments from

     * it will result in an <code>IllegalArgumentException</code>.

     * @param soundbank soundbank for which support is queried

     * @return <code>true</code> if the soundbank is supported, otherwise <code>false</code>

     * @see #loadInstruments

     * @see #loadAllInstruments

     * @see #unloadInstruments

     * @see #unloadAllInstruments

     * @see #getDefaultSoundbank

     */

    public boolean isSoundbankSupported(Soundbank soundbank);

    /**

     * Makes a particular instrument available for synthesis.  This instrument

     * is loaded into the patch location specified by its <code>Patch</code>

     * object, so that if a program-change message is

     * received (or has been received) that causes that patch to be selected,

     * subsequent notes will be played using the sound of

     * <code>instrument</code>.  If the specified instrument is already loaded,

     * this method does nothing and returns <code>true</code>.

     * <p>

     * The instrument must be part of a soundbank

     * that this <code>Synthesizer</code> supports.  (To make sure, you can use

     * the <code>getSoundbank</code> method of <code>Instrument</code> and the

     * <code>isSoundbankSupported</code> method of <code>Synthesizer</code>.)

     * @param instrument instrument to load

     * @return <code>true</code> if the instrument is successfully loaded (or

     * already had been), <code>false</code> if the instrument could not be

     * loaded (for example, if the synthesizer has insufficient

     * memory to load it)

     * @throws IllegalArgumentException if this

     * <code>Synthesizer</code> doesn't support the specified instrument's

     * soundbank

     * @see #unloadInstrument

     * @see #loadInstruments

     * @see #loadAllInstruments

     * @see #remapInstrument

     * @see SoundbankResource#getSoundbank

     * @see MidiChannel#programChange(int, int)

     */

    public boolean loadInstrument(Instrument instrument);

    /**

     * Unloads a particular instrument.

     * @param instrument instrument to unload

     * @throws IllegalArgumentException if this

     * <code>Synthesizer</code> doesn't support the specified instrument's

     * soundbank

     * @see #loadInstrument

     * @see #unloadInstruments

     * @see #unloadAllInstruments

     * @see #getLoadedInstruments

     * @see #remapInstrument

     */

    public void unloadInstrument(Instrument instrument);

    /**

     * Remaps an instrument. Instrument <code>to</code> takes the

     * place of instrument <code>from</code>.<br>

     * For example, if <code>from</code> was located at bank number 2,

     * program number 11, remapping causes that bank and program location

     * to be occupied instead by <code>to</code>.<br>

     * If the function succeeds,  instrument <code>from</code> is unloaded.

     * <p>To cancel the remapping reload instrument <code>from</code> by

     * invoking one of {@link #loadInstrument}, {@link #loadInstruments}

     * or {@link #loadAllInstruments}.

     *

     * @param from the <code>Instrument</code> object to be replaced

     * @param to the <code>Instrument</code> object to be used in place

     * of the old instrument, it should be loaded into the synthesizer

     * <code>false</code> if feature is not implemented by synthesizer

     * @throws IllegalArgumentException if instrument

     * <code>from</code> or instrument <code>to</code> aren't supported by

     * synthesizer or if instrument <code>to</code> is not loaded

     * @throws NullPointerException if <code>from</code> or

     * <code>to</code> parameters have null value

     * @see #loadInstrument

     * @see #loadInstruments

     * @see #loadAllInstruments

     */

    public boolean remapInstrument(Instrument from, Instrument to);

    /**

     * Obtains the default soundbank for the synthesizer, if one exists.

     * (Some synthesizers provide a default or built-in soundbank.)

     * If a synthesizer doesn't have a default soundbank, instruments must

     * be loaded explicitly from an external soundbank.

     * @return default soundbank, or <code>null</code> if one does not exist.

     * @see #isSoundbankSupported

     */

    public Soundbank getDefaultSoundbank();

    /**

     * Obtains a list of instruments that come with the synthesizer.  These

     * instruments might be built into the synthesizer, or they might be

     * part of a default soundbank provided with the synthesizer, etc.

     * <p>

     * Note that you don't use this method  to find out which instruments are

     * currently loaded onto the synthesizer; for that purpose, you use

     * <code>getLoadedInstruments()</code>.

     * Nor does the method indicate all the instruments that can be loaded onto

     * the synthesizer; it only indicates the subset that come with the synthesizer.

     * To learn whether another instrument can be loaded, you can invoke

     * <code>isSoundbankSupported()</code>, and if the instrument's

     * <code>Soundbank</code> is supported, you can try loading the instrument.

     *

     * @return list of available instruments. If the synthesizer

     * has no instruments coming with it, an array of length 0 is returned.

     * @see #getLoadedInstruments

     * @see #isSoundbankSupported(Soundbank)

     * @see #loadInstrument

     */

    public Instrument[] getAvailableInstruments();

    /**

     * Obtains a list of the instruments that are currently loaded onto this

     * <code>Synthesizer</code>.

     * @return a list of currently loaded instruments

     * @see #loadInstrument

     * @see #getAvailableInstruments

     * @see Soundbank#getInstruments

     */

    public Instrument[] getLoadedInstruments();

    /**

     * Loads onto the <code>Synthesizer</code> all instruments contained

     * in the specified <code>Soundbank</code>.

     * @param soundbank the <code>Soundbank</code> whose are instruments are

     * to be loaded

     * @return <code>true</code> if the instruments are all successfully loaded (or

     * already had been), <code>false</code> if any instrument could not be

     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)

     * @throws IllegalArgumentException if the requested soundbank is

     * incompatible with this synthesizer.

     * @see #isSoundbankSupported

     * @see #loadInstrument

     * @see #loadInstruments

     */

    public boolean loadAllInstruments(Soundbank soundbank);

    /**

     * Unloads all instruments contained in the specified <code>Soundbank</code>.

     * @param soundbank soundbank containing instruments to unload

     * @throws IllegalArgumentException thrown if the soundbank is not supported.

     * @see #isSoundbankSupported

     * @see #unloadInstrument

     * @see #unloadInstruments

     */

    public void unloadAllInstruments(Soundbank soundbank);

    /**

     * Loads the instruments referenced by the specified patches, from the

     * specified <code>Soundbank</code>.  Each of the <code>Patch</code> objects

     * indicates a bank and program number; the <code>Instrument</code> that

     * has the matching <code>Patch</code> is loaded into that bank and program

     * location.

     * @param soundbank the <code>Soundbank</code> containing the instruments to load

     * @param patchList list of patches for which instruments should be loaded

     * @return <code>true</code> if the instruments are all successfully loaded (or

     * already had been), <code>false</code> if any instrument could not be

     * loaded (for example, if the <code>Synthesizer</code> had insufficient memory)

     * @throws IllegalArgumentException thrown if the soundbank is not supported.

     * @see #isSoundbankSupported

     * @see Instrument#getPatch

     * @see #loadAllInstruments

     * @see #loadInstrument

     * @see Soundbank#getInstrument(Patch)

     * @see Sequence#getPatchList()

     */

    public boolean loadInstruments(Soundbank soundbank, Patch[] patchList);

    /**

     * Unloads the instruments referenced by the specified patches, from the MIDI sound bank specified.

     * @param soundbank soundbank containing instruments to unload

     * @param patchList list of patches for which instruments should be unloaded

     * @throws IllegalArgumentException thrown if the soundbank is not supported.

     *

     * @see #unloadInstrument

     * @see #unloadAllInstruments

     * @see #isSoundbankSupported

     * @see Instrument#getPatch

     * @see #loadInstruments

     */

    public void unloadInstruments(Soundbank soundbank, Patch[] patchList);

    // RECEIVER METHODS

    /**

     * Obtains the name of the receiver.

     * @return receiver name

     */

    //  public abstract String getName();

    /**

     * Opens the receiver.

     * @throws MidiUnavailableException if the receiver is cannot be opened,

     * usually because the MIDI device is in use by another application.

     * @throws SecurityException if the receiver cannot be opened due to security

     * restrictions.

     */

    //  public abstract void open() throws MidiUnavailableException, SecurityException;

    /**

     * Closes the receiver.

     */

    //  public abstract void close();

    /**

     * Sends a MIDI event to the receiver.

     * @param event event to send.

     * @throws IllegalStateException if the receiver is not open.

     */

    //  public void send(MidiEvent event) throws IllegalStateException {

    //

    //  }

    /**

     * Obtains the set of controls supported by the

     * element.  If no controls are supported, returns an

     * array of length 0.

     * @return set of controls

     */

    // $$kk: 03.04.99: josh bloch recommends getting rid of this:

    // what can you really do with a set of untyped controls??

    // $$kk: 03.05.99: i am putting this back in.  for one thing,

    // you can check the length and know whether you should keep

    // looking....

    // public Control[] getControls();

    /**

     * Obtains the specified control.

     * @param controlClass class of the requested control

     * @return requested control object, or null if the

     * control is not supported.

     */

    // public Control getControl(Class controlClass);

}