1 package net.sf.jack4j;
2
3 /*
4 Copyright (C) 2008 Ondrej Par
5
6 This program is free software; you can redistribute it and/or modify
7 it under the terms of the GNU Lesser General Public License as published by
8 the Free Software Foundation; either version 2.1 of the License, or
9 (at your option) any later version.
10
11 This program is distributed in the hope that it will be useful,
12 but WITHOUT ANY WARRANTY; without even the implied warranty of
13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 GNU Lesser General Public License for more details.
15
16 You should have received a copy of the GNU Lesser General Public License
17 along with this program; if not, write to the Free Software
18 Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
19
20 */
21
22 /**
23 * MIDI buffer for {@link JackLocalMidiPort}.
24 *
25 * <p>
26 * The instance may be obtained with
27 * {@link JackLocalMidiPort#initializeMidiBuffer(int)}, and is only valid
28 * <b>during the current process cycle</b>.
29 */
30 public class JackMidiPortBuffer {
31
32 private long bufferPointer;
33
34 public JackMidiPortBuffer(long bufferPointer) {
35 this.bufferPointer = bufferPointer;
36 }
37
38 /**
39 * Native pointer to buffer data.
40 *
41 * <p>
42 * The pointer is packed as <code>long</code> value.
43 */
44 public long getBufferPointer() {
45 return bufferPointer;
46 }
47
48 /**
49 * To be used solely by {@link JackLocalMidiPort}.
50 */
51 void setBufferPointer(long bufferPointer) {
52 this.bufferPointer = bufferPointer;
53 }
54
55 /**
56 * Returns current number of MIDI events in the buffer.
57 */
58 public native int getEventCount();
59
60 /**
61 * Returns MIDI event from the (input) buffer.
62 *
63 * @param index
64 * event number, must be non-negative and lower than
65 * {@link #getEventCount()}
66 * @return the event
67 * @throws JackException
68 * if native Jack API fails
69 */
70 public native JackMidiEvent getEvent(int index) throws JackException;
71
72 /**
73 * Clears an event buffer.
74 *
75 * <p>
76 * May be called only during client's process callback.
77 *
78 * <p>
79 * This should be called at the beginning of each process cycle before
80 * calling {@link #eventReserve(int, int)} or
81 * {@link #eventWrite(int, byte[])}. This function may not be called on an
82 * input port.
83 */
84 public native void clearBuffer();
85
86 /**
87 * Allocate space for an event to be written to an event port buffer.
88 *
89 * <p>
90 * May be called only during client's process callback.
91 *
92 * <p>
93 * There's probably no good reason to use this method in Java; use
94 * {@link #eventWrite(int, byte[])} instead.
95 *
96 * <p>
97 * The returned value is a native pointer of type
98 * <code>jack_midi_data_t*</code>. packed as long.
99 *
100 * <p>
101 * Clients are to write the actual event data to be written starting at the
102 * pointer returned by this function. Clients must not write more than
103 * dataSize bytes into this buffer. Clients must write normalized MIDI data
104 * to the port - no running status and no (1-byte) realtime messages
105 * interspersed with other messages (realtime messages are fine when they
106 * occur on their own, like other messages).
107 *
108 * @param time
109 * sample offset of the event (number of frames since cycle
110 * start)
111 * @param dataSize
112 * length of event's raw data in bytes
113 * @return <code>jack_midi_data_t*</code> packed as long
114 * @throws JackException
115 * if the error occurrs (native function
116 * <code>jack_midi_event_reserve</code> returns NULL)
117 */
118 public native long eventReserve(int time, int dataSize) throws JackException;
119
120 /**
121 * Write an event into an event port buffer.
122 *
123 * <p>
124 * May be called only during client's process callback.
125 *
126 * <p>
127 * The <code>data</code> must be normalized MIDI data - no running status
128 * and no (1-byte) realtime messages interspersed with other messages
129 * (realtime messages are fine when they occur on their own, like other
130 * messages).
131 *
132 * @param time
133 * sample offset of the event (number of frames since cycle
134 * start)
135 * @param data
136 * raw MIDI data
137 * @throws JackException
138 * if error occurrs
139 */
140 public native void eventWrite(int time, byte[] data) throws JackException;
141
142 /**
143 * Not for public use, intended for unit tests.
144 *
145 * <p>
146 * Calls {@link #eventReserve(int, int)} and then writes given data to the
147 * reserved space.
148 */
149 native void eventReserveAndWrite(int time, byte[] data) throws JackException;
150
151 /**
152 * Returns the size of the largest event that can be stored by the port.
153 *
154 * <p>
155 * May be called only during client's process callback.
156 */
157 public native int getMaxEventSize();
158
159 /**
160 * Returns the number of events that could not be written to port.
161 */
162 public native int getLostEventsCount();
163
164 }