 |
wxMidi - A MIDI interface based on PortMidi
|
|
wxMidi - A MIDI interface based on PortMidi
|
Represents a MIDI stream on which MIDI data traffic can be read. More...
#include <wxMidi.h>
Public Member Functions | |
| wxMidiInDevice (wxMidiDeviceID nDevice, double timeoutSeconds=5.0) | |
| Constructor. More... | |
| ~wxMidiInDevice () | |
| Destructor. | |
| wxMidiError | Open (void *pDriverInfo=NULL, int buffersize=4096) |
| Open the device, so that the device can be used. More... | |
| wxMidiMessage * | Read (wxMidiError *pError) |
| Retrieves a received MIDI message and modifies value of variable pointed by pError to leave an error code. More... | |
| wxMidiError | Read (wxMidiPmEvent *buffer, long *length) |
| This second Read operation is just a wrapper for the portmidi native Read function. More... | |
| wxMidiError | SetFilter (long filters) |
| Sets filters on an open wxMidiInDevice to drop selected input types. More... | |
| wxMidiError | SetChannelMask (long mask) |
| SetChannelMask() filters incoming messages based on channel. More... | |
| wxMidiError | Poll () |
| Check if there is a received MIDI message waiting to be Read(). More... | |
| void | Flush () |
| Discard any MIDI messages waiting to be read. | |
| wxMidiError | StartListening (wxWindow *pWindow, unsigned long nPollingRate=50) |
| This method creates and starts a thread to call Poll() method every nPollingRate milliseconds, and trigger a wxEVT_MIDI_INPUT command event if a MIDI message has been received and is waiting to be Read(). More... | |
| wxMidiError | StopListening () |
| Stops a listener thread created in a previous call to wxMidiInDevice::StartListening(). More... | |
 Public Member Functions inherited from wxMidiDevice | |
| wxMidiDevice (wxMidiDeviceID nDevice) | |
| Constructor. More... | |
| virtual | ~wxMidiDevice () |
| Destructor. | |
| wxMidiError | Close () |
| Closes a MIDI stream, flushing any pending messages. More... | |
| const wxString | DeviceName () |
| Returns a string containing the name of the MIDI device. More... | |
| const wxString | InterfaceUsed () |
| Returns a string containing the name of the API used internally by portmidi to implement MIDI communication. More... | |
| bool | IsInputPort () |
| Returns true if the device has input capabilities and then can be used as wxMidiInDevice. More... | |
| bool | IsOutputPort () |
| Returns true if the device has output capabilities and then can be used as wxMidiOutDevice. More... | |
| int | HasHostError () |
| Check if the wxMidiDevice has a pending host error to be reported. More... | |
Additional Inherited Members | |
| Protected Attributes inherited from wxMidiDevice | |
| wxMidiDeviceID | m_nDevice |
| const PmDeviceInfo * | m_pInfo |
| PortMidiStream * | m_stream |
Represents a MIDI stream on which MIDI data traffic can be read.
| wxMidiInDevice::wxMidiInDevice | ( | wxMidiDeviceID | nDevice, |
| double | timeoutSeconds = 5.0 |
||
| ) |
Constructor.
| nDevice | The number of the device. Device numbers (also referred as device IDs) range from 0 to wxMidiSystem::CountDevices() - 1 |
| timeoutSeconds | Specifies the maximum wait time without receiving more data for aborting an incomplete SysEx message reception. This will happen if a SysEx message reception is interrupted (i.e. the MIDI cable is accidentally unplugged). |
| wxMidiError wxMidiInDevice::Open | ( | void * | pDriverInfo = NULL, |
| int | buffersize = 4096 |
||
| ) |
Open the device, so that the device can be used.
Upon success Open() returns zero (wxMIDI_NO_ERROR). If the open process fails a non-zero error code is returned.
Any successfully opened device should eventually be closed calling Close().
| pDriverInfo | It is a pointer to an optional driver specific data structure containing additional information for device setup or handle processing. pDriverInfo is never required for correct operation. If not used pDriverInfo should be NULL. |
| buffersize | The portmidi library doesn't allow for dynamic buffer allocation. Therefore, you should allocate enough space for the largest SysEx message you expect to receive. As each slot of a portmidi buffer holds 4 SysEx bytes, buffersize parameter must be something like the maximum SysEx message length in bytes divided by 4. The default value allows to receive at least 16KB long SysEx messages. |
portmidi uses an 'int' for specifying buffer size. This introduces an apparent limitation to approx. 128KB SysEx messages (32KB x 4). But as MIDI data transfer rate is 3.8 KB/sec, in principle wxMidi will read arriving bytes much faster. So, in practice, the default value for the portmidi buffersize should not cause any limitation for receiving SysEx messages of any length.
|
inline |
Check if there is a received MIDI message waiting to be Read().
It returns TRUE if there are messages waiting, FALSE if not, or an error value if an error occurred.
| wxMidiMessage * wxMidiInDevice::Read | ( | wxMidiError * | pError | ) |
Retrieves a received MIDI message and modifies value of variable pointed by pError to leave an error code.
On success, a pointer to a MIDI message (either wxMIDIShortMessage or wxMidiSysExMessage) is returned and value zero (wxMIDI_NO_ERROR) is left in *pError. If any error occurs, a NULL pointer is returned and the error code is left in *pError.
| pError | Pointer to an wxMidiError variable in which to leave the error code for the Read operation. |
| wxMidiError wxMidiInDevice::Read | ( | wxMidiPmEvent * | buffer, |
| long * | length | ||
| ) |
This second Read operation is just a wrapper for the portmidi native Read function.
This method is provided in case it is needed but it should not be required.
|
inline |
SetChannelMask() filters incoming messages based on channel.
The mask is a 16-bit bitfield corresponding to appropriate channels. By default, messages for all channels are allowed. Macro wxMIDI_CHANNEL can assist in preparing this mask.
|
inline |
Sets filters on an open wxMidiInDevice to drop selected input types.
By default, active sensing messages are filtered. To allow all messages you have to call SetFilter(wxMIDI_NO_FILTER).
Filtering is useful when midi routing or midi thru functionality is being provided by the user application. For example, you may want to exclude timing messages (clock, MTC, start/stop/continue), while allowing note-related messages to pass. Or you may be using a sequencer or drum-machine for MIDI clock information but want to exclude any notes it may play.
| filters | Filter codes combined with the OR operator (|). See filter_codes |
Example:
| wxMidiError wxMidiInDevice::StartListening | ( | wxWindow * | pWindow, |
| unsigned long | nPollingRate = 50 |
||
| ) |
This method creates and starts a thread to call Poll() method every nPollingRate milliseconds, and trigger a wxEVT_MIDI_INPUT command event if a MIDI message has been received and is waiting to be Read().
| pWindow | Pointer to window that will receive the wxEVT_MIDI_INPUT command events. |
| nPollingRate | Polling interval, in milliseconds. |
Remarks: This method is useful for dealing with input messages by means of an event handler. See Receiving messages for an example.
| wxMidiError wxMidiInDevice::StopListening | ( | ) |
Stops a listener thread created in a previous call to wxMidiInDevice::StartListening().
1.8.13