libkmid Library API Documentation

DeviceManager Class Reference

MIDI Device Manager class . Manages all MIDI devices and redirects MIDI events to each one as configured. More...

#include <deviceman.h>

List of all members.

Public Methods

 DeviceManager (int def=-1)
 Constructor.

 ~DeviceManager (void)
 Destructor.

int initManager (void)
 Initializes the MIDI Device Manager object.

int checkInit (void)
 Checks if the device manager has been initialized (with @initManager), and in case it wasn't, initializes it.

MidiOutchntodev (int chn)
 Obsolete.

MidiOutdeviceForChannel (int chn)
 It's possible to send different MIDI channels to different MIDI devices, so that you can for example send channel 1 to an external synthesizer, channel 2 to a FM device and channel 10 to an AWE synth.

int deviceNumberForChannel (int chn)
 Returns the device number associated with a given channel.

void setDeviceNumberForChannel (int chn, int dev)
 Sets the device number associated with a given channel.

int ok (void)
int usingAlsa (void)
 Returns true if it's running ALSA and false if OSS is being run.

void openDev (void)
 Open the devices.

void closeDev (void)
 Closes the devices, and /dev/sequencer.

void initDev (void)
 Calls MidiOut::initDev() in turn in each of the available devices.

void noteOn (uchar chn, uchar note, uchar vel)
 Sends a Note On MIDI event.

void noteOff (uchar chn, uchar note, uchar vel)
 Sends a Note Off MIDI event.

void keyPressure (uchar chn, uchar note, uchar vel)
 Sends a Key Pressure (or Aftertouch) MIDI event.

void chnPatchChange (uchar chn, uchar patch)
 Changes the patch (instrument) on a MIDI channel.

void chnPressure (uchar chn, uchar vel)
 Changes the Pressure (Aftertouch) on a MIDI channel.

void chnPitchBender (uchar chn, uchar lsb, uchar msb)
 Changes the Pitch Bender value on a MIDI channel.

void chnController (uchar chn, uchar ctl, uchar v)
 Sends a Controller event to a MIDI channel.

void sysEx (uchar *data, ulong size)
 Sends a SYStem EXclusive message to the default MIDI device (usually, external MIDI synths, as most internal synths do not support sysex messages).

void wait (double ms)
 Sets the number of milliseconds at which the next event will be sent.

void tmrSetTempo (int v)
 Sets the tempo which will be used to convert between ticks and milliseconds.

void tmrStart (long int tpcn)
 Starts the timer.

void tmrStop (void)
 Stops the timer.

void tmrContinue (void)
 Continue the stopped timer .

void allNotesOff (void)
 Sends an all notes off event.

void sync (bool f=0)
 Synchronizes with the MIDI buffer.

void setVolumePercentage (int i)
 Changes the "master" volume of the played events by altering next volume controller events.

int defaultDevice (void)
 Returns the device to which the MIDI events will be sent.

void setDefaultDevice (int i)
 Sets the device to send the MIDI events to.

int setPatchesToUse (int *patchesused)
 Loads the patches you're going to use .

const char * midiMapFilename (void)
 Returns the filename where the Midi Mapper was loaded from, or "" if no MIDI Mapper is in use.

void setMidiMap (MidiMapper *map)
 Sets a MidiMapper object to use.

int rate (void)
 Returns the SNDCTL_SEQ_CTRLRATE ioctl value.

int midiPorts (void)
 Returns the number of MIDI ports available on the system.

int synthDevices (void)
 Returns the number of internal synthesizers available on the system.

const char * name (int i)
 Returns the name of the i-th device .

const char * type (int i)
 Returns the type of device the i-th device is , in a user-friendly string .


Detailed Description

MIDI Device Manager class . Manages all MIDI devices and redirects MIDI events to each one as configured.

This class is the one you should use to send MIDI events to any device, as it creates and manages the *Out classes.

This class is usually used by creating a DeviceManager object, then call openDev() and initDev() . Then, use numberOfMidiPorts(), numberOfSynthDevices(), name() and type() to choose which device to play MIDI events to and then use defaultDevice() to set the MIDI device to play.

Version:
0.9.5 17/01/2000
Author:
Antonio Larrosa Jimenez <larrosa@kde.org>

Definition at line 46 of file deviceman.h.


Constructor & Destructor Documentation

DeviceManager::DeviceManager int    def = -1
 

Constructor.

