wxMidiDevice

The base interface for devices is wxMidiDevice. It is an abstract class with two derived classes:
wxMidiInDevice and wxMidiOutDevice

A wxMidiDevice object represents a MIDI stream on which MIDI data traffic can be read or sent. All MIDI communication is achieved through a wxMidiDevice by using MIDI messages. Devices can be opened and closed, and they provide descriptions of themselves.

MIDI messages are represented by the wxMidiMessage abstract class and are read and sent from/to the MIDI stream by using methods Read and Write, respectively.

For the most common output operations, such as note on or note off, there are specific methods implemented so that wxMidi user has not to build and send the appropriate messages. See: NoteOn, NoteOff, ProgramChange, AllSoundsOff.

Derived from

None

See also

wxMidiInDevice, wxMidiOutDevice, wxMidiMessage, wxMidiSytem, wxMidi quick start

Members

wxMidiDevice::wxMidiDevice
wxMidiDevice::~wxMidiDevice
wxMidiDevice::Close
wxMidiDevice::DeviceName
wxMidiDevice::HasHostError
wxMidiDevice::InterfaceUsed
wxMidiDevice::IsInputPort
wxMidiDevice::IsOutputPort


wxMidiDevice::wxMidiDevice

wxMidiDevice(wxMidiDeviceID nDevice)

Constructor.

 

Parameters

nDevice

 

See also:

wxMidiSystem::CountDevices


wxMidiDevice::~wxMidiDevice

~wxMidiDevice()

Destructor.


wxMidiDevice::Close

wxMidiError Close();

Closes a MIDI stream, flushing any pending messages. Any wxMidiDevice that is successfully opened should eventually be closed calling Close().


wxMidiDevice::DeviceName

const wxString DeviceName()

Returns a string containing the name of the MIDI device. For example "MPU-401 Compatible card".


wxMidiDevice::HasHostError

int HasHostError()

Check if the wxMidiDevice has a pending host error to be reported.

Normally, the application finds out about wxMidi errors through returned error codes, but some errors can occur asynchronously where the application does not explicitly call a function, and therefore cannot receive an error code.

The client can test for a pending error using method HasHostError(). If true, the error can be accessed and cleared by calling wxMidiSystem::GetErrorText. It is nor necessary to call HasHostError() as any pending error will be reported the next time the application performs an explicit function call on the wxMidiDevice, i.e. an input or output operation.


wxMidiDevice::InterfaceUsed

const wxString InterfaceUsed()

Returns a string containing the name of the API used internally to implement MIDI communication. Examples are "MMSystem", "DirectX", "ALSA", "OSS", etc. At present, the only Win32 interface implemented is "MMSystem", the only Linux interface is "ALSA", and the only Max OS X interface is "CoreMIDI".


wxMidiDevice::IsInputPort

bool IsInputPort()

Returns true if the device has input capabilities and then can be used as wxMidiInDevice.


wxMidiDevice::IsOutputPort

bool IsOutputPort()

Returns true if the device has output capabilities and then can be used as wxMidiOutDevice.


wxMidiInDevice

A wxMidiInDevice object represents a MIDI stream on which MIDI data traffic can be read.

Derived from

wxMidiDevice

Members

wxMidiInDevice::wxMidiInDevice
wxMidiInDevice::~wxMidiInDevice
wxMidiInDevice::Flush
wxMidiInDevice::Open
wxMidiInDevice::Poll
wxMidiInDevice::Read
wxMidiInDevice::SetFilter
wxMidiInDevice::SetChannelMask
wxMidiInDevice::StartListening
wxMidiInDevice::StopListening


wxMidiInDevice::wxMidiInDevice

wxMidiInDevice(wxMidiDeviceID nDevice)

Constructor.

 

Parameters

nDevice

 

See also:

wxMidiSystem::CountDevices


wxMidiInDevice::~wxMidiInDevice

~wxMidiInDevice()

Destructor.


wxMidiInDevice::Flush

void Flush()

Discard any MIDI messages waiting to be read.


wxMidiInDevice::Open

wxMidiError Open(void *pDriverInfo = NULL)

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().

 

Parameters

pDriverInfo


wxMidiInDevice::Poll

wxMidiError Poll()

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 ocurred.


wxMidiInDevice::Read

wxMidiMessage* 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.

 

Parameters

pError

 

