View Javadoc
1   /*
2    * Copyright (c) 1999, 2002, 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  /**
30   * A <code>Patch</code> object represents a location, on a MIDI
31   * synthesizer, into which a single instrument is stored (loaded).
32   * Every <code>Instrument</code> object has its own <code>Patch</code>
33   * object that specifies the memory location
34   * into which that instrument should be loaded. The
35   * location is specified abstractly by a bank index and a program number (not by
36   * any scheme that directly refers to a specific address or offset in RAM).
37   * This is a hierarchical indexing scheme: MIDI provides for up to 16384 banks,
38   * each of which contains up to 128 program locations.  For example, a
39   * minimal sort of synthesizer might have only one bank of instruments, and
40   * only 32 instruments (programs) in that bank.
41   * <p>
42   * To select what instrument should play the notes on a particular MIDI
43   * channel, two kinds of MIDI message are used that specify a patch location:
44   * a bank-select command, and a program-change channel command.  The Java Sound
45   * equivalent is the
46   * {@link MidiChannel#programChange(int, int) programChange(int, int)}
47   * method of <code>MidiChannel</code>.
48   *
49   * @see Instrument
50   * @see Instrument#getPatch()
51   * @see MidiChannel#programChange(int, int)
52   * @see Synthesizer#loadInstruments(Soundbank, Patch[])
53   * @see Soundbank
54   * @see Sequence#getPatchList()
55   *
56   * @author Kara Kytle
57   */
58  
59  public class Patch {
60  
61  
62      /**
63       * Bank index
64       */
65      private final int bank;
66  
67  
68      /**
69       * Program change number
70       */
71      private final int program;
72  
73  
74      /**
75       * Constructs a new patch object from the specified bank and program
76       * numbers.
77       * @param bank the bank index (in the range from 0 to 16383)
78       * @param program the program index (in the range from 0 to 127)
79       */
80      public Patch(int bank, int program) {
81  
82          this.bank = bank;
83          this.program = program;
84      }
85  
86  
87      /**
88       * Returns the number of the bank that contains the instrument
89       * whose location this <code>Patch</code> specifies.
90       * @return the bank number, whose range is from 0 to 16383
91       * @see MidiChannel#programChange(int, int)
92       */
93      public int getBank() {
94  
95          return bank;
96      }
97  
98  
99      /**
100      * Returns the index, within
101      * a bank, of the instrument whose location this <code>Patch</code> specifies.
102      * @return the instrument's program number, whose range is from 0 to 127
103      *
104      * @see MidiChannel#getProgram
105      * @see MidiChannel#programChange(int)
106      * @see MidiChannel#programChange(int, int)
107      */
108     public int getProgram() {
109 
110         return program;
111     }
112 }