It just initializes internal variables, before playing any music, you should call initManager(), setMidiMap() (optional), openDev(), initDev(), setPatchesToUse() (not required, unless you're playing to a GUS device, which must load the patches), tmrStart(), and finally, play the music.

Definition at line 104 of file deviceman.cc.

References QString::find(), QString::isEmpty(), and QString::mid().

DeviceManager::~DeviceManager void   
 

Destructor.

It closes the device (calling closeDev() ) if it wasn't closed before.

Definition at line 149 of file deviceman.cc.

References closeDev().


Member Function Documentation

int DeviceManager::initManager void   
 

Initializes the MIDI Device Manager object.

The /dev/sequencer and/or /dev/snd/seq files are opened, available devices are analyzed and *Out objects are created. Then, the device files are closed.

Returns:
0 if everything was OK, or -1 if there was an error and it couldn't be initialized (for example, because it couldn't open the /dev/sequencer file)

Definition at line 199 of file deviceman.cc.

References KStdAccel::close(), name(), KStdAccel::open(), and setMidiMap().

Referenced by checkInit().

int DeviceManager::checkInit void   
 

Checks if the device manager has been initialized (with @initManager), and in case it wasn't, initializes it.

Returns:
0 if it was (or has just been) correctly initialized, and -1 if there was an error.

Definition at line 172 of file deviceman.cc.

References initManager().

Referenced by name(), openDev(), setPatchesToUse(), and type().

MidiOut* DeviceManager::chntodev int    chn [inline]
 

Obsolete.

Please use deviceForChannel() instead.

Definition at line 205 of file deviceman.h.

References deviceForChannel().

Referenced by chnController(), chnPatchChange(), chnPitchBender(), chnPressure(), keyPressure(), noteOff(), and noteOn().

MidiOut* DeviceManager::deviceForChannel int    chn [inline]
 

It's possible to send different MIDI channels to different MIDI devices, so that you can for example send channel 1 to an external synthesizer, channel 2 to a FM device and channel 10 to an AWE synth.

Returns:
the device to which MIDI events goind to channel chn should be sent.

Definition at line 216 of file deviceman.h.

Referenced by chntodev().

int DeviceManager::deviceNumberForChannel int    chn [inline]
 

Returns the device number associated with a given channel.

Definition at line 222 of file deviceman.h.

void DeviceManager::setDeviceNumberForChannel int    chn,
int    dev
 

Sets the device number associated with a given channel.

Definition at line 817 of file deviceman.cc.

int DeviceManager::ok void   
 

Returns:
0 if there was a problem and 1 if everything was OK. Note that the return value is changed after you check it, so you can only check it once.

Definition at line 165 of file deviceman.cc.

Referenced by MidiPlayer::play().

int DeviceManager::usingAlsa void    [inline]
 

Returns true if it's running ALSA and false if OSS is being run.

Definition at line 238 of file deviceman.h.

void DeviceManager::openDev void   
 

Open the devices.

It first initializes the manager it that wasn't done yet (you should do it yourself, to be able to choose the MIDI output device, as it will be set to an external synth by default, if available).

Then /dev/sequencer is opened and the MIDI devices are opened (calling MidiOut::openDev() ).

See also:
ok() to check if there was any problem , closeDev() , initDev()

Definition at line 394 of file deviceman.cc.

References checkInit(), MidiOut::closeDev(), MidiOut::ok(), KStdAccel::open(), and MidiOut::openDev().

Referenced by MidiPlayer::play().

void DeviceManager::closeDev void   
 

Closes the devices, and /dev/sequencer.

See also:
openDev()

Definition at line 445 of file deviceman.cc.

References KStdAccel::close(), MidiOut::closeDev(), and tmrStop().

Referenced by MidiPlayer::play(), and ~DeviceManager().

void DeviceManager::initDev void   
 

Calls MidiOut::initDev() in turn in each of the available devices.

See also:
MidiOut::initDev()

Definition at line 478 of file deviceman.cc.

References MidiOut::initDev().

Referenced by MidiPlayer::play().

void DeviceManager::noteOn uchar    chn,
uchar    note,
uchar    vel
 

Sends a Note On MIDI event.

Parameters:
chn  the MIDI channel (0 to 15) to play the note on.
note  the key of the note to play (0 to 127).
vel  the velocity of the note (0 to 127).
See also:
noteOff()

Definition at line 492 of file deviceman.cc.

References chntodev(), and MidiOut::noteOn().

Referenced by MidiPlayer::play().

void DeviceManager::noteOff uchar    chn,
uchar    note,
uchar    vel
 

Sends a Note Off MIDI event.

This is equivalent to send a Note On event with a vel value of 0.

Parameters:
chn  the MIDI channel (0 to 15) to play the note on.
note  the key of the note to play (0 to 127).
vel  the velocity of the note (0 to 127).
See also:
noteOn()

Definition at line 497 of file deviceman.cc.

