diff options
Diffstat (limited to 'pd/portmidi/pm_common/portmidi.h')
| -rw-r--r-- | pd/portmidi/pm_common/portmidi.h | 418 |
1 files changed, 166 insertions, 252 deletions
diff --git a/pd/portmidi/pm_common/portmidi.h b/pd/portmidi/pm_common/portmidi.h index 8c9c04c2..8f4879f3 100644 --- a/pd/portmidi/pm_common/portmidi.h +++ b/pd/portmidi/pm_common/portmidi.h @@ -10,7 +10,12 @@ extern "C" { * 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
+ * Copyright (c) 2001-2006 Roger B. Dannenberg
+ *
+ * Latest version available at: http://www.cs.cmu.edu/~music/portmidi/
+ *
+ * Copyright (c) 1999-2000 Ross Bencina and Phil Burk
+ * Copyright (c) 2001-2006 Roger B. Dannenberg
*
* Permission is hereby granted, free of charge, to any person obtaining
* a copy of this software and associated documentation files
@@ -23,10 +28,6 @@ extern "C" { * 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.
@@ -34,114 +35,21 @@ extern "C" { * 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.
+ */
+
+/*
+ * The text above constitutes the entire PortMidi license; however,
+ * the PortMusic community also makes the following non-binding requests:
*
+ * 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. It is also
+ * requested that these non-binding requests be included along with the
+ * license above.
*/
/* 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().
- *
+ * (see ../CHANGELOG.txt)
*
* IMPORTANT INFORMATION ABOUT A WIN32 BUG:
*
@@ -149,15 +57,19 @@ extern "C" { * 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
+ * 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:
+ * You can enable the DLL cleanup routine by defining USE_DLL_FOR_CLEANUP.
+ * Do not define this preprocessor symbol if you do not want to use this
+ * feature.
+ *
+ * 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
@@ -165,50 +77,45 @@ extern "C" { * 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
+ * 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
+ * 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
+ * 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
+ * a) host error
* b) host error during callback
- * These can occur w/midi input or output devices. (b) can only happen
+ * 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
+ * synchronously running PortMidi and any resulting system dependent calls.
+ * Both (a) and (b) are reported by the next read or write call. You can
+ * also query for asynchronous errors (b) at any time by calling
+ * Pm_HasHostError().
*
- * 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.
+ * NOTES ON COMPILE-TIME SWITCHES
*
- */
+ * DEBUG assumes stdio and a console. Use this if you want automatic, simple
+ * error reporting, e.g. for prototyping. If you are using MFC or some
+ * other graphical interface with no console, DEBUG probably should be
+ * undefined.
+ * PM_CHECK_ERRORS more-or-less takes over error checking for return values,
+ * stopping your program and printing error messages when an error
+ * occurs. This also uses stdio for console text I/O.
+ * USE_DLL_FOR_CLEANUP is described above. (Windows only.)
+ *
+ */
#ifndef FALSE
#define FALSE 0
@@ -224,14 +131,19 @@ extern "C" { typedef enum {
pmNoError = 0,
pmHostError = -10000,
- pmInvalidDeviceId, /* out of range or output device when input is requested or vice versa */
+ pmInvalidDeviceId, /* out of range or
+ * output device when input is requested or
+ * input device when output is requested or
+ * device is already opened
+ */
pmInsufficientMemory,
pmBufferTooSmall,
pmBufferOverflow,
pmBadPtr,
pmBadData, /* illegal midi data, e.g. missing EOX */
pmInternalError,
- pmBufferMaxSize, /* buffer is already as large as it can be */
+ pmBufferMaxSize /* buffer is already as large as it can be */
+ /* NOTE: If you add a new error type, be sure to update Pm_GetErrorText() */
} PmError;
/*
@@ -255,32 +167,35 @@ typedef void 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.
+ 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().
+ Errors are also cleared by calling other functions that can return
+ errors, e.g. Pm_OpenInput(), Pm_OpenOutput(), Pm_Read(), Pm_Write(). 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. Until the error is cleared,
+ no new error codes will be obtained, even for a different stream.
*/
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
+ 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.
+ 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
+#define PM_HOST_ERROR_MSG_LEN 256u /* any host error msg will occupy less
than this number of characters */
/*
@@ -292,7 +207,7 @@ void Pm_GetHostErrorText(char * msg, unsigned int len); typedef int PmDeviceID;
#define pmNoDevice -1
typedef struct {
- int structVersion;
+ 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 */
@@ -308,12 +223,12 @@ int Pm_CountDevices( void ); 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".
@@ -327,25 +242,25 @@ int Pm_CountDevices( void ); 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 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".
+ 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
+ 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).
+ (the input or output device with the lowest PmDeviceID).
*/
PmDeviceID Pm_GetDefaultInputDeviceID( void );
PmDeviceID Pm_GetDefaultOutputDeviceID( void );
@@ -391,26 +306,26 @@ const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); 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.
+ 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.)
+ 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.
+ 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
+ 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,
@@ -419,7 +334,7 @@ const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); 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.
+ time_info is a pointer passed to time_proc.
return value:
Upon success Pm_Open() returns PmNoError and places a pointer to a
@@ -428,7 +343,7 @@ const PmDeviceInfo* Pm_GetDeviceInfo( PmDeviceID id ); PMError above) and the value of port is invalid.
Any stream that is successfully opened should eventually be closed
- by calling Pm_Close().
+ by calling Pm_Close().
*/
PmError Pm_OpenInput( PortMidiStream** stream,
@@ -446,7 +361,7 @@ PmError Pm_OpenOutput( PortMidiStream** stream, 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
@@ -461,53 +376,52 @@ PmError Pm_OpenOutput( PortMidiStream** stream, */
/* filter active sensing messages (0xFE): */
-#define PM_FILT_ACTIVE 0x1
+#define PM_FILT_ACTIVE (1 << 0x0E)
/* 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
+#define PM_FILT_SYSEX (1 << 0x00)
+/* filter clock messages (CLOCK 0xF8, START 0xFA, STOP 0xFC, and CONTINUE 0xFB) */
+#define PM_FILT_CLOCK ((1 << 0x08) | (1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
/* 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
+#define PM_FILT_PLAY (1 << 0x0A)
+/* filter tick messages (0xF9) */
+#define PM_FILT_TICK (1 << 0x09)
/* filter undefined FD messages */
-#define PM_FILT_FD 0x20
+#define PM_FILT_FD (1 << 0x0D)
/* filter undefined real-time messages */
-#define PM_FILT_UNDEFINED (PM_FILT_F9 | PM_FILT_FD)
+#define PM_FILT_UNDEFINED PM_FILT_FD
/* filter reset messages (0xFF) */
-#define PM_FILT_RESET 0x40
+#define PM_FILT_RESET (1 << 0x0F)
/* 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)
+#define PM_FILT_REALTIME (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \
+ PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK)
/* filter note-on and note-off (0x90-0x9F and 0x80-0x8F */
-#define PM_FILT_NOTE 0x80
+#define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18))
/* 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
+#define PM_FILT_CHANNEL_AFTERTOUCH (1 << 0x1D)
+/* per-note aftertouch (0xA0-0xAF) */
+#define PM_FILT_POLY_AFTERTOUCH (1 << 0x1A)
/* 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
+#define PM_FILT_PROGRAM (1 << 0x1C)
/* Control Changes (CC's) (0xB0-0xBF)*/
-#define PM_FILT_CONTROL 0x800
+#define PM_FILT_CONTROL (1 << 0x1B)
/* Pitch Bender (0xE0-0xEF*/
-#define PM_FILT_PITCHBEND 0x1000
+#define PM_FILT_PITCHBEND (1 << 0x1E)
/* MIDI Time Code (0xF1)*/
-#define PM_FILT_MTC 0x2000
+#define PM_FILT_MTC (1 << 0x01)
/* Song Position (0xF2) */
-#define PM_FILT_SONG_POSITION 0x4000
+#define PM_FILT_SONG_POSITION (1 << 0x02)
/* Song Select (0xF3)*/
-#define PM_FILT_SONG_SELECT 0x8000
+#define PM_FILT_SONG_SELECT (1 << 0x03)
/* Tuning request (0xF6)*/
-#define PM_FILT_TUNE 0x10000
+#define PM_FILT_TUNE (1 << 0x06)
/* 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
@@ -532,11 +446,11 @@ PmError Pm_SetChannelMask(PortMidiStream *stream, int mask); 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.)
+ (PortMidi attempts to close open streams when the application
+ exits -- this is particularly difficult under Windows.)
*/
PmError Pm_Close( PortMidiStream* stream );
@@ -544,7 +458,7 @@ 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_MessageStatus(), Pm_MessageData1(), and
Pm_MessageData2() extract fields from a long-encoded midi message.
*/
#define Pm_Message(status, data1, data2) \
@@ -560,61 +474,61 @@ PmError Pm_Close( PortMidiStream* stream ); 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,
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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
+ 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.
@@ -627,19 +541,19 @@ typedef struct { /*
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,
+ 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
+ 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
+ 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
@@ -652,20 +566,20 @@ typedef struct { PmError Pm_Read( PortMidiStream *stream, PmEvent *buffer, long length );
/*
- Pm_Poll() tests whether input is available,
+ 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
+ - 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
+ Use Pm_WriteSysEx() to write a sysex message stored as a contiguous
array of bytes.
Sysex data may contain embedded real-time messages.
@@ -674,9 +588,9 @@ 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.)
+ 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);
|