wxMidiError Read(PmEvent *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, probably, it will be deleted in future versions of wxMidi.

 

Remarks

If there is an overflow in the internal buffer managed by PortMidi, the buffer will be flushed when an the next Read() operetaion will fail with error code wxMIDI_ERROR_BufferOverflow. Normal operation resumes as soon as a new message arrives. The remainder of any partial sysex message will not be considered to be a "new message" and will be flushed as well.


wxMidiInDevice::SetFilter

wxMidiError SetFilter( long filters )

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.

 

Parameters

filters

 

Example

// Let's filter out active sensing and sysex messages
pMidiIn->SetFilter(wxMIDI_FILT_ACTIVE | wxMIDI_FILT_SYSEX);


wxMidiInDevice::SetChannelMask

wxMidiError SetChannelMask( long mask )

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.


wxMidiInDevice::StartListening

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().

 

Parameters

pWindow

nPollingRate

 

Remarks

This method is useful for dealing with input messages by means of an event handler. See Receiving MIDI messages for an example.


wxMidiInDevice::StopListening

wxMidiError StopListening()

Stops a listener thread created in a previous call to wxMidiInDevice::StartListening.


wxMidiOutDevice

A wxMidiOutDevice object represents a MIDI stream on which MIDI data traffic can be sent..

Derived from

wxMidiDevice

Members

wxMidiOutDevice::wxMidiOutDevice
wxMidiOutDevice::~wxMidiOutDevice
wxMidiOutDevice::Abort
wxMidiOutDevice::AllSoundsOff
wxMidiOutDevice::NoteOff
wxMidiOutDevice::NoteOn
wxMidiOutDevice::Open
wxMidiOutDevice::ProgramChange
wxMidiOutDevice::Write


wxMidiOutDevice::wxMidiOutDevice

wxMidiOutDevice(wxMidiDeviceID nDevice)

Constructor.

 

Parameters

nDevice

 

See also:

wxMidiSystem::CountDevices


wxMidiOutDevice::~wxMidiOutDevice

~wxMidiOutDevice()

Destructor.


wxMidiOutDevice::Abort

wxMidiError Abort()

Terminates any outgoing message immediately; this call may result in a partial transmission of a MIDI message. The caller should immediately close the output port .


wxMidiOutDevice::AllSoundsOff

wxMidiError AllSoundsOff()

From time to time, specially during user application debugging, you may encounter a situation in which a MIDI synthesizer sounds as if its keys are "stuck," and it plays continuously as though someone's still pressing them. Method AllSoundsOff() sends the MIDI device a signal that tells it to stop inmediatelly all sounds.


wxMidiOutDevice::NoteOn

wxMidiError NoteOn(int channel, int note, int velocity)

Prepares and sends a NoteOn MIDI message.

Parameters

channel

note

velocity

 

Remarks

You must be aware that in MIDI systems, the activation of a particular note and the release of the same note are considered as two separate events. So, after calling method NoteOn() it is necessary to call later to method NoteOff() to stop the sound generator, even if the sound produced by the NoteOn() command is no longer audible due to natural soud extintion because of the chosen intrument (i.e.piano or percussion instruments).


wxMidiOutDevice::NoteOff

wxMidiError NoteOff(int channel, int note, int velocity)

Prepares and sends a NoteOff MIDI message. It is normally used to stop a sound started by a previous call to NoteOn().

Parameters

channel

note

velocity


wxMidiOutDevice::Open

wxMidiError Open(long latency, void * pDriverInfo = NULL)

This methods opens a wxMidiOutDevice stream so that it can be used.

Parameters

latency

pDriverInfo

Return value

Upon success Open() returns zero (wxMIDI_NO_ERROR). If a call to Open() fails a nonzero error code is returned.


wxMidiOutDevice::ProgramChange

wxMidiError ProgramChange(int channel, int instrument)

Prepares and sends a ProgramChange MIDI message. This message is used to change the sound (instrument) assigned to a channel.

Parameters

channel

instrument

 

See also:

wxMidiDatabaseGM


wxMidiOutDevice::Write

wxMidiError Write(wxMidiShortMessage* pMsg)

wxMidiError Write(wxMidiSysExMessage* pMsg)

wxMidiError Write(wxByte* pBytes, wxMidiTimestamp when=0)

Sends a MIDI message to the MIDI device represented by the wxMidiOutDevice object.

Parameters

pMsg

pBytes

when

 

An additional Write method is provided:

wxMidiError Write(PmEvent* buffer, long length)

This method is just a wrapper for the portmidi native Write function. This method is provided in case it is needed but, probably, it will be deleted in future versions of wxMidi.