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(wxMidiDeviceID nDevice)
Constructor.
Parameters
nDevice
See also:
~wxMidiDevice()
Destructor.
Closes a MIDI stream, flushing any pending messages. Any wxMidiDevice that is successfully opened should eventually be closed calling Close().
Returns a string containing the name of the MIDI device. For example "MPU-401 Compatible card".
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.
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".
Returns true if the device has input capabilities and then can be used as wxMidiInDevice.
Returns true if the device has output capabilities and then can be used as wxMidiOutDevice.
Derived from
Members
wxMidiInDevice::wxMidiInDevice
wxMidiInDevice::~wxMidiInDevice
wxMidiInDevice::Flush
wxMidiInDevice::Open
wxMidiInDevice::Poll
wxMidiInDevice::Read
wxMidiInDevice::SetFilter
wxMidiInDevice::SetChannelMask
wxMidiInDevice::StartListening
wxMidiInDevice::StopListening
Constructor.
Parameters
nDevice
See also:
Destructor.
Discard any MIDI messages waiting to be read.
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
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.
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.
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);
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.
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.
Stops a listener thread created in a previous call to wxMidiInDevice::StartListening.
Derived from
Members
wxMidiOutDevice::wxMidiOutDevice
wxMidiOutDevice::~wxMidiOutDevice
wxMidiOutDevice::Abort
wxMidiOutDevice::AllSoundsOff
wxMidiOutDevice::NoteOff
wxMidiOutDevice::NoteOn
wxMidiOutDevice::Open
wxMidiOutDevice::ProgramChange
wxMidiOutDevice::Write
Constructor.
Parameters
nDevice
See also:
Destructor.
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 .
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.
Prepares and sends a NoteOn MIDI message.
Parameters
channel
velocity
OFF | ppp | pp | p | mp | mf | f | ff | fff |
0 | 1 | 2 | 4 | 8 | 16 | 32 | 64 | 127 |
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).
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
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.
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:
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.