Events and Filters Handling

Classes
struct	PmEvent
	All midi data comes in the form of PmEvent structures. More...

Macros
#define	PM_FILT_ACTIVE   (1 << 0x0E)
	filter active sensing messages (0xFE):
#define	PM_FILT_SYSEX   (1 << 0x00)
	filter system exclusive messages (0xF0):
#define	PM_FILT_CLOCK   (1 << 0x08)
	filter MIDI clock message (0xF8)
#define	PM_FILT_PLAY   ((1 << 0x0A) | (1 << 0x0C) | (1 << 0x0B))
	filter play messages (start 0xFA, stop 0xFC, continue 0xFB)
#define	PM_FILT_TICK   (1 << 0x09)
	filter tick messages (0xF9)
#define	PM_FILT_FD   (1 << 0x0D)
	filter undefined FD messages
#define	PM_FILT_UNDEFINED   PM_FILT_FD
	filter undefined real-time messages
#define	PM_FILT_RESET   (1 << 0x0F)
	filter reset messages (0xFF)
#define	PM_FILT_REALTIME
	filter all real-time messages More...
#define	PM_FILT_NOTE   ((1 << 0x19) | (1 << 0x18))
	filter note-on and note-off (0x90-0x9F and 0x80-0x8F
#define	PM_FILT_CHANNEL_AFTERTOUCH   (1 << 0x1D)
	filter channel aftertouch (most midi controllers use this) (0xD0-0xDF)
#define	PM_FILT_POLY_AFTERTOUCH   (1 << 0x1A)
	per-note aftertouch (0xA0-0xAF)
#define	PM_FILT_AFTERTOUCH
	filter both channel and poly aftertouch More...
#define	PM_FILT_PROGRAM   (1 << 0x1C)
	Program changes (0xC0-0xCF)
#define	PM_FILT_CONTROL   (1 << 0x1B)
	Control Changes (CC's) (0xB0-0xBF)
#define	PM_FILT_PITCHBEND   (1 << 0x1E)
	Pitch Bender (0xE0-0xEF.
#define	PM_FILT_MTC   (1 << 0x01)
	MIDI Time Code (0xF1)
#define	PM_FILT_SONG_POSITION   (1 << 0x02)
	Song Position (0xF2)
#define	PM_FILT_SONG_SELECT   (1 << 0x03)
	Song Select (0xF3)
#define	PM_FILT_TUNE   (1 << 0x06)
	Tuning request (0xF6)
#define	PM_FILT_SYSTEMCOMMON
	All System Common messages (mtc, song position, song select, tune request) More...
#define	Pm_Channel(channel)   (1<<(channel))
	Create a mask that filters one channel.
#define	Pm_Message(status, data1, data2)
	Encode a short Midi message into a 32-bit word. More...
#define	Pm_MessageStatus(msg)   ((msg) & 0xFF)
	Extract the status field from a 32-bit midi message.
#define	Pm_MessageData1(msg)   (((msg) >> 8) & 0xFF)
	Extract the 1st data field (e.g., pitch) from a 32-bit midi message.
#define	Pm_MessageData2(msg)   (((msg) >> 16) & 0xFF)
	Extract the 2nd data field (e.g., velocity) from a 32-bit midi message.

Typedefs
typedef int32_t	PmMessage
	see PmEvent

Functions
PMEXPORT PmError	Pm_SetFilter (PortMidiStream *stream, int32_t filters)
PMEXPORT PmError	Pm_SetChannelMask (PortMidiStream *stream, int mask)
	Filter incoming messages based on channel. More...
PMEXPORT PmError	Pm_Abort (PortMidiStream *stream)
	Terminate outgoing messages immediately. More...
PMEXPORT PmError	Pm_Close (PortMidiStream *stream)
	Close a midi stream, flush any pending buffers if possible. More...
PMEXPORT PmError	Pm_Synchronize (PortMidiStream *stream)
	(re)synchronize to the time_proc passed when the stream was opened. More...

Detailed Description

Macro Definition Documentation

PM_FILT_AFTERTOUCH

#define PM_FILT_AFTERTOUCH

Value:

                            (PM_FILT_CHANNEL_AFTERTOUCH | \
                            PM_FILT_POLY_AFTERTOUCH)

filter both channel and poly aftertouch

PM_FILT_REALTIME

#define PM_FILT_REALTIME

Value:

    (PM_FILT_ACTIVE | PM_FILT_SYSEX | PM_FILT_CLOCK | \
    PM_FILT_PLAY | PM_FILT_UNDEFINED | PM_FILT_RESET | PM_FILT_TICK)

filter all real-time messages

PM_FILT_SYSTEMCOMMON

#define PM_FILT_SYSTEMCOMMON

Value:

                              (PM_FILT_MTC | PM_FILT_SONG_POSITION | \
                              PM_FILT_SONG_SELECT | PM_FILT_TUNE)

All System Common messages (mtc, song position, song select, tune request)

Pm_Message

#define Pm_Message	(		status,
			data1,
			data2
	)

Value:

         ((((data2) << 16) & 0xFF0000) | \
          (((data1) << 8) & 0xFF00) | \
          ((status) & 0xFF))

Encode a short Midi message into a 32-bit word.

If data1 and/or data2 are not present, use zero.

Function Documentation

Pm_Abort()

PMEXPORT PmError Pm_Abort

(

PortMidiStream *

stream

)

Terminate outgoing messages immediately.

Parameters

stream

an open MIDI output stream.

Returns

pmNoError or an error code.

The caller should immediately close the output port; this call may result in transmission of a partial MIDI message. There is no abort for Midi input because the user can simply ignore messages in the buffer and close an input device at any time. If the specified behavior cannot be achieved through the system-level interface (ALSA, CoreMIDI, etc.), the behavior may be that of Pm_Close().

Pm_Close()

PMEXPORT PmError Pm_Close

(

PortMidiStream *

stream

)

Close a midi stream, flush any pending buffers if possible.

Parameters

stream

an open MIDI input or output stream.

Returns

pmNoError or an error code.

If the system-level interface (ALSA, CoreMIDI, etc.) does not support flushing remaining messages, the behavior may be one of the following (most preferred first): block until all pending timestamped messages are delivered; deliver messages to a server or kernel process for later delivery but return immediately; drop messages (as in Pm_Abort()). Therefore, to be safe, applications should wait until the output queue is empty before calling Pm_Close(). E.g. calling Pt_Sleep(100 + latency); will give a 100ms "cushion" beyond latency (if any) before closing.

Pm_SetChannelMask()

PMEXPORT PmError Pm_SetChannelMask	(	PortMidiStream *	stream,
		int	mask
	)

Filter incoming messages based on channel.

Parameters

stream	an open MIDI input stream.
mask	indicates channels to be received.

Returns

pmNoError or an error code.

The mask is a 16-bit bitfield corresponding to appropriate channels. The Pm_Channel macro can assist in calling this function. I.e. to receive only input on channel 1, call with Pm_SetChannelMask(Pm_Channel(1)); Multiple channels should be OR'd together, like Pm_SetChannelMask(Pm_Channel(10) | Pm_Channel(11))

Note that channels are numbered 0 to 15 (not 1 to 16). Most synthesizer and interfaces number channels starting at 1, but PortMidi numbers channels starting at 0.

All channels are allowed by default

Pm_Synchronize()

PMEXPORT PmError Pm_Synchronize

(

PortMidiStream *

stream

)

(re)synchronize to the time_proc passed when the stream was opened.

Parameters

stream

an open MIDI input or output stream.

Returns

pmNoError or an error code.

Typically, this is used when the stream must be opened before the time_proc reference is actually advancing. In this case, message timing may be erratic, but since timestamps of zero mean "send immediately," initialization messages with zero timestamps can be written without a functioning time reference and without problems. Before the first MIDI message with a non-zero timestamp is written to the stream, the time reference must begin to advance (for example, if the time_proc computes time based on audio samples, time might begin to advance when an audio stream becomes active). After time_proc return values become valid, and BEFORE writing the first non-zero timestamped MIDI message, call Pm_Synchronize() so that PortMidi can observe the difference between the current time_proc value and its MIDI stream time.

In the more normal case where time_proc values advance continuously, there is no need to call Pm_Synchronize. PortMidi will always synchronize at the first output message and periodically thereafter.