From 90d5b8b4a064420d74678654e94ea4755b377f21 Mon Sep 17 00:00:00 2001 From: Hans-Christoph Steiner Date: Thu, 15 Dec 2005 00:57:02 +0000 Subject: checking in missing files on behalf of Miller (cleared it with him first). The files are from portmidi17nov04.zip svn path=/trunk/; revision=4216 --- pd/portmidi/pm_common/portmidi.h | 692 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 692 insertions(+) create mode 100644 pd/portmidi/pm_common/portmidi.h (limited to 'pd/portmidi/pm_common/portmidi.h') diff --git a/pd/portmidi/pm_common/portmidi.h b/pd/portmidi/pm_common/portmidi.h new file mode 100644 index 00000000..8c9c04c2 --- /dev/null +++ b/pd/portmidi/pm_common/portmidi.h @@ -0,0 +1,692 @@ +#ifndef PORT_MIDI_H +#define PORT_MIDI_H +#ifdef __cplusplus +extern "C" { +#endif /* __cplusplus */ + +/* + * PortMidi Portable Real-Time MIDI Library + * PortMidi API Header File + * Latest version available at: http://www.cs.cmu.edu/~music/portmidi/ + * + * Copyright (c) 1999-2000 Ross Bencina and Phil Burk + * Copyright (c) 2001 Roger B. Dannenberg + * + * Permission is hereby granted, free of charge, to any person obtaining + * a copy of this software and associated documentation files + * (the "Software"), to deal in the Software without restriction, + * including without limitation the rights to use, copy, modify, merge, + * publish, distribute, sublicense, and/or sell copies of the Software, + * and to permit persons to whom the Software is furnished to do so, + * subject to the following conditions: + * + * The above copyright notice and this permission notice shall be + * included in all copies or substantial portions of the Software. + * + * Any person wishing to distribute modifications to the Software is + * requested to send the modifications to the original developer so that + * they can be incorporated into the canonical version. + * + * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, + * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR + * ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF + * CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + * + */ + +/* CHANGELOG FOR PORTMIDI + * + * 15Nov04 Ben Allison + * - sysex output now uses one buffer/message and reallocates buffer + * - if needed + * - filters expanded for many message types and channels + * - detailed changes are as follows: + * ------------- in pmwinmm.c -------------- + * - new #define symbol: OUTPUT_BYTES_PER_BUFFER + * - change SYSEX_BYTES_PER_BUFFER to 1024 + * - added MIDIHDR_BUFFER_LENGTH(x) to correctly count midihdr buffer length + * - change MIDIHDR_SIZE(x) to (MIDIHDR_BUFFER_LENGTH(x) + sizeof(MIDIHDR)) + * - change allocate_buffer to use new MIDIHDR_BUFFER_LENGTH macro + * - new macros for MIDIHDR_SYSEX_SIZE and MIDIHDR_SYSEX_BUFFER_LENGTH + * - similar to above, but counts appropriately for sysex messages + * - added the following members to midiwinmm_struct for sysex data: + * - LPMIDIHDR *sysex_buffers; ** pool of buffers for sysex data ** + * - int num_sysex_buffers; ** how many sysex buffers ** + * - int next_sysex_buffer; ** index of next sysexbuffer to send ** + * - HANDLE sysex_buffer_signal; ** to wait for free sysex buffer ** + * - duplicated allocate_buffer, alocate_buffers and get_free_output_buffer + * - into equivalent sysex_buffer form + * - changed winmm_in_open to initialize new midiwinmm_struct members and + * - to use the new allocate_sysex_buffer() function instead of + * - allocate_buffer() + * - changed winmm_out_open to initialize new members, create sysex buffer + * - signal, and allocate 2 sysex buffers + * - changed winmm_out_delete to free sysex buffers and shut down the sysex + * - buffer signal + * - create new function resize_sysex_buffer which resizes m->hdr to the + * - passed size, and corrects the midiwinmm_struct accordingly. + * - changed winmm_write_byte to use new resize_sysex_buffer function, + * - if resize fails, write current buffer to output and continue + * - changed winmm_out_callback to use buffer_signal or sysex_buffer_signal + * - depending on which buffer was finished + * ------------- in portmidi.h -------------- + * - added pmBufferMaxSize to PmError to indicate that the buffer would be + * - too large for the underlying API + * - added additional filters + * - added prototype, documentation, and helper macro for Pm_SetChannelMask + * ------------- in portmidi.c -------------- + * - added pm_status_filtered() and pm_realtime_filtered() functions to + * separate filtering logic from buffer logic in pm_read_short + * - added Pm_SetChannelMask function + * - added pm_channel_filtered() function + * ------------- in pminternal.h -------------- + * - added member to PortMidiStream for channel mask + * + * 25May04 RBD + * - removed support for MIDI THRU + * - moved filtering from Pm_Read to pm_enqueue to avoid buffer ovfl + * - extensive work on Mac OS X port, especially sysex and error handling + * + * 18May04 RBD + * - removed side-effects from assert() calls. Now you can disable assert(). + * - no longer check pm_hosterror everywhere, fixing a bug where an open + * failure could cause a write not to work on a previously opened port + * until you call Pm_GetHostErrorText(). + * 16May04 RBD and Chris Roberts + * - Some documentation wordsmithing in portmidi.h + * - Dynamically allocate port descriptor structures + * - Fixed parameter error in midiInPrepareBuffer and midiInAddBuffer. + * + * 09Oct03 RBD + * - Changed Thru handling. Now the client does all the work and the client + * must poll or read to keep thru messages flowing. + * + * 31May03 RBD + * - Fixed various bugs. + * - Added linux ALSA support with help from Clemens Ladisch + * - Added Mac OS X support, implemented by Jon Parise, updated and + * integrated by Andrew Zeldis and Zico Kolter + * - Added latency program to build histogram of system latency using PortTime. + * + * 30Jun02 RBD Extensive rewrite of sysex handling. It works now. + * Extensive reworking of error reporting and error text -- no + * longer use dictionary call to delete data; instead, Pm_Open + * and Pm_Close clean up before returning an error code, and + * error text is saved in a system-independent location. + * Wrote sysex.c to test sysex message handling. + * + * 15Jun02 BCT changes: + * - Added pmHostError text handling. + * - For robustness, check PortMidi stream args not NULL. + * - Re-C-ANSI-fied code (changed many C++ comments to C style) + * - Reorganized code in pmwinmm according to input/output functionality (made + * cleanup handling easier to reason about) + * - Fixed Pm_Write calls (portmidi.h says these should not return length but Pm_Error) + * - Cleaned up memory handling (now system specific data deleted via dictionary + * call in PortMidi, allows client to query host errors). + * - Added explicit asserts to verify various aspects of pmwinmm implementation behaves as + * logic implies it should. Specifically: verified callback routines not reentrant and + * all verified status for all unchecked Win32 MMedia API calls perform successfully + * - Moved portmidi initialization and clean-up routines into DLL to fix Win32 MMedia API + * bug (i.e. if devices not explicitly closed, must reboot to debug application further). + * With this change, clients no longer need explicitly call Pm_Initialize, Pm_Terminate, or + * explicitly Pm_Close open devices when using WinMM version of PortMidi. + * + * 23Jan02 RBD Fixed bug in pmwinmm.c thru handling + * + * 21Jan02 RBD Added tests in Pm_OpenInput() and Pm_OpenOutput() to prevent + * opening an input as output and vice versa. + * Added comments and documentation. + * Implemented Pm_Terminate(). + * + * + * IMPORTANT INFORMATION ABOUT A WIN32 BUG: + * + * Windows apparently has a serious midi bug -- if you do not close ports, Windows + * may crash. PortMidi tries to protect against this by using a DLL to clean up. + * + * If client exits for example with: + * i) assert + * ii) Ctrl^c, + * then DLL clean-up routine called. However, when client does something + * really bad (e.g. assigns value to NULL pointer) then DLL CLEANUP ROUTINE + * NEVER RUNS! In this state, if you wait around long enough, you will + * probably get the blue screen of death. Can also go into Pview and there will + * exist zombie process that you can't kill. + * + * NOTES ON HOST ERROR REPORTING: + * + * PortMidi errors (of type PmError) are generic, system-independent errors. + * When an error does not map to one of the more specific PmErrors, the + * catch-all code pmHostError is returned. This means that PortMidi has + * retained a more specific system-dependent error code. The caller can + * get more information by calling Pm_HasHostError() to test if there is + * a pending host error, and Pm_GetHostErrorText() to get a text string + * describing the error. Host errors are reported on a per-device basis + * because only after you open a device does PortMidi have a place to + * record the host error code. I.e. only + * those routines that receive a (PortMidiStream *) argument check and + * report errors. One exception to this is that Pm_OpenInput() and + * Pm_OpenOutput() can report errors even though when an error occurs, + * there is no PortMidiStream* to hold the error. Fortunately, both + * of these functions return any error immediately, so we do not really + * need per-device error memory. Instead, any host error code is stored + * in a global, pmHostError is returned, and the user can call + * Pm_GetHostErrorText() to get the error message (and the invalid stream + * parameter will be ignored.) The functions + * pm_init and pm_term do not fail or raise + * errors. The job of pm_init is to locate all available devices so that + * the caller can get information via PmDeviceInfo(). If an error occurs, + * the device is simply not listed as available. + * + * Host errors come in two flavors: + * a) host error + * b) host error during callback + * These can occur w/midi input or output devices. (b) can only happen + * asynchronously (during callback routines), whereas (a) only occurs while + * synchronously running PortMidi and any resulting system dependent calls + * + * Host-error reporting relies on following assumptions: + * 1) PortMidi routines won't allow system dependent routines to be + * called when args are bogus. + * Thus, in pmwinmm.c it is safe to assume: + * - stream ptr valid + * - currently not operating in "has host error" state + * 2) Host-error reporting relies on a staged delivery of error messages. + * When a host error occurs, the error code is saved with the stream. + * The error is reported as a return code from the next operation on + * the stream. This could be immediately if the error is synchronous, + * or delayed if the error is an asynchronous callback problem. In + * any case, when pmHostError is returned, the error is copied to + * a global, pm_hosterror and the error code stored with the stream + * is cleared. If the user chooses to inquire about the error using + * Pm_GetHostErrorText(), the error will be reported as text. If the + * user ignores the error and makes another call on the stream, the + * call will proceed because the error code associated with the stream + * has been cleared. + * + */ + +#ifndef FALSE + #define FALSE 0 +#endif +#ifndef TRUE + #define TRUE 1 +#endif + +/* default size of buffers for sysex transmission: */ +#define PM_DEFAULT_SYSEX_BUFFER_SIZE 1024 + + +typedef enum { + pmNoError = 0, + pmHostError = -10000, + pmInvalidDeviceId, /* out of range or output device when input is requested or vice versa */ + pmInsufficientMemory, + pmBufferTooSmall, + pmBufferOverflow, + pmBadPtr, + pmBadData, /* illegal midi data, e.g. missing EOX */ + pmInternalError, + pmBufferMaxSize, /* buffer is already as large as it can be */ +} PmError; + +/* + Pm_Initialize() is the library initialisation function - call this before + using the library. +*/ + +PmError Pm_Initialize( void ); + +/* + Pm_Terminate() is the library termination function - call this after + using the library. +*/ + +PmError Pm_Terminate( void ); + +/* A single PortMidiStream is a descriptor for an open MIDI device. +*/ +typedef void PortMidiStream; +#define PmStream PortMidiStream + +/* + Test whether stream has a pending host error. Normally, the client finds + out about errors through returned error codes, but some errors can occur + asynchronously where the client does not + explicitly call a function, and therefore cannot receive an error code. + The client can test for a pending error using Pm_HasHostError(). If true, + the error can be accessed and cleared by calling Pm_GetErrorText(). The + client does not need to call Pm_HasHostError(). Any pending error will be + reported the next time the client performs an explicit function call on + the stream, e.g. an input or output operation. +*/ +int Pm_HasHostError( PortMidiStream * stream ); + + +/* Translate portmidi error number into human readable message. + These strings are constants (set at compile time) so client has + no need to allocate storage +*/ +const char *Pm_GetErrorText( PmError errnum ); + +/* Translate portmidi host error into human readable message. + These strings are computed at run time, so client has to allocate storage. + After this routine executes, the host error is cleared. +*/ +void Pm_GetHostErrorText(char * msg, unsigned int len); + +#define HDRLENGTH 50 +#define PM_HOST_ERROR_MSG_LEN 256u /* any host error msg will occupy less + than this number of characters */ + +/* + Device enumeration mechanism. + + Device ids range from 0 to Pm_CountDevices()-1. + +*/ +typedef int PmDeviceID; +#define pmNoDevice -1 +typedef struct { + int structVersion; + const char *interf; /* underlying MIDI API, e.g. MMSystem or DirectX */ + const char *name; /* device name, e.g. USB MidiSport 1x1 */ + int input; /* true iff input is available */ + int output; /* true iff output is available */ + int opened; /* used by generic PortMidi code to do error checking on arguments */ + +} PmDeviceInfo; + + +int Pm_CountDevices( void ); +/* + Pm_GetDefaultInputDeviceID(), Pm_GetDefaultOutputDeviceID() + + Return the default device ID or pmNoDevice if there are no devices. + The result can be passed to Pm_OpenMidi(). + + On the PC, the user can specify a default device by + setting an environment variable. For example, to use device #1. + + set PM_RECOMMENDED_OUTPUT_DEVICE=1 + + The user should first determine the available device ID by using + the supplied application "testin" or "testout". + + In general, the registry is a better place for this kind of info, + and with USB devices that can come and go, using integers is not + very reliable for device identification. Under Windows, if + PM_RECOMMENDED_OUTPUT_DEVICE (or PM_RECOMMENDED_INPUT_DEVICE) is + *NOT* found in the environment, then the default device is obtained + by looking for a string in the registry under: + HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Input_Device + and HKEY_LOCAL_MACHINE/SOFTWARE/PortMidi/Recommended_Output_Device + for a string. The number of the first device with a substring that + matches the string exactly is returned. For example, if the string + in the registry is "USB", and device 1 is named + "In USB MidiSport 1x1", then that will be the default + input because it contains the string "USB". + + In addition to the name, PmDeviceInfo has the member "interf", which + is the interface name. (The "interface" is the underlying software + system or API used by PortMidi to access devices. Examples are + MMSystem, DirectX (not implemented), ALSA, OSS (not implemented), etc.) + At present, the only Win32 interface is "MMSystem", the only Linux + interface is "ALSA", and the only Max OS X interface is "CoreMIDI". + To specify both the interface and the device name in the registry, + separate the two with a comma and a space, e.g.: + MMSystem, In USB MidiSport 1x1 + In this case, the string before the comma must be a substring of + the "interf" string, and the string after the space must be a + substring of the "name" name string in order to match the device. + + Note: in the current release, the default is simply the first device + (the input or output device with the lowest PmDeviceID). +*/ +PmDeviceID Pm_GetDefaultInputDeviceID( void ); +PmDeviceID Pm_GetDefaultOutputDeviceID( void ); + +/* + PmTimestamp is used to represent a millisecond clock with arbitrary + start time. The type is used for all MIDI timestampes and clocks. +*/ +typedef long PmTimestamp; +typedef PmTimestamp (*PmTimeProcPtr)(void *time_info); + +/* TRUE if t1 before t2 */ +#define PmBefore(t1,t2) ((t1-t2) < 0) + +/* + Pm_GetDeviceInfo() returns a pointer to a PmDeviceInfo structure + referring to the device specified by id. + If id is out of range the function returns NULL. + + The returned structure is owned by the PortMidi implementation and must + not be manipulated or freed. The pointer is guaranteed to be valid + between calls to Pm_Initialize() and Pm_Terminate(). +*/ +const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); + +/* + Pm_OpenInput() and Pm_OpenOutput() open devices. + + stream is the address of a PortMidiStream pointer which will receive + a pointer to the newly opened stream. + + inputDevice is the id of the device used for input (see PmDeviceID above). + + inputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or handle processing. + inputDriverInfo is never required for correct operation. If not used + inputDriverInfo should be NULL. + + outputDevice is the id of the device used for output (see PmDeviceID above.) + + outputDriverInfo is a pointer to an optional driver specific data structure + containing additional information for device setup or handle processing. + outputDriverInfo is never required for correct operation. If not used + outputDriverInfo should be NULL. + + For input, the buffersize specifies the number of input events to be + buffered waiting to be read using Pm_Read(). For output, buffersize + specifies the number of output events to be buffered waiting for output. + (In some cases -- see below -- PortMidi does not buffer output at all + and merely passes data to a lower-level API, in which case buffersize + is ignored.) + + latency is the delay in milliseconds applied to timestamps to determine + when the output should actually occur. (If latency is < 0, 0 is assumed.) + If latency is zero, timestamps are ignored and all output is delivered + immediately. If latency is greater than zero, output is delayed until + the message timestamp plus the latency. (NOTE: time is measured relative + to the time source indicated by time_proc. Timestamps are absolute, not + relative delays or offsets.) In some cases, PortMidi can obtain + better timing than your application by passing timestamps along to the + device driver or hardware. Latency may also help you to synchronize midi + data to audio data by matching midi latency to the audio buffer latency. + + time_proc is a pointer to a procedure that returns time in milliseconds. It + may be NULL, in which case a default millisecond timebase (PortTime) is + used. If the application wants to use PortTime, it should start the timer + (call Pt_Start) before calling Pm_OpenInput or Pm_OpenOutput. If the + application tries to start the timer *after* Pm_OpenInput or Pm_OpenOutput, + it may get a ptAlreadyStarted error from Pt_Start, and the application's + preferred time resolution and callback function will be ignored. + time_proc result values are appended to incoming MIDI data, and time_proc + times are used to schedule outgoing MIDI data (when latency is non-zero). + + time_info is a pointer passed to time_proc. + + return value: + Upon success Pm_Open() returns PmNoError and places a pointer to a + valid PortMidiStream in the stream argument. + If a call to Pm_Open() fails a nonzero error code is returned (see + PMError above) and the value of port is invalid. + + Any stream that is successfully opened should eventually be closed + by calling Pm_Close(). + +*/ +PmError Pm_OpenInput( PortMidiStream** stream, + PmDeviceID inputDevice, + void *inputDriverInfo, + long bufferSize, + PmTimeProcPtr time_proc, + void *time_info ); + +PmError Pm_OpenOutput( PortMidiStream** stream, + PmDeviceID outputDevice, + void *outputDriverInfo, + long bufferSize, + PmTimeProcPtr time_proc, + void *time_info, + long latency ); + +/* + Pm_SetFilter() sets filters on an open input stream to drop selected + input types. By default, only active sensing messages are filtered. + To prohibit, say, active sensing and sysex messages, call + Pm_SetFilter(stream, PM_FILT_ACTIVE | PM_FILT_SYSEX); + + Filtering is useful when midi routing or midi thru functionality is being + provided by the user application. + For example, you may want to exclude timing messages (clock, MTC, start/stop/continue), + while allowing note-related messages to pass. + Or you may be using a sequencer or drum-machine for MIDI clock information but want to + exclude any notes it may play. + */ + +/* filter active sensing messages (0xFE): */ +#define PM_FILT_ACTIVE 0x1 +/* filter system exclusive messages (0xF0): */ +#define PM_FILT_SYSEX 0x2 +/* filter clock messages (0xF8 only, does not filter clock start, etc.): */ +#define PM_FILT_CLOCK 0x4 +/* filter play messages (start 0xFA, stop 0xFC, continue 0xFB) */ +#define PM_FILT_PLAY 0x8 +/* filter undefined F9 messages (some equipment uses this as a 10ms 'tick') */ +#define PM_FILT_F9 0x10 +#define PM_FILT_TICK PM_FILT_F9 +/* filter undefined FD messages */ +#define PM_FILT_FD 0x20 +/* filter undefined real-time messages */ +#define PM_FILT_UNDEFINED (PM_FILT_F9 | PM_FILT_FD) +/* filter reset messages (0xFF) */ +#define PM_FILT_RESET 0x40 +/* filter all real-time messages */ +#define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET) +/* filter note-on and note-off (0x90-0x9F and 0x80-0x8F */ +#define PM_FILT_NOTE 0x80 +/* filter channel aftertouch (most midi controllers use this) (0xD0-0xDF)*/ +#define PM_FILT_CHANNEL_AFTERTOUCH 0x100 +/* per-note aftertouch (Ensoniq holds a patent on generating this on keyboards until June 2006) (0xA0-0xAF) */ +#define PM_FILT_POLY_AFTERTOUCH 0x200 +/* filter both channel and poly aftertouch */ +#define PM_FILT_AFTERTOUCH (PM_FILT_CHANNEL_AFTERTOUCH | PM_FILT_POLY_AFTERTOUCH) +/* Program changes (0xC0-0xCF) */ +#define PM_FILT_PROGRAM 0x400 +/* Control Changes (CC's) (0xB0-0xBF)*/ +#define PM_FILT_CONTROL 0x800 +/* Pitch Bender (0xE0-0xEF*/ +#define PM_FILT_PITCHBEND 0x1000 +/* MIDI Time Code (0xF1)*/ +#define PM_FILT_MTC 0x2000 +/* Song Position (0xF2) */ +#define PM_FILT_SONG_POSITION 0x4000 +/* Song Select (0xF3)*/ +#define PM_FILT_SONG_SELECT 0x8000 +/* Tuning request (0xF6)*/ +#define PM_FILT_TUNE 0x10000 +/* All System Common messages (mtc, song position, song select, tune request) */ +#define PM_FILT_SYSTEMCOMMON (PM_FILT_MTC | PM_FILT_SONG_POSITION | PM_FILT_SONG_SELECT | PM_FILT_TUNE) + + +PmError Pm_SetFilter( PortMidiStream* stream, long filters ); + + +/* + Pm_SetChannelMask() filters incoming messages based on channel. + The mask is a 16-bit bitfield corresponding to appropriate channels + The Pm_Channel macro can assist in calling this function. + i.e. to set receive only input on channel 1, call with + Pm_SetChannelMask(Pm_Channel(1)); + Multiple channels should be OR'd together, like + Pm_SetChannelMask(Pm_Channel(10) | Pm_Channel(11)) + + All channels are allowed by default +*/ +#define Pm_Channel(channel) (1<<(channel)) + +PmError Pm_SetChannelMask(PortMidiStream *stream, int mask); + +/* + Pm_Abort() terminates outgoing messages immediately + The caller should immediately close the output port; + this call may result in transmission of a partial midi message. + There is no abort for Midi input because the user can simply + ignore messages in the buffer and close an input device at + any time. + */ +PmError Pm_Abort( PortMidiStream* stream ); + +/* + Pm_Close() closes a midi stream, flushing any pending buffers. + (PortMidi attempts to close open streams when the application + exits -- this is particularly difficult under Windows.) +*/ +PmError Pm_Close( PortMidiStream* stream ); + +/* + Pm_Message() encodes a short Midi message into a long word. If data1 + and/or data2 are not present, use zero. + + Pm_MessageStatus(), Pm_MessageData1(), and + Pm_MessageData2() extract fields from a long-encoded midi message. +*/ +#define Pm_Message(status, data1, data2) \ + ((((data2) << 16) & 0xFF0000) | \ + (((data1) << 8) & 0xFF00) | \ + ((status) & 0xFF)) +#define Pm_MessageStatus(msg) ((msg) & 0xFF) +#define Pm_MessageData1(msg) (((msg) >> 8) & 0xFF) +#define Pm_MessageData2(msg) (((msg) >> 16) & 0xFF) + +/* All midi data comes in the form of PmEvent structures. A sysex + message is encoded as a sequence of PmEvent structures, with each + structure carrying 4 bytes of the message, i.e. only the first + PmEvent carries the status byte. + + Note that MIDI allows nested messages: the so-called "real-time" MIDI + messages can be inserted into the MIDI byte stream at any location, + including within a sysex message. MIDI real-time messages are one-byte + messages used mainly for timing (see the MIDI spec). PortMidi retains + the order of non-real-time MIDI messages on both input and output, but + it does not specify exactly how real-time messages are processed. This + is particulary problematic for MIDI input, because the input parser + must either prepare to buffer an unlimited number of sysex message + bytes or to buffer an unlimited number of real-time messages that + arrive embedded in a long sysex message. To simplify things, the input + parser is allowed to pass real-time MIDI messages embedded within a + sysex message, and it is up to the client to detect, process, and + remove these messages as they arrive. + + When receiving sysex messages, the sysex message is terminated + by either an EOX status byte (anywhere in the 4 byte messages) or + by a non-real-time status byte in the low order byte of the message. + If you get a non-real-time status byte but there was no EOX byte, it + means the sysex message was somehow truncated. This is not + considered an error; e.g., a missing EOX can result from the user + disconnecting a MIDI cable during sysex transmission. + + A real-time message can occur within a sysex message. A real-time + message will always occupy a full PmEvent with the status byte in + the low-order byte of the PmEvent message field. (This implies that + the byte-order of sysex bytes and real-time message bytes may not + be preserved -- for example, if a real-time message arrives after + 3 bytes of a sysex message, the real-time message will be delivered + first. The first word of the sysex message will be delivered only + after the 4th byte arrives, filling the 4-byte PmEvent message field. + + The timestamp field is observed when the output port is opened with + a non-zero latency. A timestamp of zero means "use the current time", + which in turn means to deliver the message with a delay of + latency (the latency parameter used when opening the output port.) + Do not expect PortMidi to sort data according to timestamps -- + messages should be sent in the correct order, and timestamps MUST + be non-decreasing. + + A sysex message will generally fill many PmEvent structures. On + output to a PortMidiStream with non-zero latency, the first timestamp + on sysex message data will determine the time to begin sending the + message. PortMidi implementations may ignore timestamps for the + remainder of the sysex message. + + On input, the timestamp ideally denotes the arrival time of the + status byte of the message. The first timestamp on sysex message + data will be valid. Subsequent timestamps may denote + when message bytes were actually received, or they may be simply + copies of the first timestamp. + + Timestamps for nested messages: If a real-time message arrives in + the middle of some other message, it is enqueued immediately with + the timestamp corresponding to its arrival time. The interrupted + non-real-time message or 4-byte packet of sysex data will be enqueued + later. The timestamp of interrupted data will be equal to that of + the interrupting real-time message to insure that timestamps are + non-decreasing. + */ +typedef long PmMessage; +typedef struct { + PmMessage message; + PmTimestamp timestamp; +} PmEvent; + +/* + Pm_Read() retrieves midi data into a buffer, and returns the number + of events read. Result is a non-negative number unless an error occurs, + in which case a PmError value will be returned. + + Buffer Overflow + + The problem: if an input overflow occurs, data will be lost, ultimately + because there is no flow control all the way back to the data source. + When data is lost, the receiver should be notified and some sort of + graceful recovery should take place, e.g. you shouldn't resume receiving + in the middle of a long sysex message. + + With a lock-free fifo, which is pretty much what we're stuck with to + enable portability to the Mac, it's tricky for the producer and consumer + to synchronously reset the buffer and resume normal operation. + + Solution: the buffer managed by PortMidi will be flushed when an overflow + occurs. The consumer (Pm_Read()) gets an error message (pmBufferOverflow) + and ordinary processing resumes as soon as a new message arrives. The + remainder of a partial sysex message is not considered to be a "new + message" and will be flushed as well. + +*/ +PmError Pm_Read( PortMidiStream *stream, PmEvent *buffer, long length ); + +/* + Pm_Poll() tests whether input is available, + returning TRUE, FALSE, or an error value. +*/ +PmError Pm_Poll( PortMidiStream *stream); + +/* + Pm_Write() writes midi data from a buffer. This may contain: + - short messages + or + - sysex messages that are converted into a sequence of PmEvent + structures, e.g. sending data from a file or forwarding them + from midi input. + + Use Pm_WriteSysEx() to write a sysex message stored as a contiguous + array of bytes. + + Sysex data may contain embedded real-time messages. +*/ +PmError Pm_Write( PortMidiStream *stream, PmEvent *buffer, long length ); + +/* + Pm_WriteShort() writes a timestamped non-system-exclusive midi message. + Messages are delivered in order as received, and timestamps must be + non-decreasing. (But timestamps are ignored if the stream was opened + with latency = 0.) +*/ +PmError Pm_WriteShort( PortMidiStream *stream, PmTimestamp when, long msg); + +/* + Pm_WriteSysEx() writes a timestamped system-exclusive midi message. +*/ +PmError Pm_WriteSysEx( PortMidiStream *stream, PmTimestamp when, unsigned char *msg); + + +#ifdef __cplusplus +} +#endif /* __cplusplus */ +#endif /* PORT_MIDI_H */ -- cgit v1.2.1