References chntodev(), and MidiOut::noteOff().

Referenced by MidiPlayer::play().

void DeviceManager::keyPressure uchar    chn,
uchar    note,
uchar    vel
 

Sends a Key Pressure (or Aftertouch) MIDI event.

This event changes the pressure over a key after this key has been played.

Parameters:
chn  the MIDI channel (0 to 15) where the note is being played.
note  the key of the note (0 to 127).
vel  the new velocity (or pressure) of the note (0 to 127).

Definition at line 502 of file deviceman.cc.

References chntodev(), and MidiOut::keyPressure().

Referenced by MidiPlayer::play().

void DeviceManager::chnPatchChange uchar    chn,
uchar    patch
 

Changes the patch (instrument) on a MIDI channel.

See also:
setPatchesToUse()
Parameters:
chn  the MIDI channel (0 to 15) .
patch  the General Midi patch (0 to 127) to use on the channel chn.

Definition at line 507 of file deviceman.cc.

References MidiOut::chnPatchChange(), and chntodev().

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::chnPressure uchar    chn,
uchar    vel
 

Changes the Pressure (Aftertouch) on a MIDI channel.

Keep in mind that some synthesizers don't like this events, and it's better not to send it.

Parameters:
chn  the MIDI channel (0 to 15) to change.
vel  the velocity (0 to 127) to use on the channel chn.

Definition at line 512 of file deviceman.cc.

References MidiOut::chnPressure(), and chntodev().

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::chnPitchBender uchar    chn,
uchar    lsb,
uchar    msb
 

Changes the Pitch Bender value on a MIDI channel.

This bends the tone of each note played on this channel.

Parameters:
chn  the MIDI channel (0 to 15) to use.
lsb  and msb the less significant byte and the most significant byte (0 to 127 each) of the number by which notes will be bend. a 0x4000 value means not to bend.

Definition at line 517 of file deviceman.cc.

References MidiOut::chnPitchBender(), and chntodev().

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::chnController uchar    chn,
uchar    ctl,
uchar    v
 

Sends a Controller event to a MIDI channel.

This can be used for example to change the volume, set a XG patch, etc. Look for any General Midi resource page on the net for more information about the available controller events.

For example, to set the tremolo value to a maximum on the MIDI channel number one, you should pass 1 to chn, 1 to ctl and 127 to v.

Parameters:
chn  the MIDI channel (0 to 15) to send the event to.
ctl  the controller (0 to 15) to send.
v  the value (data) of the controller.

Definition at line 522 of file deviceman.cc.

References MidiOut::chnController(), and chntodev().

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::sysEx uchar *    data,
ulong    size
 

Sends a SYStem EXclusive message to the default MIDI device (usually, external MIDI synths, as most internal synths do not support sysex messages).

Parameters:
data  the array of bytes that comform the system exclusive message. Without the initial 0xF0 char, and including the final 0xF7 char (end of exclusive message)
size  the size in bytes of the data to send
See also:
setDefaultDevice()

Definition at line 527 of file deviceman.cc.

References MidiOut::sysex().

void DeviceManager::wait double    ms
 

Sets the number of milliseconds at which the next event will be sent.

This way, you can schedule notes and events to send to the MIDI device.

See also:
tmrStart()

Definition at line 533 of file deviceman.cc.

Referenced by MidiPlayer::play().

void DeviceManager::tmrSetTempo int    v
 

Sets the tempo which will be used to convert between ticks and milliseconds.

Definition at line 549 of file deviceman.cc.

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::tmrStart long int    tpcn
 

Starts the timer.

You must call tmrStart before using wait()

Definition at line 561 of file deviceman.cc.

Referenced by MidiPlayer::play().

void DeviceManager::tmrStop void   
 

Stops the timer.

This will be called by closeDev() before closing the device

Definition at line 587 of file deviceman.cc.

Referenced by closeDev(), and MidiPlayer::play().

void DeviceManager::tmrContinue void   
 

Continue the stopped timer .

It is the same than starting a new timer, but without resetting it.

Definition at line 608 of file deviceman.cc.

void DeviceManager::allNotesOff void   
 

Sends an all notes off event.

Definition at line 822 of file deviceman.cc.

References MidiOut::allNotesOff().

Referenced by MidiPlayer::play().

void DeviceManager::sync bool    f = 0
 

Synchronizes with the MIDI buffer.

Midi events are put into a buffer, along with timer delays (see wait() ). sync returns when the buffer is empty.

Parameters:
f  if false, it syncronizes by waiting for the buffer to be sent. If true, it forces the synchronization by clearing the buffer inmediately. The "force" method is, of course, not recommended, except in rare situations.

