$Header: /MidiComp/Midiin.pas 2 10/06/97 7:33 Davec $ } { Written by David Churcher ,
released to the public domain. TMidiInput - -------------------------------------------------------------------
Register - -------------------------------------------------------------------
MidiInputState
procedure Register;
-------------------------------------------------------------------
MidiInputState = (misOpen, misClosed, misCreating, misDestroying);
Properties:
DeviceID: Windows numeric device ID for the MIDI input device.
Between 0 and NumDevs-1.
Read-only while device is open, exception when changed while open
MIDIHandle: The input handle to the MIDI device.
0 when device is not open
Read-only, runtime-only
MessageCount: Number of input messages waiting in input buffer
Capacity: Number of messages input buffer can hold
Defaults to 1024
Limited to (64K/event size)
Read-only when device is open (exception when changed while open)
SysexBufferSize: Size in bytes of each sysex buffer
Defaults to 10K
Minimum 0K (no buffers), Maximum 64K-1
SysexBufferCount: Number of sysex buffers
Defaults to 16
Minimum 0 (no buffers), Maximum (avail mem/SysexBufferSize)
Check where these buffers are allocated?
SysexOnly: True to ignore all non-sysex input events. May be changed while
device is open. Handy for patch editors where you have lots of short MIDI
events on the wire which you are always going to ignore anyway.
DriverVersion: Version number of MIDI device driver. High-order byte is
major version, low-order byte is minor version.
ProductName: Name of product (e.g. 'MPU 401 In')
MID and PID: Manufacturer ID and Product ID, see
"Manufacturer and Product IDs" in MMSYSTEM.HLP for list of possible values.
Methods:
GetMidiEvent: Read Midi event at the head of the FIFO input buffer.
Returns a TMyMidiEvent object containing MIDI message data, timestamp,
and sysex data if applicable.
This method automatically removes the event from the input buffer.
It makes a copy of the received sysex buffer and puts the buffer back
on the input device.
The TMyMidiEvent object must be freed by calling MyMidiEvent.Free.
Open: Opens device. Note no input will appear until you call the Start
method.
Close: Closes device. Any pending system exclusive output will be cancelled.
Start: Starts receiving MIDI input.
Stop: Stops receiving MIDI input.
Events:
OnMidiInput: Called when MIDI input data arrives. Use the GetMidiEvent to
get the MIDI input data.
OnOverflow: Called if the MIDI input buffer overflows. The caller must
clear the buffer before any more MIDI input can be received.
Notes:
Buffering: Uses a circular buffer, separate pointers for next location
to fill and next location to empty because a MIDI input interrupt may
be adding data to the buffer while the buffer is being read. Buffer
pointers wrap around from end to start of buffer automatically. If
buffer overflows then the OnBufferOverflow event is triggered and no
further input will be received until the buffer is emptied by calls
to GetMidiEvent.
Sysex buffers: There are (SysexBufferCount) buffers on the input device.
When sysex events arrive these buffers are removed from the input device and
added to the circular buffer by the interrupt handler in the DLL. When the sysex events
are removed from the circular buffer by the GetMidiEvent method the buffers are
put back on the input. If all the buffers are used up there will be no
more sysex input until at least one sysex event is removed from the input buffer.
In other words if you're expecting lots of sysex input you need to set the
SysexBufferCount property high enough so that you won't run out of
input buffers before you get a chance to read them with GetMidiEvent.
If the synth sends a block of sysex that's longer than SysexBufferSize it
will be received as separate events.
TODO: Component derived from this one that handles >64K sysex blocks cleanly
and can stream them to disk.
Midi Time Code (MTC) and Active Sensing: The DLL is currently hardcoded
to filter these short events out, so that we don't spend all our time
processing them.
TODO: implement a filter property to select the events that will be filtered
out.