src/share/classes/javax/sound/midi/Soundbank.java

Print this page

        

*** 1,7 **** /* ! * Copyright (c) 1998, 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 --- 1,7 ---- /* ! * Copyright (c) 1998, 2014, 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
*** 23,133 **** * questions. */ package javax.sound.midi; - import java.net.URL; - - /** ! * A <code>Soundbank</code> contains a set of <code>Instruments</code> ! * that can be loaded into a <code>Synthesizer</code>. ! * Note that a Java Sound <code>Soundbank</code> is different from a MIDI bank. ! * MIDI permits up to 16383 banks, each containing up to 128 instruments ! * (also sometimes called programs, patches, or timbres). ! * However, a <code>Soundbank</code> can contain 16383 times 128 instruments, ! * because the instruments within a <code>Soundbank</code> are indexed by both ! * a MIDI program number and a MIDI bank number (via a <code>Patch</code> ! * object). Thus, a <code>Soundbank</code> can be thought of as a collection ! * of MIDI banks. * <p> ! * <code>Soundbank</code> includes methods that return <code>String</code> ! * objects containing the sound bank's name, manufacturer, version number, and ! * description. The precise content and format of these strings is left ! * to the implementor. * <p> ! * Different synthesizers use a variety of synthesis techniques. A common ! * one is wavetable synthesis, in which a segment of recorded sound is ! * played back, often with looping and pitch change. The Downloadable Sound ! * (DLS) format uses segments of recorded sound, as does the Headspace Engine. ! * <code>Soundbanks</code> and <code>Instruments</code> that are based on ! * wavetable synthesis (or other uses of stored sound recordings) should ! * typically implement the <code>getResources()</code> ! * method to provide access to these recorded segments. This is optional, ! * however; the method can return an zero-length array if the synthesis technique ! * doesn't use sampled sound (FM synthesis and physical modeling are examples ! * of such techniques), or if it does but the implementor chooses not to make the ! * samples accessible. * * @see Synthesizer#getDefaultSoundbank * @see Synthesizer#isSoundbankSupported * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Patch * @see Instrument * @see SoundbankResource - * - * @author David Rivas - * @author Kara Kytle */ - public interface Soundbank { - /** * Obtains the name of the sound bank. ! * @return a <code>String</code> naming the sound bank */ ! public String getName(); /** * Obtains the version string for the sound bank. ! * @return a <code>String</code> that indicates the sound bank's version */ ! public String getVersion(); /** ! * Obtains a <code>string</code> naming the company that provides the ! * sound bank * @return the vendor string */ ! public String getVendor(); /** * Obtains a textual description of the sound bank, suitable for display. ! * @return a <code>String</code> that describes the sound bank */ ! public String getDescription(); ! /** * Extracts a list of non-Instrument resources contained in the sound bank. ! * @return an array of resources, excluding instruments. If the sound bank contains ! * no resources (other than instruments), returns an array of length 0. */ ! public SoundbankResource[] getResources(); ! /** * Obtains a list of instruments contained in this sound bank. - * @return an array of the <code>Instruments</code> in this - * <code>SoundBank</code> - * If the sound bank contains no instruments, returns an array of length 0. * * @see Synthesizer#getLoadedInstruments * @see #getInstrument(Patch) */ ! public Instrument[] getInstruments(); /** ! * Obtains an <code>Instrument</code> from the given <code>Patch</code>. ! * @param patch a <code>Patch</code> object specifying the bank index ! * and program change number ! * @return the requested instrument, or <code>null</code> if the ! * sound bank doesn't contain that instrument * * @see #getInstruments * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ ! public Instrument getInstrument(Patch patch); ! ! } --- 23,125 ---- * questions. */ package javax.sound.midi; /** ! * A {@code Soundbank} contains a set of {@code Instruments} that can be loaded ! * into a {@code Synthesizer}. Note that a Java Sound {@code Soundbank} is ! * different from a MIDI bank. MIDI permits up to 16383 banks, each containing ! * up to 128 instruments (also sometimes called programs, patches, or timbres). ! * However, a {@code Soundbank} can contain 16383 times 128 instruments, because ! * the instruments within a {@code Soundbank} are indexed by both a MIDI program ! * number and a MIDI bank number (via a {@code Patch} object). Thus, a ! * {@code Soundbank} can be thought of as a collection of MIDI banks. * <p> ! * {@code Soundbank} includes methods that return {@code String} objects ! * containing the sound bank's name, manufacturer, version number, and ! * description. The precise content and format of these strings is left to the ! * implementor. * <p> ! * Different synthesizers use a variety of synthesis techniques. A common one is ! * wavetable synthesis, in which a segment of recorded sound is played back, ! * often with looping and pitch change. The Downloadable Sound (DLS) format uses ! * segments of recorded sound, as does the Headspace Engine. {@code Soundbanks} ! * and {@code Instruments} that are based on wavetable synthesis (or other uses ! * of stored sound recordings) should typically implement the ! * {@code getResources()} method to provide access to these recorded segments. ! * This is optional, however; the method can return an zero-length array if the ! * synthesis technique doesn't use sampled sound (FM synthesis and physical ! * modeling are examples of such techniques), or if it does but the implementor ! * chooses not to make the samples accessible. * + * @author David Rivas + * @author Kara Kytle * @see Synthesizer#getDefaultSoundbank * @see Synthesizer#isSoundbankSupported * @see Synthesizer#loadInstruments(Soundbank, Patch[]) * @see Patch * @see Instrument * @see SoundbankResource */ public interface Soundbank { /** * Obtains the name of the sound bank. ! * ! * @return a {@code String} naming the sound bank */ ! String getName(); /** * Obtains the version string for the sound bank. ! * ! * @return a {@code String} that indicates the sound bank's version */ ! String getVersion(); /** ! * Obtains a {@code string} naming the company that provides the sound bank. ! * * @return the vendor string */ ! String getVendor(); /** * Obtains a textual description of the sound bank, suitable for display. ! * ! * @return a {@code String} that describes the sound bank */ ! String getDescription(); /** * Extracts a list of non-Instrument resources contained in the sound bank. ! * ! * @return an array of resources, excluding instruments. If the sound bank ! * contains no resources (other than instruments), returns an array ! * of length 0. */ ! SoundbankResource[] getResources(); /** * Obtains a list of instruments contained in this sound bank. * + * @return an array of the {@code Instruments} in this {@code SoundBank}. If + * the sound bank contains no instruments, returns an array of + * length 0. * @see Synthesizer#getLoadedInstruments * @see #getInstrument(Patch) */ ! Instrument[] getInstruments(); /** ! * Obtains an {@code Instrument} from the given {@code Patch}. * + * @param patch a {@code Patch} object specifying the bank index and + * program change number + * @return the requested instrument, or {@code null} if the sound bank + * doesn't contain that instrument * @see #getInstruments * @see Synthesizer#loadInstruments(Soundbank, Patch[]) */ ! Instrument getInstrument(Patch patch); }