1 /*
   2  * Copyright (c) 1999, 2004, Oracle and/or its affiliates. All rights reserved.
   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
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  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  *
  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.
  24  */
  25 
  26 package javax.sound.midi;
  27 
  28 /**
  29  * A <code>SoundbankResource</code> represents any audio resource stored
  30  * in a <code>{@link Soundbank}</code>.  Common soundbank resources include:
  31  * <ul>
  32  * <li>Instruments.  An instrument may be specified in a variety of
  33  * ways.  However, all soundbanks have some mechanism for defining
  34  * instruments.  In doing so, they may reference other resources
  35  * stored in the soundbank.  Each instrument has a <code>Patch</code>
  36  * which specifies the MIDI program and bank by which it may be
  37  * referenced in MIDI messages.  Instrument information may be
  38  * stored in <code>{@link Instrument}</code> objects.
  39  * <li>Audio samples.  A sample typically is a sampled audio waveform
  40  * which contains a short sound recording whose duration is a fraction of
  41  * a second, or at most a few seconds.  These audio samples may be
  42  * used by a <code>{@link Synthesizer}</code> to synthesize sound in response to MIDI
  43  * commands, or extracted for use by an application.
  44  * (The terminology reflects musicians' use of the word "sample" to refer
  45  * collectively to a series of contiguous audio samples or frames, rather than
  46  * to a single, instantaneous sample.)
  47  * The data class for an audio sample will be an object
  48  * that encapsulates the audio sample data itself and information
  49  * about how to interpret it (the format of the audio data), such
  50  * as an <code>{@link javax.sound.sampled.AudioInputStream}</code>.     </li>
  51  * <li>Embedded sequences.  A sound bank may contain built-in
  52  * song data stored in a data object such as a <code>{@link Sequence}</code>.
  53  * </ul>
  54  * <p>
  55  * Synthesizers that use wavetable synthesis or related
  56  * techniques play back the audio in a sample when
  57  * synthesizing notes, often when emulating the real-world instrument that
  58  * was originally recorded.  However, there is not necessarily a one-to-one
  59  * correspondence between the <code>Instruments</code> and samples
  60  * in a <code>Soundbank</code>.  A single <code>Instrument</code> can use
  61  * multiple SoundbankResources (typically for notes of dissimilar pitch or
  62  * brightness).  Also, more than one <code>Instrument</code> can use the same
  63  * sample.
  64  *
  65  * @author Kara Kytle
  66  */
  67 
  68 public abstract class SoundbankResource {
  69 
  70 
  71     /**
  72      * The sound bank that contains the <code>SoundbankResources</code>
  73      */
  74     private final Soundbank soundBank;
  75 
  76 
  77     /**
  78      * The name of the <code>SoundbankResource</code>
  79      */
  80     private final String name;
  81 
  82 
  83     /**
  84      * The class used to represent the sample's data.
  85      */
  86     private final Class dataClass;
  87 
  88 
  89     /**
  90      * The wavetable index.
  91      */
  92     //private final int index;
  93 
  94 
  95     /**
  96      * Constructs a new <code>SoundbankResource</code> from the given sound bank
  97      * and wavetable index.  (Setting the <code>SoundbankResource's</code> name,
  98      * sampled audio data, and instruments is a subclass responsibility.)
  99      * @param soundBank the sound bank containing this <code>SoundbankResource</code>
 100      * @param name the name of the sample
 101      * @param dataClass the class used to represent the sample's data
 102      *
 103      * @see #getSoundbank
 104      * @see #getName
 105      * @see #getDataClass
 106      * @see #getData
 107      */
 108     protected SoundbankResource(Soundbank soundBank, String name, Class<?> dataClass) {
 109 
 110         this.soundBank = soundBank;
 111         this.name = name;
 112         this.dataClass = dataClass;
 113     }
 114 
 115 
 116     /**
 117      * Obtains the sound bank that contains this <code>SoundbankResource</code>.
 118      * @return the sound bank in which this <code>SoundbankResource</code> is stored
 119      */
 120     public Soundbank getSoundbank() {
 121         return soundBank;
 122     }
 123 
 124 
 125     /**
 126      * Obtains the name of the resource.  This should generally be a string
 127      * descriptive of the resource.
 128      * @return the instrument's name
 129      */
 130     public String getName() {
 131         return name;
 132     }
 133 
 134 
 135     /**
 136      * Obtains the class used by this sample to represent its data.
 137      * The object returned by <code>getData</code> will be of this
 138      * class.  If this <code>SoundbankResource</code> object does not support
 139      * direct access to its data, returns <code>null</code>.
 140      * @return the class used to represent the sample's data, or
 141      * null if the data is not accessible
 142      */
 143     public Class<?> getDataClass() {
 144         return dataClass;
 145     }
 146 
 147 
 148     /**
 149      * Obtains the sampled audio that is stored in this <code>SoundbankResource</code>.
 150      * The type of object returned depends on the implementation of the
 151      * concrete class, and may be queried using <code>getDataClass</code>.
 152      * @return an object containing the sampled audio data
 153      * @see #getDataClass
 154      */
 155     public abstract Object getData();
 156 
 157 
 158     /**
 159      * Obtains the index of this <code>SoundbankResource</code> into the
 160      * <code>Soundbank's</code> set of <code>SoundbankResources</code>.
 161      * @return the wavetable index
 162      */
 163     //public int getIndex() {
 164     //  return index;
 165     //}
 166 
 167 
 168     /**
 169      * Obtains a list of the instruments in the sound bank that use the
 170      * <code>SoundbankResource</code> for sound synthesis.
 171      * @return an array of <code>Instruments</code> that reference this
 172      * <code>SoundbankResource</code>
 173      *
 174      * @see Instrument#getSamples
 175      */
 176     //public abstract Instrument[] getInstruments();
 177 }
--- EOF ---