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

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

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

    29  * A {@code Synthesizer} generates sound. This usually happens when one of the

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

    30  * {@code Synthesizer}'s {@link MidiChannel} objects receives a

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

    31  * {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via

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

    32  * the {@code Synthesizer} object. Many {@code Synthesizer}s support

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

    33  * {@code Receivers}, through which MIDI events can be delivered to the

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

    34  * {@code Synthesizer}. In such cases, the {@code Synthesizer} typically

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

    35  * responds by sending a corresponding message to the appropriate

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

    36  * {@code MidiChannel}, or by processing the event itself if the event isn't one

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

    37  * of the MIDI channel messages.

    41  * messages.

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

    39  * The {@code Synthesizer} interface includes methods for loading and unloading

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

    40  * instruments from soundbanks. An instrument is a specification for

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

    41  * synthesizing a certain type of sound, whether that sound emulates a

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

    42  * traditional instrument or is some kind of sound effect or other imaginary

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

    43  * sound. A soundbank is a collection of instruments, organized by bank and

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

    44  * program number (via the instrument's {@code Patch} object). Different

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

    45  * {@code Synthesizer} classes might implement different sound-synthesis

    50  * given synthesizer.

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

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

    47  * with a given synthesizer. Also, synthesizers may have a limited amount of

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

    48  * memory for instruments, meaning that not every soundbank and instrument can

    53  * the synthesis technique is compatible.

    49  * be used by every synthesizer, even if the synthesis technique is compatible.

    54  * To see whether the instruments from

    50  * To see whether the instruments from a certain soundbank can be played by a

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

    51  * given synthesizer, invoke the

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

    52  * {@link #isSoundbankSupported(Soundbank) isSoundbankSupported}

    57  * <code>Synthesizer</code>.

    53  * method of {@code Synthesizer}.

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

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

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

    57  * location specified by its {@code Patch} object. Loading does not necessarily

    62  * not necessarily mean that subsequently played notes will immediately have

    58  * mean that subsequently played notes will immediately have the sound of this

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

    59  * newly loaded instrument. For the instrument to play notes, one of the

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

    60  * synthesizer's {@code MidiChannel} objects must receive (or have received) a

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

    61  * program-change message that causes that particular instrument's bank and

    66  * bank and program number to be selected.

    62  * program number to be selected.

    67  *

    63  *

    64  * @author Kara Kytle

    83 

    77     /**

    84     /**

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

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

    79      * simultaneously.

    80      *

    89     public int getMaxPolyphony();

    84     int getMaxPolyphony();

    90 

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

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

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

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

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

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

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

    93      * measured delay may vary over a wider range than this resolution suggests.

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

    94      * For example, a synthesizer might have a worst-case delay of a few

    95      * milliseconds or more.

   104     public long getLatency();

    99     long getLatency();

   105 

   100 

   106 

   101     /**

   107     /**

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

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

   103      * non-null element in the returned array is a {@code MidiChannel} that

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

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

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

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

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

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

   109      * might be {@code null}, so you should check each element before using it.

   116      * before using it.

   110      *

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

   111      * @return an array of the {@code MidiChannel} objects managed by this

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

   112      *         {@code Synthesizer}. Some of the array elements may be

   119      */

   113      *         {@code null}.

   120     public MidiChannel[] getChannels();

   114      */

   121 

   115     MidiChannel[] getChannels();

   122 

   116 

   123     /**

   117     /**

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

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

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

   119      * this class of {@code Synthesizer} does not provide voice information, the

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

   120      * returned array will always be of length 0. Otherwise, its length is

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

   121      * always equal to the total number of voices, as returned by

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

   122      * {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description

   129      * description for an explanation of synthesizer voices.)

   123      * for an explanation of synthesizer voices.)

   130      *

   124      *

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

   125      * @return an array of {@code VoiceStatus} objects that supply information

   132      * information about the corresponding synthesizer voices

   126      *         about the corresponding synthesizer voices

   136     public VoiceStatus[] getVoiceStatus();

   130     VoiceStatus[] getVoiceStatus();

   137 

   141      * instruments from the specified soundbank.

   134      * instruments from the specified soundbank. If the soundbank is

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

   135      * unsupported, any attempts to load instruments from it will result in an

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

   136      * {@code IllegalArgumentException}.

   144      * @param soundbank soundbank for which support is queried

   137      *

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

   138      * @param  soundbank soundbank for which support is queried

   139      * @return {@code true} if the soundbank is supported, otherwise

   140      *         {@code false}

   152     public boolean isSoundbankSupported(Soundbank soundbank);

   147     boolean isSoundbankSupported(Soundbank soundbank);

   153 

   148 

   154 

   149     /**

   155     /**

   150      * Makes a particular instrument available for synthesis. This instrument is

   156      * Makes a particular instrument available for synthesis.  This instrument

   151      * loaded into the patch location specified by its {@code Patch} object, so

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

   152      * that if a program-change message is received (or has been received) that

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

   153      * causes that patch to be selected, subsequent notes will be played using

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

   154      * the sound of {@code instrument}. If the specified instrument is already

   160      * subsequent notes will be played using the sound of

   155      * loaded, this method does nothing and returns {@code true}.

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

   156      * <p>

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

   157      * The instrument must be part of a soundbank that this {@code Synthesizer}

   163      * <p>

   158      * supports. (To make sure, you can use the {@code getSoundbank} method of

   164      * The instrument must be part of a soundbank

   159      * {@code Instrument} and the {@code isSoundbankSupported} method of

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

   160      * {@code Synthesizer}.)

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

   161      *

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

   162      * @param  instrument instrument to load

   168      * @param instrument instrument to load

   163      * @return {@code true} if the instrument is successfully loaded (or already

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

   164      *         had been), {@code false} if the instrument could not be loaded

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

   165      *         (for example, if the synthesizer has insufficient memory to load

   171      * loaded (for example, if the synthesizer has insufficient

   166      *         it)

   172      * memory to load it)

   167      * @throws IllegalArgumentException if this {@code Synthesizer} doesn't

   173      * @throws IllegalArgumentException if this

   168      *         support the specified instrument's soundbank

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

   175      * soundbank

   183     public boolean loadInstrument(Instrument instrument);

   176     boolean loadInstrument(Instrument instrument);

   184 

   188      * @param instrument instrument to unload

   180      *

   189      * @throws IllegalArgumentException if this

   181      * @param  instrument instrument to unload

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

   182      * @throws IllegalArgumentException if this {@code Synthesizer} doesn't

   191      * soundbank

   183      *         support the specified instrument's soundbank

   198     public void unloadInstrument(Instrument instrument);

   190     void unloadInstrument(Instrument instrument);

   199 

   191 

   200 

   192     /**

   201     /**

   193      * Remaps an instrument. Instrument {@code to} takes the place of instrument

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

   194      * {@code from}.

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

   195      * <br>

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

   196      * For example, if {@code from} was located at bank number 2, program number

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

   197      * 11, remapping causes that bank and program location to be occupied

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

   198      * instead by {@code to}.

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

   199      * <br>

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

   200      * If the function succeeds, instrument {@code from} is unloaded.

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

   201      * <p>

   210      * or {@link #loadAllInstruments}.

   202      * To cancel the remapping reload instrument {@code from} by invoking one of

   211      *

   203      * {@link #loadInstrument}, {@link #loadInstruments} or

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

   204      * {@link #loadAllInstruments}.

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

   205      *

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

   206      * @param  from the {@code Instrument} object to be replaced

   215      * @return <code>true</code> if the instrument successfully remapped,

   207      * @param  to the {@code Instrument} object to be used in place of the old

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

   208      *         instrument, it should be loaded into the synthesizer

   217      * @throws IllegalArgumentException if instrument

   209      * @return {@code true} if the instrument successfully remapped,

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

   210      *         {@code false} if feature is not implemented by synthesizer

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

   211      * @throws IllegalArgumentException if instrument {@code from} or instrument

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

   212      *         {@code to} aren't supported by synthesizer or if instrument

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

   213      *         {@code to} is not loaded

   214      * @throws NullPointerException if {@code from} or {@code to} parameters

   215      *         have null value

   226     public boolean remapInstrument(Instrument from, Instrument to);

   220     boolean remapInstrument(Instrument from, Instrument to);

   227 

   221 

   228 

   222     /**

   229     /**

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

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

   224      * synthesizers provide a default or built-in soundbank.) If a synthesizer

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

   225      * doesn't have a default soundbank, instruments must be loaded explicitly

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

   226      * from an external soundbank.

   233      * be loaded explicitly from an external soundbank.

   227      *

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

   228      * @return default soundbank, or {@code null} if one does not exist

   235      * @see #isSoundbankSupported

   229      * @see #isSoundbankSupported

   236      */

   230      */

   237     public Soundbank getDefaultSoundbank();

   231     Soundbank getDefaultSoundbank();

   238 

   232 

   239 

   233     /**

   240     /**

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

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

   235      * instruments might be built into the synthesizer, or they might be part of

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

   236      * a default soundbank provided with the synthesizer, etc.

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

   237      * <p>

   244      * <p>

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

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

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

   240      * {@code getLoadedInstruments()}. Nor does the method indicate all the

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

   241      * instruments that can be loaded onto the synthesizer; it only indicates

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

   242      * the subset that come with the synthesizer. To learn whether another

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

   243      * instrument can be loaded, you can invoke {@code isSoundbankSupported()},

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

   244      * and if the instrument's {@code Soundbank} is supported, you can try

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

   245      * loading the instrument.

   253      *

   246      *

   254      * @return list of available instruments. If the synthesizer

   247      * @return list of available instruments. If the synthesizer has no

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

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

   260     public Instrument[] getAvailableInstruments();

   253     Instrument[] getAvailableInstruments();

   261 

   265      * <code>Synthesizer</code>.

   257      * {@code Synthesizer}.

   258      *

   271     public Instrument[] getLoadedInstruments();

   264     Instrument[] getLoadedInstruments();

   272 

   265 

   273 

   266     /**

   274     /**

   267      * Loads onto the {@code Synthesizer} all instruments contained in the

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

   268      * specified {@code Soundbank}.

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

   269      *

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

   270      * @param  soundbank the {@code Soundbank} whose are instruments are to be

   278      * to be loaded

   271      *         loaded

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

   272      * @return {@code true} if the instruments are all successfully loaded (or

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

   273      *         already had been), {@code false} if any instrument could not be

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

   274      *         loaded (for example, if the {@code Synthesizer} had insufficient

   275      *         memory)

   283      * incompatible with this synthesizer.

   277      *         incompatible with this synthesizer

   284      * @see #isSoundbankSupported

   278      * @see #isSoundbankSupported

   285      * @see #loadInstrument

   279      * @see #loadInstrument

   286      * @see #loadInstruments

   280      * @see #loadInstruments

   287      */

   281      */

   288     public boolean loadAllInstruments(Soundbank soundbank);

   282     boolean loadAllInstruments(Soundbank soundbank);

   289 

   283 

   290 

   284     /**

   291 

   285      * Unloads all instruments contained in the specified {@code Soundbank}.

   292     /**

   286      *

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

   287      * @param  soundbank soundbank containing instruments to unload

   294      * @param soundbank soundbank containing instruments to unload

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

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

   300     public void unloadAllInstruments(Soundbank soundbank);

   293     void unloadAllInstruments(Soundbank soundbank);

   301 

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

   297      * specified {@code Soundbank}. Each of the {@code Patch} objects indicates

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

   298      * a bank and program number; the {@code Instrument} that has the matching

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

   299      * {@code Patch} is loaded into that bank and program location.

   308      * location.

   300      *

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

   301      * @param  soundbank the {@code Soundbank} containing the instruments to

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

   302      *         load

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

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

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

   304      * @return {@code true} if the instruments are all successfully loaded (or

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

   305      *         already had been), {@code false} if any instrument could not be

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

   306      *         loaded (for example, if the {@code Synthesizer} had insufficient

   307      *         memory)

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

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

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

   323 

   317 

   324     /**

   318     /**

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

   319      * Unloads the instruments referenced by the specified patches, from the

   326      * @param soundbank soundbank containing instruments to unload

   320      * MIDI sound bank specified.

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

   321      *

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

   322      * @param  soundbank soundbank containing instruments to unload

   329      *

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

   324      *         unloaded

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

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

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

   337 

   345     //  public abstract String getName();

   341     //  abstract String getName();

   346 

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

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

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

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

   353      * restrictions.

   349      *         security restrictions

   354      */

   350      */

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

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

   356 

   361     //  public abstract void close();

   356     //  abstract void close();

   362 

   366      * @param event event to send.

   360      *

   367      * @throws IllegalStateException if the receiver is not open.

   361      * @param  event event to send

   368      */

   362      * @throws IllegalStateException if the receiver is not open

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

   363      */

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

   373 

   368     /**

   374     /**

   369      * Obtains the set of controls supported by the element. If no controls are

   375      * Obtains the set of controls supported by the

   370      * supported, returns an array of length 0.

   376      * element.  If no controls are supported, returns an

   371      *

   377      * array of length 0.

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

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

   385     // public Control[] getControls();

   379     // Control[] getControls();

   389      * @param controlClass class of the requested control

   383      *

   390      * @return requested control object, or null if the

   384      * @param  controlClass class of the requested control

   391      * control is not supported.

   385      * @return requested control object, or null if the control is not supported

   392      */

   386      */

   393     // public Control getControl(Class controlClass);

   387     // Control getControl(Class controlClass);