author | ddehaven |
Tue, 19 Aug 2014 10:32:16 -0700 | |
changeset 26037 | 508779ce6619 |
parent 26003 | jdk/src/share/classes/javax/sound/midi/Synthesizer.java@d630c97424bd |
parent 25859 | jdk/src/share/classes/javax/sound/midi/Synthesizer.java@3317bb8137f4 |
child 32871 | f013b86386e6 |
permissions | -rw-r--r-- |
2 | 1 |
/* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
2 |
* Copyright (c) 1999, 2014, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package javax.sound.midi; |
|
27 |
||
28 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
29 |
* A {@code Synthesizer} generates sound. This usually happens when one of the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
30 |
* {@code Synthesizer}'s {@link MidiChannel} objects receives a |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
31 |
* {@link MidiChannel#noteOn(int, int) noteOn} message, either directly or via |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
32 |
* the {@code Synthesizer} object. Many {@code Synthesizer}s support |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
33 |
* {@code Receivers}, through which MIDI events can be delivered to the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
34 |
* {@code Synthesizer}. In such cases, the {@code Synthesizer} typically |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
35 |
* responds by sending a corresponding message to the appropriate |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
36 |
* {@code MidiChannel}, or by processing the event itself if the event isn't one |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
37 |
* of the MIDI channel messages. |
2 | 38 |
* <p> |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
39 |
* The {@code Synthesizer} interface includes methods for loading and unloading |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
40 |
* instruments from soundbanks. An instrument is a specification for |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
41 |
* synthesizing a certain type of sound, whether that sound emulates a |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
42 |
* traditional instrument or is some kind of sound effect or other imaginary |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
43 |
* sound. A soundbank is a collection of instruments, organized by bank and |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
44 |
* program number (via the instrument's {@code Patch} object). Different |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
45 |
* {@code Synthesizer} classes might implement different sound-synthesis |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
46 |
* techniques, meaning that some instruments and not others might be compatible |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
47 |
* with a given synthesizer. Also, synthesizers may have a limited amount of |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
48 |
* memory for instruments, meaning that not every soundbank and instrument can |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
49 |
* be used by every synthesizer, even if the synthesis technique is compatible. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
50 |
* To see whether the instruments from a certain soundbank can be played by a |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
51 |
* given synthesizer, invoke the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
52 |
* {@link #isSoundbankSupported(Soundbank) isSoundbankSupported} |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
53 |
* method of {@code Synthesizer}. |
2 | 54 |
* <p> |
55 |
* "Loading" an instrument means that that instrument becomes available for |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
56 |
* synthesizing notes. The instrument is loaded into the bank and program |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
57 |
* location specified by its {@code Patch} object. Loading does not necessarily |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
58 |
* mean that subsequently played notes will immediately have the sound of this |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
59 |
* newly loaded instrument. For the instrument to play notes, one of the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
60 |
* synthesizer's {@code MidiChannel} objects must receive (or have received) a |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
61 |
* program-change message that causes that particular instrument's bank and |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
62 |
* program number to be selected. |
2 | 63 |
* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
64 |
* @author Kara Kytle |
2 | 65 |
* @see MidiSystem#getSynthesizer |
66 |
* @see Soundbank |
|
67 |
* @see Instrument |
|
68 |
* @see MidiChannel#programChange(int, int) |
|
69 |
* @see Receiver |
|
70 |
* @see Transmitter |
|
71 |
* @see MidiDevice |
|
72 |
*/ |
|
73 |
public interface Synthesizer extends MidiDevice { |
|
74 |
||
75 |
// SYNTHESIZER METHODS |
|
76 |
||
77 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
78 |
* Obtains the maximum number of notes that this synthesizer can sound |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
79 |
* simultaneously. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
80 |
* |
2 | 81 |
* @return the maximum number of simultaneous notes |
82 |
* @see #getVoiceStatus |
|
83 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
84 |
int getMaxPolyphony(); |
2 | 85 |
|
86 |
/** |
|
87 |
* Obtains the processing latency incurred by this synthesizer, expressed in |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
88 |
* microseconds. This latency measures the worst-case delay between the time |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
89 |
* a MIDI message is delivered to the synthesizer and the time that the |
2 | 90 |
* synthesizer actually produces the corresponding result. |
91 |
* <p> |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
92 |
* Although the latency is expressed in microseconds, a synthesizer's actual |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
93 |
* measured delay may vary over a wider range than this resolution suggests. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
94 |
* For example, a synthesizer might have a worst-case delay of a few |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
95 |
* milliseconds or more. |
2 | 96 |
* |
97 |
* @return the worst-case delay, in microseconds |
|
98 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
99 |
long getLatency(); |
2 | 100 |
|
101 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
102 |
* Obtains the set of MIDI channels controlled by this synthesizer. Each |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
103 |
* non-null element in the returned array is a {@code MidiChannel} that |
2 | 104 |
* receives the MIDI messages sent on that channel number. |
105 |
* <p> |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
106 |
* The MIDI 1.0 specification provides for 16 channels, so this method |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
107 |
* returns an array of at least 16 elements. However, if this synthesizer |
2 | 108 |
* doesn't make use of all 16 channels, some of the elements of the array |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
109 |
* might be {@code null}, so you should check each element before using it. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
110 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
111 |
* @return an array of the {@code MidiChannel} objects managed by this |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
112 |
* {@code Synthesizer}. Some of the array elements may be |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
113 |
* {@code null}. |
2 | 114 |
*/ |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
115 |
MidiChannel[] getChannels(); |
2 | 116 |
|
117 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
118 |
* Obtains the current status of the voices produced by this synthesizer. If |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
119 |
* this class of {@code Synthesizer} does not provide voice information, the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
120 |
* returned array will always be of length 0. Otherwise, its length is |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
121 |
* always equal to the total number of voices, as returned by |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
122 |
* {@code getMaxPolyphony()}. (See the {@code VoiceStatus} class description |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
123 |
* for an explanation of synthesizer voices.) |
2 | 124 |
* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
125 |
* @return an array of {@code VoiceStatus} objects that supply information |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
126 |
* about the corresponding synthesizer voices |
2 | 127 |
* @see #getMaxPolyphony |
128 |
* @see VoiceStatus |
|
129 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
130 |
VoiceStatus[] getVoiceStatus(); |
2 | 131 |
|
132 |
/** |
|
133 |
* Informs the caller whether this synthesizer is capable of loading |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
134 |
* instruments from the specified soundbank. If the soundbank is |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
135 |
* unsupported, any attempts to load instruments from it will result in an |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
136 |
* {@code IllegalArgumentException}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
137 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
138 |
* @param soundbank soundbank for which support is queried |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
139 |
* @return {@code true} if the soundbank is supported, otherwise |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
140 |
* {@code false} |
2 | 141 |
* @see #loadInstruments |
142 |
* @see #loadAllInstruments |
|
143 |
* @see #unloadInstruments |
|
144 |
* @see #unloadAllInstruments |
|
145 |
* @see #getDefaultSoundbank |
|
146 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
147 |
boolean isSoundbankSupported(Soundbank soundbank); |
2 | 148 |
|
149 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
150 |
* Makes a particular instrument available for synthesis. This instrument is |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
151 |
* loaded into the patch location specified by its {@code Patch} object, so |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
152 |
* that if a program-change message is received (or has been received) that |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
153 |
* causes that patch to be selected, subsequent notes will be played using |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
154 |
* the sound of {@code instrument}. If the specified instrument is already |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
155 |
* loaded, this method does nothing and returns {@code true}. |
2 | 156 |
* <p> |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
157 |
* The instrument must be part of a soundbank that this {@code Synthesizer} |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
158 |
* supports. (To make sure, you can use the {@code getSoundbank} method of |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
159 |
* {@code Instrument} and the {@code isSoundbankSupported} method of |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
160 |
* {@code Synthesizer}.) |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
161 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
162 |
* @param instrument instrument to load |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
163 |
* @return {@code true} if the instrument is successfully loaded (or already |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
164 |
* had been), {@code false} if the instrument could not be loaded |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
165 |
* (for example, if the synthesizer has insufficient memory to load |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
166 |
* it) |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
167 |
* @throws IllegalArgumentException if this {@code Synthesizer} doesn't |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
168 |
* support the specified instrument's soundbank |
2 | 169 |
* @see #unloadInstrument |
170 |
* @see #loadInstruments |
|
171 |
* @see #loadAllInstruments |
|
172 |
* @see #remapInstrument |
|
173 |
* @see SoundbankResource#getSoundbank |
|
174 |
* @see MidiChannel#programChange(int, int) |
|
175 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
176 |
boolean loadInstrument(Instrument instrument); |
2 | 177 |
|
178 |
/** |
|
179 |
* Unloads a particular instrument. |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
180 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
181 |
* @param instrument instrument to unload |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
182 |
* @throws IllegalArgumentException if this {@code Synthesizer} doesn't |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
183 |
* support the specified instrument's soundbank |
2 | 184 |
* @see #loadInstrument |
185 |
* @see #unloadInstruments |
|
186 |
* @see #unloadAllInstruments |
|
187 |
* @see #getLoadedInstruments |
|
188 |
* @see #remapInstrument |
|
189 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
190 |
void unloadInstrument(Instrument instrument); |
2 | 191 |
|
192 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
193 |
* Remaps an instrument. Instrument {@code to} takes the place of instrument |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
194 |
* {@code from}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
195 |
* <br> |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
196 |
* For example, if {@code from} was located at bank number 2, program number |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
197 |
* 11, remapping causes that bank and program location to be occupied |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
198 |
* instead by {@code to}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
199 |
* <br> |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
200 |
* If the function succeeds, instrument {@code from} is unloaded. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
201 |
* <p> |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
202 |
* To cancel the remapping reload instrument {@code from} by invoking one of |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
203 |
* {@link #loadInstrument}, {@link #loadInstruments} or |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
204 |
* {@link #loadAllInstruments}. |
2 | 205 |
* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
206 |
* @param from the {@code Instrument} object to be replaced |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
207 |
* @param to the {@code Instrument} object to be used in place of the old |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
208 |
* instrument, it should be loaded into the synthesizer |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
209 |
* @return {@code true} if the instrument successfully remapped, |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
210 |
* {@code false} if feature is not implemented by synthesizer |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
211 |
* @throws IllegalArgumentException if instrument {@code from} or instrument |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
212 |
* {@code to} aren't supported by synthesizer or if instrument |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
213 |
* {@code to} is not loaded |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
214 |
* @throws NullPointerException if {@code from} or {@code to} parameters |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
215 |
* have null value |
2 | 216 |
* @see #loadInstrument |
217 |
* @see #loadInstruments |
|
218 |
* @see #loadAllInstruments |
|
219 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
220 |
boolean remapInstrument(Instrument from, Instrument to); |
2 | 221 |
|
222 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
223 |
* Obtains the default soundbank for the synthesizer, if one exists. (Some |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
224 |
* synthesizers provide a default or built-in soundbank.) If a synthesizer |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
225 |
* doesn't have a default soundbank, instruments must be loaded explicitly |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
226 |
* from an external soundbank. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
227 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
228 |
* @return default soundbank, or {@code null} if one does not exist |
2 | 229 |
* @see #isSoundbankSupported |
230 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
231 |
Soundbank getDefaultSoundbank(); |
2 | 232 |
|
233 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
234 |
* Obtains a list of instruments that come with the synthesizer. These |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
235 |
* instruments might be built into the synthesizer, or they might be part of |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
236 |
* a default soundbank provided with the synthesizer, etc. |
2 | 237 |
* <p> |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
238 |
* Note that you don't use this method to find out which instruments are |
2 | 239 |
* currently loaded onto the synthesizer; for that purpose, you use |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
240 |
* {@code getLoadedInstruments()}. Nor does the method indicate all the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
241 |
* instruments that can be loaded onto the synthesizer; it only indicates |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
242 |
* the subset that come with the synthesizer. To learn whether another |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
243 |
* instrument can be loaded, you can invoke {@code isSoundbankSupported()}, |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
244 |
* and if the instrument's {@code Soundbank} is supported, you can try |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
245 |
* loading the instrument. |
2 | 246 |
* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
247 |
* @return list of available instruments. If the synthesizer has no |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
248 |
* instruments coming with it, an array of length 0 is returned. |
2 | 249 |
* @see #getLoadedInstruments |
250 |
* @see #isSoundbankSupported(Soundbank) |
|
251 |
* @see #loadInstrument |
|
252 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
253 |
Instrument[] getAvailableInstruments(); |
2 | 254 |
|
255 |
/** |
|
256 |
* Obtains a list of the instruments that are currently loaded onto this |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
257 |
* {@code Synthesizer}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
258 |
* |
2 | 259 |
* @return a list of currently loaded instruments |
260 |
* @see #loadInstrument |
|
261 |
* @see #getAvailableInstruments |
|
262 |
* @see Soundbank#getInstruments |
|
263 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
264 |
Instrument[] getLoadedInstruments(); |
2 | 265 |
|
266 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
267 |
* Loads onto the {@code Synthesizer} all instruments contained in the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
268 |
* specified {@code Soundbank}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
269 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
270 |
* @param soundbank the {@code Soundbank} whose are instruments are to be |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
271 |
* loaded |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
272 |
* @return {@code true} if the instruments are all successfully loaded (or |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
273 |
* already had been), {@code false} if any instrument could not be |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
274 |
* loaded (for example, if the {@code Synthesizer} had insufficient |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
275 |
* memory) |
2 | 276 |
* @throws IllegalArgumentException if the requested soundbank is |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
277 |
* incompatible with this synthesizer |
2 | 278 |
* @see #isSoundbankSupported |
279 |
* @see #loadInstrument |
|
280 |
* @see #loadInstruments |
|
281 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
282 |
boolean loadAllInstruments(Soundbank soundbank); |
2 | 283 |
|
284 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
285 |
* Unloads all instruments contained in the specified {@code Soundbank}. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
286 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
287 |
* @param soundbank soundbank containing instruments to unload |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
288 |
* @throws IllegalArgumentException thrown if the soundbank is not supported |
2 | 289 |
* @see #isSoundbankSupported |
290 |
* @see #unloadInstrument |
|
291 |
* @see #unloadInstruments |
|
292 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
293 |
void unloadAllInstruments(Soundbank soundbank); |
2 | 294 |
|
295 |
/** |
|
296 |
* Loads the instruments referenced by the specified patches, from the |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
297 |
* specified {@code Soundbank}. Each of the {@code Patch} objects indicates |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
298 |
* a bank and program number; the {@code Instrument} that has the matching |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
299 |
* {@code Patch} is loaded into that bank and program location. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
300 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
301 |
* @param soundbank the {@code Soundbank} containing the instruments to |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
302 |
* load |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
303 |
* @param patchList list of patches for which instruments should be loaded |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
304 |
* @return {@code true} if the instruments are all successfully loaded (or |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
305 |
* already had been), {@code false} if any instrument could not be |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
306 |
* loaded (for example, if the {@code Synthesizer} had insufficient |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
307 |
* memory) |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
308 |
* @throws IllegalArgumentException thrown if the soundbank is not supported |
2 | 309 |
* @see #isSoundbankSupported |
310 |
* @see Instrument#getPatch |
|
311 |
* @see #loadAllInstruments |
|
312 |
* @see #loadInstrument |
|
313 |
* @see Soundbank#getInstrument(Patch) |
|
314 |
* @see Sequence#getPatchList() |
|
315 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
316 |
boolean loadInstruments(Soundbank soundbank, Patch[] patchList); |
2 | 317 |
|
318 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
319 |
* Unloads the instruments referenced by the specified patches, from the |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
320 |
* MIDI sound bank specified. |
2 | 321 |
* |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
322 |
* @param soundbank soundbank containing instruments to unload |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
323 |
* @param patchList list of patches for which instruments should be |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
324 |
* unloaded |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
325 |
* @throws IllegalArgumentException thrown if the soundbank is not supported |
2 | 326 |
* @see #unloadInstrument |
327 |
* @see #unloadAllInstruments |
|
328 |
* @see #isSoundbankSupported |
|
329 |
* @see Instrument#getPatch |
|
330 |
* @see #loadInstruments |
|
331 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
332 |
void unloadInstruments(Soundbank soundbank, Patch[] patchList); |
2 | 333 |
|
334 |
// RECEIVER METHODS |
|
335 |
||
336 |
/** |
|
337 |
* Obtains the name of the receiver. |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
338 |
* |
2 | 339 |
* @return receiver name |
340 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
341 |
// abstract String getName(); |
2 | 342 |
|
343 |
/** |
|
344 |
* Opens the receiver. |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
345 |
* |
2 | 346 |
* @throws MidiUnavailableException if the receiver is cannot be opened, |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
347 |
* usually because the MIDI device is in use by another application. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
348 |
* @throws SecurityException if the receiver cannot be opened due to |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
349 |
* security restrictions |
2 | 350 |
*/ |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
351 |
// abstract void open() throws MidiUnavailableException, SecurityException; |
2 | 352 |
|
353 |
/** |
|
354 |
* Closes the receiver. |
|
355 |
*/ |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
356 |
// abstract void close(); |
2 | 357 |
|
358 |
/** |
|
359 |
* Sends a MIDI event to the receiver. |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
360 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
361 |
* @param event event to send |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
362 |
* @throws IllegalStateException if the receiver is not open |
2 | 363 |
*/ |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
364 |
// void send(MidiEvent event) throws IllegalStateException { |
2 | 365 |
// |
366 |
// } |
|
367 |
||
368 |
/** |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
369 |
* Obtains the set of controls supported by the element. If no controls are |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
370 |
* supported, returns an array of length 0. |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
371 |
* |
2 | 372 |
* @return set of controls |
373 |
*/ |
|
374 |
// $$kk: 03.04.99: josh bloch recommends getting rid of this: |
|
375 |
// what can you really do with a set of untyped controls?? |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
376 |
// $$kk: 03.05.99: i am putting this back in. for one thing, |
2 | 377 |
// you can check the length and know whether you should keep |
378 |
// looking.... |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
379 |
// Control[] getControls(); |
2 | 380 |
|
381 |
/** |
|
382 |
* Obtains the specified control. |
|
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
383 |
* |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
384 |
* @param controlClass class of the requested control |
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
385 |
* @return requested control object, or null if the control is not supported |
2 | 386 |
*/ |
26003
d630c97424bd
8050852: Javadoc cleanup of javax.sound.midi package
serb
parents:
21278
diff
changeset
|
387 |
// Control getControl(Class controlClass); |
2 | 388 |
} |