Definition at line 628 of file deviceman.cc.

Referenced by MidiPlayer::play(), and MidiStatus::sendData().

void DeviceManager::setVolumePercentage int    i
 

Changes the "master" volume of the played events by altering next volume controller events.

The parameter i should be in the range of 0 (nothing is heard) to 150 (music is played at a 150% of the original volume).

Keep in mind that as most MIDI files already play music at near the maximum volume, an i value greater than 100 is very probably ignored most of the times.

Definition at line 806 of file deviceman.cc.

References MidiOut::setVolumePercentage().

Referenced by MidiPlayer::play().

int DeviceManager::defaultDevice void   
 

Returns the device to which the MIDI events will be sent.

Returns -1 if there's no available device.

See also:
setDefaultDevice()

Definition at line 762 of file deviceman.cc.

void DeviceManager::setDefaultDevice int    i
 

Sets the device to send the MIDI events to.

By using midiPorts(), synthDevices(), name() and type(), you should choose which device to use (note that they are numbered with midi ports being first and synth devices next)

See also:
defaultDevice()

Definition at line 767 of file deviceman.cc.

int DeviceManager::setPatchesToUse int *    patchesused
 

Loads the patches you're going to use .

This has effect only for GUS cards, although, if you use this function when defaultDevice() is not a GUS device, it will be ignored.

The parameter is an int [256] array, which contain the following:

The first 0..127 integers, are the number of times each General MIDI patch will be used, and -1 when the corresponding patch won't be used.

The 128..255 integers are the number of times each drum voice (each note on the drum channel) will be used, and -1 when the corresponding percussion won't be used.

This is done this way so that if the user has very little memory on his GUS card, and not all patches will be loaded, they are at least reordered, so that it first loads the one you're going to use most.

In case you don't worry about such users, or you don't know "a priori" the number of notes you're going to play, you can just use 1 for each patch you want to load and -1 in the rest.

See also:
GUSOut::setPatchesToUse() , GUSOut::loadPatch()
Returns:
0 if ok, and -1 if there wasn't enough memory to load the patches in the card's memory.

Definition at line 792 of file deviceman.cc.

References checkInit(), and GUSOut::setPatchesToUse().

Referenced by MidiPlayer::play().

const char * DeviceManager::midiMapFilename void   
 

Returns the filename where the Midi Mapper was loaded from, or "" if no MIDI Mapper is in use.

See also:
setMidiMap()

Definition at line 774 of file deviceman.cc.

void DeviceManager::setMidiMap MidiMapper   map
 

Sets a MidiMapper object to use.

This object should already have loaded the configuration. See the description of MidiMapper for more information.

See also:
MidiMapper::MidiMapper() , midiMapFilename()

Definition at line 782 of file deviceman.cc.

Referenced by initManager().

int DeviceManager::rate void    [inline]
 

Returns the SNDCTL_SEQ_CTRLRATE ioctl value.

Definition at line 491 of file deviceman.h.

int DeviceManager::midiPorts void    [inline]
 

Returns the number of MIDI ports available on the system.

It's common that users have MIDI ports available, but there are no external synthesizers connected to these ports, so sending MIDI events to these ports will not produce any music in this case.

See also:
synthDevices() , setDefaultDevice()

Definition at line 502 of file deviceman.h.

Referenced by MidiPlayer::play().

int DeviceManager::synthDevices void    [inline]
 

Returns the number of internal synthesizers available on the system.

Some of these devices will need special configuration, for example, to load sound patches.

See also:
midiPorts() , setDefaultDevice() , setPatchesToUse()

Definition at line 513 of file deviceman.h.

Referenced by MidiPlayer::play().

const char * DeviceManager::name int    i
 

Returns the name of the i-th device .

In case the DeviceManager wasn't yet initialized ( see checkInit() ), the return value is NULL, and in case the parameter has a value out of the valid range ( 0 to midiPorts() + synthDevices() ) it returns an empty string.

Definition at line 714 of file deviceman.cc.

References checkInit(), and MidiOut::deviceName().

Referenced by initManager().

const char * DeviceManager::type int    i
 

Returns the type of device the i-th device is , in a user-friendly string .

For example, "External Midi Port" for midi ports, "FM" for FM synthesizers, "GUS" for Gravis Ultrasound devices, etc.

Definition at line 732 of file deviceman.cc.

References checkInit().


The documentation for this class was generated from the following files:
KDE Logo
This file is part of the documentation for kdelibs Version 3.1.0.
Documentation copyright © 1996-2002 the KDE developers.
Generated on Wed Oct 8 12:22:00 2003 by doxygen 1.2.18 written by Dimitri van Heesch, © 1997-2001