[PD-cvs] pd/portmidi/pm_common pminternal.h, 1.1, 1.2 pmutil.c, 1.1, 1.2 pmutil.h, 1.1, 1.2 portmidi.c, 1.1, 1.2 portmidi.h, 1.1, 1.2

Update of /cvsroot/pure-data/pd/portmidi/pm_common In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv5166/pd/portmidi/pm_common

Modified Files: pminternal.h pmutil.c pmutil.h portmidi.c portmidi.h Log Message: 0.41-0 test 11

Index: pminternal.h =================================================================== RCS file: /cvsroot/pure-data/pd/portmidi/pm_common/pminternal.h,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** pminternal.h 15 Dec 2005 00:56:57 -0000 1.1 --- pminternal.h 16 Jan 2008 21:54:10 -0000 1.2 *************** *** 29,37 **** extern int pm_hosterror; extern char pm_hosterror_text[PM_HOST_ERROR_MSG_LEN]; ! struct pm_internal_struct;

/* these do not use PmInternal because it is not defined yet... */ ! typedef PmError (*pm_write_short_fn)(struct pm_internal_struct *midi, PmEvent *buffer); typedef PmError (*pm_begin_sysex_fn)(struct pm_internal_struct *midi, --- 29,37 ---- extern int pm_hosterror; extern char pm_hosterror_text[PM_HOST_ERROR_MSG_LEN]; ! struct pm_internal_struct;

/* these do not use PmInternal because it is not defined yet... */ ! typedef PmError (*pm_write_short_fn)(struct pm_internal_struct *midi, PmEvent *buffer); typedef PmError (*pm_begin_sysex_fn)(struct pm_internal_struct *midi, *************** *** 43,47 **** typedef PmError (*pm_write_realtime_fn)(struct pm_internal_struct *midi, PmEvent *buffer); ! typedef PmError (*pm_write_flush_fn)(struct pm_internal_struct *midi); typedef PmTimestamp (*pm_synchronize_fn)(struct pm_internal_struct *midi); /* pm_open_fn should clean up all memory and close the device if any part --- 43,48 ---- typedef PmError (*pm_write_realtime_fn)(struct pm_internal_struct *midi, PmEvent *buffer); ! typedef PmError (*pm_write_flush_fn)(struct pm_internal_struct *midi, ! PmTimestamp timestamp); typedef PmTimestamp (*pm_synchronize_fn)(struct pm_internal_struct *midi); /* pm_open_fn should clean up all memory and close the device if any part *************** *** 70,74 **** pm_close_fn close; /* close device */ pm_poll_fn poll; /* read pending midi events into portmidi buffer */ ! pm_has_host_error_fn has_host_error; /* true when device has had host error message */ pm_host_error_fn host_error; /* provide text readable host error message --- 71,75 ---- pm_close_fn close; /* close device */ pm_poll_fn poll; /* read pending midi events into portmidi buffer */ ! pm_has_host_error_fn has_host_error; /* true when device has had host error message */ pm_host_error_fn host_error; /* provide text readable host error message *************** *** 84,88 **** device closing (see PmDeviceInfo struct) */ void *descriptor; /* ID number passed to win32 multimedia API open */ ! void *internalDescriptor; /* points to PmInternal device, allows automatic device closing */ pm_fns_type dictionary; --- 85,89 ---- device closing (see PmDeviceInfo struct) */ void *descriptor; /* ID number passed to win32 multimedia API open */ ! void *internalDescriptor; /* points to PmInternal device, allows automatic device closing */ pm_fns_type dictionary; *************** *** 98,125 **** int device_id; /* which device is open (index to descriptors) */ short write_flag; /* MIDI_IN, or MIDI_OUT */ ! PmTimeProcPtr time_proc; /* where to get the time */ void *time_info; /* pass this to get_time() */ ! ! long buffer_len; /* how big is the buffer */ ! PmEvent *buffer; /* storage for: ! - midi input - midi output w/latency != 0 */ long head; long tail; ! long latency; /* time delay in ms between timestamps and actual output */ /* set to zero to get immediate, simple blocking output */ /* if latency is zero, timestamps will be ignored; */ /* if midi input device, this field ignored */ ! ! int overflow; /* set to non-zero if input is dropped */ ! int flush; /* flag to drop incoming sysex data because of overflow */ ! int sysex_in_progress; /* use for overflow management */ PmMessage sysex_message; /* buffer for 4 bytes of sysex data */ int sysex_message_count; /* how many bytes in sysex_message so far */

long filters; /* flags that filter incoming message classes */ ! int channel_mask; /* filter incoming messages based on channel */ PmTimestamp last_msg_time; /* timestamp of last message */ PmTimestamp sync_time; /* time of last synchronization */ --- 99,134 ---- int device_id; /* which device is open (index to descriptors) */ short write_flag; /* MIDI_IN, or MIDI_OUT */ ! PmTimeProcPtr time_proc; /* where to get the time */ void *time_info; /* pass this to get_time() */ ! long buffer_len; /* how big is the buffer or queue? */ ! #ifdef NEWBUFFER ! PmQueue *queue; ! #else ! PmEvent *buffer; /* storage for: ! - midi input - midi output w/latency != 0 */ long head; long tail; ! int overflow; /* set to non-zero if input is dropped */ ! #endif long latency; /* time delay in ms between timestamps and actual output */ /* set to zero to get immediate, simple blocking output */ /* if latency is zero, timestamps will be ignored; */ /* if midi input device, this field ignored */ ! ! int sysex_in_progress; /* when sysex status is seen, this flag becomes ! * true until EOX is seen. When true, new data is appended to the ! * stream of outgoing bytes. When overflow occurs, sysex data is ! * dropped (until an EOX or non-real-timei status byte is seen) so ! * that, if the overflow condition is cleared, we don't start ! * sending data from the middle of a sysex message. If a sysex ! * message is filtered, sysex_in_progress is false, causing the ! * message to be dropped. */ PmMessage sysex_message; /* buffer for 4 bytes of sysex data */ int sysex_message_count; /* how many bytes in sysex_message so far */

long filters; /* flags that filter incoming message classes */ ! int channel_mask; /* flter incoming messages based on channel */ PmTimestamp last_msg_time; /* timestamp of last message */ PmTimestamp sync_time; /* time of last synchronization */ *************** *** 128,164 **** pm_fns_type dictionary; /* implementation functions */ void *descriptor; /* system-dependent state */ ! } PmInternal;

- typedef struct { - long head; - long tail; - long len; - long msg_size; - long overflow; - char *buffer; - } PmQueueRep;

/* defined by system specific implementation, e.g. pmwinmm, used by PortMidi */ ! void pm_init(void); ! void pm_term(void);

/* defined by portMidi, used by pmwinmm */ PmError none_write_short(PmInternal *midi, PmEvent *buffer); ! PmError none_sysex(PmInternal *midi, PmTimestamp timestamp); ! PmError none_write_byte(PmInternal *midi, unsigned char byte, PmTimestamp timestamp); PmTimestamp none_synchronize(PmInternal *midi);

PmError pm_fail_fn(PmInternal *midi); PmError pm_success_fn(PmInternal *midi); PmError pm_add_device(char *interf, char *name, int input, void *descriptor, pm_fns_type dictionary); ! void pm_read_byte(PmInternal *midi, unsigned char byte, PmTimestamp timestamp); ! void pm_begin_sysex(PmInternal *midi); ! void pm_end_sysex(PmInternal *midi); void pm_read_short(PmInternal *midi, PmEvent *event);

! #define none_write_flush pm_fail_fn #define none_poll pm_fail_fn #define success_poll pm_success_fn --- 137,173 ---- pm_fns_type dictionary; /* implementation functions */ void *descriptor; /* system-dependent state */ ! /* the following are used to expedite sysex data */ ! /* on windows, in debug mode, based on some profiling, these optimizations ! * cut the time to process sysex bytes from about 7.5 to 0.26 usec/byte, ! * but this does not count time in the driver, so I don't know if it is ! * important ! */ ! unsigned char *fill_base; /* addr of ptr to sysex data */ ! int *fill_offset_ptr; /* offset of next sysex byte */ ! int fill_length; /* how many sysex bytes to write */ } PmInternal;

/* defined by system specific implementation, e.g. pmwinmm, used by PortMidi */ ! void pm_init(void); ! void pm_term(void);

/* defined by portMidi, used by pmwinmm */ PmError none_write_short(PmInternal *midi, PmEvent *buffer); ! PmError none_write_byte(PmInternal *midi, unsigned char byte, PmTimestamp timestamp); PmTimestamp none_synchronize(PmInternal *midi);

PmError pm_fail_fn(PmInternal *midi); + PmError pm_fail_timestamp_fn(PmInternal *midi, PmTimestamp timestamp); PmError pm_success_fn(PmInternal *midi); PmError pm_add_device(char *interf, char *name, int input, void *descriptor, pm_fns_type dictionary); ! unsigned int pm_read_bytes(PmInternal *midi, unsigned char *data, int len, ! PmTimestamp timestamp); void pm_read_short(PmInternal *midi, PmEvent *event);

! #define none_write_flush pm_fail_timestamp_fn ! #define none_sysex pm_fail_timestamp_fn #define none_poll pm_fail_fn #define success_poll pm_success_fn

Index: pmutil.c =================================================================== RCS file: /cvsroot/pure-data/pd/portmidi/pm_common/pmutil.c,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** pmutil.c 15 Dec 2005 00:56:57 -0000 1.1 --- pmutil.c 16 Jan 2008 21:54:10 -0000 1.2 *************** *** 3,6 **** --- 3,7 ---- */ #include "stdlib.h" + #include "assert.h" #include "memory.h" #include "portmidi.h" *************** *** 8,30 **** #include "pminternal.h"

PmQueue *Pm_QueueCreate(long num_msgs, long bytes_per_msg) { PmQueueRep *queue = (PmQueueRep *) pm_alloc(sizeof(PmQueueRep)); ! ! /* arg checking */ if (!queue) ! return NULL; ! ! queue->len = num_msgs * bytes_per_msg; ! queue->buffer = pm_alloc(queue->len); if (!queue->buffer) { pm_free(queue); return NULL; } queue->head = 0; queue->tail = 0; ! queue->msg_size = bytes_per_msg; queue->overflow = FALSE; return queue; } --- 9,73 ---- #include "pminternal.h"

+ #ifdef WIN32 + #define bzero(addr, siz) memset(addr, 0, siz) + #endif + + // #define QUEUE_DEBUG 1 + #ifdef QUEUE_DEBUG + #include "stdio.h" + #endif + + /* code is based on 4-byte words -- it should work on a 64-bit machine + as long as a "long" has 4 bytes. This code could be generalized to + be independent of the size of "long" */ + + typedef long int32; + + typedef struct { + long head; + long tail; + long len; + long msg_size; /* number of int32 in a message including extra word */ + long overflow; + long peek_overflow; + int32 *buffer; + int32 *peek; + int peek_flag; + } PmQueueRep; +

PmQueue *Pm_QueueCreate(long num_msgs, long bytes_per_msg) { PmQueueRep *queue = (PmQueueRep *) pm_alloc(sizeof(PmQueueRep)); ! int int32s_per_msg = ((bytes_per_msg + sizeof(int32) - 1) & ! ~(sizeof(int32) - 1)) / sizeof(int32); ! /* arg checking */ if (!queue) ! return NULL; ! ! /* need extra word per message for non-zero encoding */ ! queue->len = num_msgs * (int32s_per_msg + 1); ! queue->buffer = (int32 *) pm_alloc(queue->len * sizeof(int32)); ! bzero(queue->buffer, queue->len * sizeof(int32)); if (!queue->buffer) { pm_free(queue); return NULL; + } else { /* allocate the "peek" buffer */ + queue->peek = (int32 *) pm_alloc(int32s_per_msg * sizeof(int32)); + if (!queue->peek) { + /* free everything allocated so far and return */ + pm_free(queue->buffer); + pm_free(queue); + return NULL; + } } + bzero(queue->buffer, queue->len * sizeof(int32)); queue->head = 0; queue->tail = 0; ! /* msg_size is in words */ ! queue->msg_size = int32s_per_msg + 1; /* note extra word is counted */ queue->overflow = FALSE; + queue->peek_overflow = FALSE; + queue->peek_flag = FALSE; return queue; } *************** *** 34,43 **** { PmQueueRep *queue = (PmQueueRep *) q; ! ! /* arg checking */ ! if (!queue || !queue->buffer) ! return pmBadPtr;

! pm_free(queue->buffer); pm_free(queue); return pmNoError; --- 77,87 ---- { PmQueueRep *queue = (PmQueueRep *) q; ! ! /* arg checking */ ! if (!queue || !queue->buffer || !queue->peek) ! return pmBadPtr;

! pm_free(queue->peek); ! pm_free(queue->buffer); pm_free(queue); return pmNoError; *************** *** 49,65 **** long head; PmQueueRep *queue = (PmQueueRep *) q;

! /* arg checking */ ! if(!queue) ! return pmBadPtr;

! if (queue->overflow) { ! queue->overflow = FALSE; return pmBufferOverflow; }

! head = queue->head; /* make sure this is written after access */ ! if (head == queue->tail) return 0; ! memcpy(msg, queue->buffer + head, queue->msg_size); head += queue->msg_size; if (head == queue->len) head = 0; --- 93,177 ---- long head; PmQueueRep *queue = (PmQueueRep *) q; + int i; + int32 *msg_as_int32 = (int32 *) msg;

! /* arg checking */ ! if (!queue) ! return pmBadPtr; ! /* a previous peek operation encountered an overflow, but the overflow ! * has not yet been reported to client, so do it now. No message is ! * returned, but on the next call, we will return the peek buffer. ! */ ! if (queue->peek_overflow) { ! queue->peek_overflow = FALSE; ! return pmBufferOverflow; ! } ! if (queue->peek_flag) { ! #ifdef QUEUE_DEBUG ! printf("Pm_Dequeue returns peek msg:"); ! for (i = 0; i < queue->msg_size - 1; i++) { ! printf(" %d", queue->peek[i]); ! } ! printf("\n"); ! #endif ! memcpy(msg, queue->peek, (queue->msg_size - 1) * sizeof(int32)); ! queue->peek_flag = FALSE; ! return 1; ! }

! head = queue->head; ! /* if writer overflows, it writes queue->overflow = tail+1 so that ! * when the reader gets to that position in the buffer, it can ! * return the overflow condition to the reader. The problem is that ! * at overflow, things have wrapped around, so tail == head, and the ! * reader will detect overflow immediately instead of waiting until ! * it reads everything in the buffer, wrapping around again to the ! * point where tail == head. So the condition also checks that ! * queue->buffer[head] is zero -- if so, then the buffer is now ! * empty, and we're at the point in the msg stream where overflow ! * occurred. It's time to signal overflow to the reader. If ! * queue->buffer[head] is non-zero, there's a message there and we ! * should read all the way around the buffer before signalling overflow. ! * There is a write-order dependency here, but to fail, the overflow ! * field would have to be written while an entire buffer full of ! * writes are still pending. I'm assuming out-of-order writes are ! * possible, but not that many. ! */ ! if (queue->overflow == head + 1 && !queue->buffer[head]) { ! queue->overflow = 0; /* non-overflow condition */ return pmBufferOverflow; }

! /* test to see if there is data in the queue -- test from back ! * to front so if writer is simultaneously writing, we don't ! * waste time discovering the write is not finished ! */ ! for (i = queue->msg_size - 1; i >= 0; i--) { ! if (!queue->buffer[head + i]) { ! return 0; ! } ! } ! #ifdef QUEUE_DEBUG ! printf("Pm_Dequeue:"); ! for (i = 0; i < queue->msg_size; i++) { ! printf(" %d", queue->buffer[head + i]); ! } ! printf("\n"); ! #endif ! memcpy(msg, (char *) &queue->buffer[head + 1], ! sizeof(int32) * (queue->msg_size - 1)); ! /* fix up zeros */ ! i = queue->buffer[head]; ! while (i < queue->msg_size) { ! int32 j; ! i--; /* msg does not have extra word so shift down */ ! j = msg_as_int32[i]; ! msg_as_int32[i] = 0; ! i = j; ! } ! /* signal that data has been removed by zeroing: */ ! bzero((char *) &queue->buffer[head], sizeof(int32) * queue->msg_size); ! ! /* update head */ head += queue->msg_size; if (head == queue->len) head = 0; *************** *** 69,132 ****

! /* source should not enqueue data if overflow is set */ ! /**/ PmError Pm_Enqueue(PmQueue *q, void *msg) { PmQueueRep *queue = (PmQueueRep *) q; long tail;

! /* arg checking */ ! if (!queue) ! return pmBadPtr;

! tail = queue->tail; ! memcpy(queue->buffer + tail, msg, queue->msg_size); ! tail += queue->msg_size; ! if (tail == queue->len) tail = 0; ! if (tail == queue->head) { ! queue->overflow = TRUE; ! /* do not update tail, so message is lost */ return pmBufferOverflow; } queue->tail = tail; return pmNoError; }

int Pm_QueueEmpty(PmQueue *q) { PmQueueRep *queue = (PmQueueRep *) q; if (!queue) return TRUE; ! return (queue->head == queue->tail); }

int Pm_QueueFull(PmQueue *q) { PmQueueRep *queue = (PmQueueRep *) q; ! long tail; ! ! /* arg checking */ ! if(!queue) ! return pmBadPtr; ! ! tail = queue->tail; ! tail += queue->msg_size; ! if (tail == queue->len) { ! tail = 0; } ! return (tail == queue->head); }

void *Pm_QueuePeek(PmQueue *q) { - long head; PmQueueRep *queue = (PmQueueRep *) q;

! /* arg checking */ ! if(!queue) ! return NULL;

! head = queue->head; /* make sure this is written after access */ ! if (head == queue->tail) return NULL; ! return queue->buffer + head; }

--- 181,311 ----

! ! PmError Pm_SetOverflow(PmQueue *q) ! { ! PmQueueRep *queue = (PmQueueRep *) q; ! long tail; ! /* no more enqueue until receiver acknowledges overflow */ ! if (queue->overflow) return pmBufferOverflow; ! if (!queue) ! return pmBadPtr; ! tail = queue->tail; ! queue->overflow = tail + 1; ! return pmBufferOverflow; ! } ! ! PmError Pm_Enqueue(PmQueue *q, void *msg) { PmQueueRep *queue = (PmQueueRep *) q; long tail; + int i; + int32 *src = (int32 *) msg; + int32 *ptr;

! int32 *dest;

! int rslt; ! /* no more enqueue until receiver acknowledges overflow */ ! if (!queue) return pmBadPtr; ! if (queue->overflow) return pmBufferOverflow; ! rslt = Pm_QueueFull(q); ! /* already checked above: if (rslt == pmBadPtr) return rslt; */ ! tail = queue->tail; ! if (rslt) { ! queue->overflow = tail + 1; return pmBufferOverflow; } + + /* queue is has room for message, and overflow flag is cleared */ + ptr = &queue->buffer[tail]; + dest = ptr + 1; + for (i = 1; i < queue->msg_size; i++) { + int32 j = src[i - 1]; + if (!j) { + *ptr = i; + ptr = dest; + } else { + *dest = j; + } + dest++; + } + *ptr = i; + #ifdef QUEUE_DEBUG + printf("Pm_Enqueue:"); + for (i = 0; i < queue->msg_size; i++) { + printf(" %d", queue->buffer[tail + i]); + } + printf("\n"); + #endif + tail += queue->msg_size; + if (tail == queue->len) tail = 0; queue->tail = tail; return pmNoError; }

+ int Pm_QueueEmpty(PmQueue *q) { PmQueueRep *queue = (PmQueueRep *) q; if (!queue) return TRUE; ! return (queue->buffer[queue->head] == 0); }

+ int Pm_QueueFull(PmQueue *q) { PmQueueRep *queue = (PmQueueRep *) q; ! int tail; ! int i; ! /* arg checking */ ! if (!queue) ! return pmBadPtr; ! tail = queue->tail; ! /* test to see if there is space in the queue */ ! for (i = 0; i < queue->msg_size; i++) { ! if (queue->buffer[tail + i]) { ! return TRUE; ! } } ! return FALSE; }

void *Pm_QueuePeek(PmQueue *q) { PmQueueRep *queue = (PmQueueRep *) q; + PmError rslt; + long temp;

! /* arg checking */ ! if (!queue) ! return NULL;

! if (queue->peek_flag) { ! return queue->peek; ! } ! /* this is ugly: if peek_overflow is set, then Pm_Dequeue() ! * returns immediately with pmBufferOverflow, but here, we ! * want Pm_Dequeue() to really check for data. If data is ! * there, we can return it ! */ ! temp = queue->peek_overflow; ! queue->peek_overflow = FALSE; ! rslt = Pm_Dequeue(q, queue->peek); ! queue->peek_overflow = temp; ! ! if (rslt == 1) { ! queue->peek_flag = TRUE; ! return queue->peek; ! } else if (rslt == pmBufferOverflow) { ! /* when overflow is indicated, the queue is empty and the ! * first message that was dropped by Enqueue (signalling ! * pmBufferOverflow to its caller) would have been the next ! * message in the queue. Pm_QueuePeek will return NULL, but ! * remember that an overflow occurred. (see Pm_Dequeue) ! */ ! queue->peek_overflow = TRUE; ! } ! return NULL; }

Index: portmidi.c =================================================================== RCS file: /cvsroot/pure-data/pd/portmidi/pm_common/portmidi.c,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** portmidi.c 15 Dec 2005 00:56:57 -0000 1.1 --- portmidi.c 16 Jan 2008 21:54:10 -0000 1.2 *************** *** 3,6 **** --- 3,9 ---- #include "portmidi.h" #include "porttime.h" + #ifdef NEWBUFFER + #include "pmutil.h" + #endif #include "pminternal.h" #include <assert.h> *************** *** 32,36 **** [...1617 lines suppressed...] *************** *** 972,980 **** /* arg checking */ assert(midi != NULL); ! assert(!Pm_HasHostError(midi)); ! tail = midi->tail + 1; if (tail == midi->buffer_len) tail = 0; return tail == midi->head; } ! --- 1177,1184 ---- /* arg checking */ assert(midi != NULL); ! tail = midi->tail + 1; if (tail == midi->buffer_len) tail = 0; return tail == midi->head; } ! #endif

Index: portmidi.h =================================================================== RCS file: /cvsroot/pure-data/pd/portmidi/pm_common/portmidi.h,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** portmidi.h 15 Dec 2005 00:56:57 -0000 1.1 --- portmidi.h 16 Jan 2008 21:54:10 -0000 1.2 *************** *** 11,15 **** * * 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 --- 11,20 ---- * * Copyright (c) 1999-2000 Ross Bencina and Phil Burk ! * 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 *************** *** 24,31 **** * 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 --- 29,32 ---- *************** *** 35,146 **** * 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: --- 36,54 ---- * 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 ! * (see ../CHANGELOG.txt) * * IMPORTANT INFORMATION ABOUT A WIN32 BUG: *************** *** 150,156 **** * * 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 --- 58,64 ---- * * 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 *************** *** 158,162 **** * exist zombie process that you can't kill. * ! * NOTES ON HOST ERROR REPORTING: * * PortMidi errors (of type PmError) are generic, system-independent errors. --- 66,74 ---- * exist zombie process that you can't kill. * ! * 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. *************** *** 166,181 **** * 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 --- 78,93 ---- * 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 *************** *** 184,213 **** * * 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 --- 96,120 ---- * * 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. ! * 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(). * ! * 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 *************** *** 225,229 **** pmNoError = 0, pmHostError = -10000, ! pmInvalidDeviceId, /* out of range or output device when input is requested or vice versa */ pmInsufficientMemory, pmBufferTooSmall, --- 132,140 ---- pmNoError = 0, pmHostError = -10000, ! 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, *************** *** 232,236 **** pmBadData, /* illegal midi data, e.g. missing EOX */ pmInternalError, ! pmBufferMaxSize, /* buffer is already as large as it can be */ } PmError;

--- 143,148 ---- pmBadData, /* illegal midi data, e.g. missing EOX */ pmInternalError, ! 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;

*************** *** 256,267 **** /* 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 ); --- 168,182 ---- /* 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(). ! 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 ); *************** *** 269,274 ****

/* 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 ); --- 184,189 ----

/* 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 ); *************** *** 276,285 **** /* 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 */

--- 191,200 ---- /* 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 */

*************** *** 293,297 **** #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 */ --- 208,212 ---- #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 */ *************** *** 309,318 **** 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". --- 224,233 ---- 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". *************** *** 328,332 **** 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". --- 243,247 ---- 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". *************** *** 334,350 **** 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 ); --- 249,265 ---- 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 ); *************** *** 392,404 **** 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 --- 307,319 ---- 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 *************** *** 406,415 **** 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 --- 321,330 ---- 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 *************** *** 420,424 **** times are used to schedule outgoing MIDI data (when latency is non-zero).

! time_info is a pointer passed to time_proc.

return value: --- 335,339 ---- times are used to schedule outgoing MIDI data (when latency is non-zero).

! time_info is a pointer passed to time_proc.

return value: *************** *** 429,433 ****

Any stream that is successfully opened should eventually be closed ! by calling Pm_Close().

*/ --- 344,348 ----

Any stream that is successfully opened should eventually be closed ! by calling Pm_Close().

*/ *************** *** 447,451 **** long latency );

! /* Pm_SetFilter() sets filters on an open input stream to drop selected input types. By default, only active sensing messages are filtered. --- 362,366 ---- long latency );

! /* Pm_SetFilter() sets filters on an open input stream to drop selected input types. By default, only active sensing messages are filtered. *************** *** 462,505 ****

/* 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) --- 377,420 ----

/* filter active sensing messages (0xFE): */ ! #define PM_FILT_ACTIVE (1 << 0x0E) /* filter system exclusive messages (0xF0): */ ! #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 (1 << 0x0A) ! /* filter tick messages (0xF9) */ ! #define PM_FILT_TICK (1 << 0x09) /* filter undefined FD messages */ ! #define PM_FILT_FD (1 << 0x0D) /* filter undefined real-time messages */ ! #define PM_FILT_UNDEFINED PM_FILT_FD /* filter reset messages (0xFF) */ ! #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 | PM_FILT_TICK) /* filter note-on and note-off (0x90-0x9F and 0x80-0x8F */ ! #define PM_FILT_NOTE ((1 << 0x19) | (1 << 0x18)) /* filter channel aftertouch (most midi controllers use this) (0xD0-0xDF)*/ ! #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 (1 << 0x1C) /* Control Changes (CC's) (0xB0-0xBF)*/ ! #define PM_FILT_CONTROL (1 << 0x1B) /* Pitch Bender (0xE0-0xEF*/ ! #define PM_FILT_PITCHBEND (1 << 0x1E) /* MIDI Time Code (0xF1)*/ ! #define PM_FILT_MTC (1 << 0x01) /* Song Position (0xF2) */ ! #define PM_FILT_SONG_POSITION (1 << 0x02) /* Song Select (0xF3)*/ ! #define PM_FILT_SONG_SELECT (1 << 0x03) /* Tuning request (0xF6)*/ ! #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) *************** *** 508,512 **** PmError Pm_SetFilter( PortMidiStream* stream, long filters );

- /* Pm_SetChannelMask() filters incoming messages based on channel. --- 423,426 ---- *************** *** 533,541 **** */ 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 ); --- 447,455 ---- */ 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 ); *************** *** 545,549 **** and/or data2 are not present, use zero.

! Pm_MessageStatus(), Pm_MessageData1(), and Pm_MessageData2() extract fields from a long-encoded midi message. */ --- 459,463 ---- and/or data2 are not present, use zero.

! Pm_MessageStatus(), Pm_MessageData1(), and Pm_MessageData2() extract fields from a long-encoded midi message. */ *************** *** 561,576 **** 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.

--- 475,490 ---- 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.

*************** *** 578,588 **** 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 --- 492,502 ---- 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 *************** *** 591,619 **** 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 --- 505,533 ---- 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 *************** *** 628,644 **** /* 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.

--- 542,558 ---- /* 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.

*************** *** 653,670 ****

/* ! 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.

--- 567,584 ----

/* ! 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.

*************** *** 675,681 **** /* 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); --- 589,595 ---- /* 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);

Index: pmutil.h =================================================================== RCS file: /cvsroot/pure-data/pd/portmidi/pm_common/pmutil.h,v retrieving revision 1.1 retrieving revision 1.2 diff -C2 -d -r1.1 -r1.2 *** pmutil.h 15 Dec 2005 00:56:57 -0000 1.1 --- pmutil.h 16 Jan 2008 21:54:10 -0000 1.2 *************** *** 3,6 **** --- 3,10 ---- */

+ #ifdef __cplusplus + extern "C" { + #endif /* __cplusplus */ + typedef void PmQueue;

*************** *** 11,14 **** --- 15,45 ---- fixed sized messages. Returns NULL if memory cannot be allocated.

+ This queue implementation uses the "light pipe" algorithm which + operates correctly even with multi-processors and out-of-order + memory writes. (see Alexander Dokumentov, "Lock-free Interprocess + Communication," Dr. Dobbs Portal, http://www.ddj.com/, + articleID=189401457, June 15, 2006. This algorithm requires + that messages be translated to a form where no words contain + zeros. Each word becomes its own "data valid" tag. Because of + this translation, we cannot return a pointer to data still in + the queue when the "peek" method is called. Instead, a buffer + is preallocated so that data can be copied there. Pm_QueuePeek() + dequeues a message into this buffer and returns a pointer to + it. A subsequent Pm_Dequeue() will copy from this buffer. + + This implementation does not try to keep reader/writer data in + separate cache lines or prevent thrashing on cache lines. + However, this algorithm differs by doing inserts/removals in + units of messages rather than units of machine words. Some + performance improvement might be obtained by not clearing data + immediately after a read, but instead by waiting for the end + of the cache line, especially if messages are smaller than + cache lines. See the Dokumentov article for explanation. + + The algorithm is extended to handle "overflow" reporting. To report + an overflow, the sender writes the current tail position to a field. + The receiver must acknowlege receipt by zeroing the field. The sender + will not send more until the field is zeroed. + Pm_QueueDestroy() destroys the queue and frees its storage. */ *************** *** 20,27 **** Pm_Dequeue() removes one item from the queue, copying it into msg. Returns 1 if successful, and 0 if the queue is empty. ! Returns pmBufferOverflow, clears the overflow flag, and does not ! return a data item if the overflow flag is set. (This protocol ! ensures that the reader will be notified when data is lost due ! to overflow.) */ PmError Pm_Dequeue(PmQueue *queue, void *msg); --- 51,59 ---- Pm_Dequeue() removes one item from the queue, copying it into msg. Returns 1 if successful, and 0 if the queue is empty. ! Returns pmBufferOverflow if what would have been the next thing ! in the queue was dropped due to overflow. (So when overflow occurs, ! the receiver can receive a queue full of messages before getting the ! overflow report. This protocol ensures that the reader will be ! notified when data is lost due to overflow. */ PmError Pm_Dequeue(PmQueue *queue, void *msg); *************** *** 41,45 ****

Either condition may change immediately because a parallel ! enqueue or dequeue operation could be in progress. */ int Pm_QueueFull(PmQueue *queue); --- 73,82 ----

Either condition may change immediately because a parallel ! enqueue or dequeue operation could be in progress. Furthermore, ! Pm_QueueEmpty() is optimistic: it may say false, when due to ! out-of-order writes, the full message has not arrived. Therefore, ! Pm_Dequeue() could still return 0 after Pm_QueueEmpty() returns ! false. On the other hand, Pm_QueueFull() is pessimistic: if it ! returns false, then Pm_Enqueue() is guaranteed to succeed. */ int Pm_QueueFull(PmQueue *queue); *************** *** 50,56 **** Pm_QueuePeek() returns a pointer to the item at the head of the queue, or NULL if the queue is empty. The item is not removed from the queue. ! If queue is in an overflow state, a valid pointer is returned and the ! queue remains in the overflow state. */ void *Pm_QueuePeek(PmQueue *queue);

--- 87,124 ---- Pm_QueuePeek() returns a pointer to the item at the head of the queue, or NULL if the queue is empty. The item is not removed from the queue. ! Pm_QueuePeek() will not indicate when an overflow occurs. If you want ! to get and check pmBufferOverflow messages, use the return value of ! Pm_QueuePeek() *only* as an indication that you should call ! Pm_Dequeue(). At the point where a direct call to Pm_Dequeue() would ! return pmBufferOverflow, Pm_QueuePeek() will return NULL but internally ! clear the pmBufferOverflow flag, enabling Pm_Enqueue() to resume ! enqueuing messages. A subsequent call to Pm_QueuePeek() ! will return a pointer to the first message *after* the overflow. ! Using this as an indication to call Pm_Dequeue(), the first call ! to Pm_Dequeue() will return pmBufferOverflow. The second call will ! return success, copying the same message pointed to by the previous ! Pm_QueuePeek(). ! ! When to use Pm_QueuePeek(): (1) when you need to look at the message ! data to decide who should be called to receive it. (2) when you need ! to know a message is ready but cannot accept the message. ! ! Note that Pm_QueuePeek() is not a fast check, so if possible, you ! might as well just call Pm_Dequeue() and accept the data if it is there. */ void *Pm_QueuePeek(PmQueue *queue);

+ /* + Pm_SetOverflow() allows the writer (enqueuer) to signal an overflow + condition to the reader (dequeuer). E.g. when transfering data from + the OS to an application, if the OS indicates a buffer overrun, + Pm_SetOverflow() can be used to insure that the reader receives a + pmBufferOverflow result from Pm_Dequeue(). Returns pmBadPtr if queue + is NULL, returns pmBufferOverflow if buffer is already in an overflow + state, returns pmNoError if successfully set overflow state. + */ + PmError Pm_SetOverflow(PmQueue *queue); + + #ifdef __cplusplus + } + #endif /* __cplusplus */