diff options
Diffstat (limited to 'libkmid/libkmid.h')
| -rw-r--r-- | libkmid/libkmid.h | 226 |
1 files changed, 226 insertions, 0 deletions
diff --git a/libkmid/libkmid.h b/libkmid/libkmid.h new file mode 100644 index 000000000..45f41bd79 --- /dev/null +++ b/libkmid/libkmid.h @@ -0,0 +1,226 @@ +/* libkmid.h - class KMidSimpleAPI that makes it easy to use libkmid + and a C wrapper. + This file is part of LibKMid 0.9.5 + Copyright (C) 2000 Antonio Larrosa Jimenez + LibKMid's homepage : http://www.arrakis.es/~rlarrosa/libkmid.html + + This library is free software; you can redistribute it and/or + modify it under the terms of the GNU Library General Public + License as published by the Free Software Foundation; either + version 2 of the License, or (at your option) any later version. + + This library is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + Library General Public License for more details. + + You should have received a copy of the GNU Library General Public License + along with this library; see the file COPYING.LIB. If not, write to + the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. + + Send comments and bug fixes to Antonio Larrosa <larrosa@kde.org> + +***************************************************************************/ +#ifndef _LIBKMID_H +#define _LIBKMID_H + +#ifdef __cplusplus + +#include <kdelibs_export.h> + +/** + * Simple API covering most of the uses of libkmid. + * + * You can use the members of this class in pure C applications, just by using + * the same name as the corresponding function member. + * + * Suppose you're developing a game and you want to play some background music + * while the user is playing. You only have to call : + * + * @li kMidInit(); + * @li kMidLoad("RideOfTheValkyries.mid"); + * @li kMidPlay(); + * + * When the user decides to quit the game, use + * + * @li kMidStop(); + * @li kMidDestruct(); + * + * to stop the music and release the memory allocated by libkmid. + * + * @short A very simple API around the rest of libkmid. + * @version 0.9.5 17/01/2000 + * @author Antonio Larrosa Jimenez <larrosa@kde.org> + */ +class KMID_EXPORT KMidSimpleAPI +{ + private: + class KMidSimpleAPIPrivate; + KMidSimpleAPIPrivate *d; + + public: + + /** + * Initializes libkmid. Creates the DeviceManager object, and initializes + * some variables that will be used later. + * + * @return 0 if OK, and a positive number when there's any error (for + * example, because the /dev/sequencer device couldn't be opened, be it + * because it was already opened by another application, or because the + * sound card wasn't configured) + */ + static int kMidInit(void); + + /** + * Loads a song that will be played with the next call to kMidPlay(). + */ + static int kMidLoad(const char *filename); + + /** + * Plays the song currently loaded with kMidLoad(). + * kMidPlay forks in order to play the song in a different process, it + * exits inmediately, so that the application can follow the normal + * execution flow while the sone is played. + * + * If loop is 0 the song is played once and then the child process + * finishes. If loop is 1, the song is played repeatedly until + * kMidStop() is called. You can call kMidStop() anytime you want + * (also if loop is 0) to stop the song and kill the child process. + * + * @see kMidStop + * @see kMidIsPlaying + */ + static int kMidPlay(int loop=0); + + /** + * Stops playing a song inmediatly. It doesn't return until the child + * process that is playing the song is terminated. + * + * @see kMidPlay + */ + static int kMidStop(void); + + /** + * Releases the memory allocated by libkmid. To continue playing, you must + * first make a(nother) call to kMidInit(). + */ + static void kMidDestruct(void); + + /** + * Returns 1 if the library is playing a song, and 0 if it's not. + * @see kMidPlay + */ + static int kMidIsPlaying(void); + + /** + * Returns the number of MIDI devices ( MIDI ports + synthesizers ) + * @see DeviceManager::midiPorts + * @see DeviceManager::synthDevices + * @see kMidName + * @see kMidType + */ + static int kMidDevices(void); + + /** + * Returns the name of the i-th device . In case libkmid wasn't yet + * initialized ( see kMidInit() ), the return value is NULL, and in + * case the parameter has a value out of the valid range + * ( see kMidDevices() ) it returns an empty string. + * + * @see kMidDevices + * @see kMidType + */ + static const char *kMidName(int i); + + /** + * Returns the type of the i-th device . In case libkmid wasn't yet + * initialized ( see kMidInit() ), the return value is NULL, and in + * case the parameter has a value out of the valid range + * ( see kMidDevices() ) it returns an empty string. + * + * @see kMidDevices + * @see kMidName + */ + static const char *kMidType(int i); + + /** + * Sets the MIDI device to use when playing a song. + * @see kMidDevices + * @see kMidName + * @see DeviceManager + */ + static void kMidSetDevice(int i); + + /** + * Sets the Midi Mapper to use. Most of the users won't need a midi mapper, + * but there're still non-General Midi synthesizers out there, and people + * with one of those will get much better sound quality by using a MIDI + * mapper. + * + * Please have a look at KMid's documentation for more information + * about MIDI mappers and how to write a MIDI mapper for your keyboard. + */ + static void kMidSetMidiMapper(const char *mapfilename); + + /** + * Returns the version number of libkmid, i.e. "0.9.5" or "1.0 Beta" + */ + static const char *kMidVersion(void); + + /** + * Returns the copyright notice that applications using libkmid should print + * to the user in an about box or somewhere visible. + * I.e. + * + * "LibKMid 0.9.5 (C) 1997-2000 Antonio Larrosa Jimenez <larrosa@kde.org>. Spain" + */ + static const char *kMidCopyright(void); + +}; + + + +extern "C" { + +#else +#define KMID_EXPORT +#endif + + +KMID_EXPORT int kMidInit(void); +KMID_EXPORT int kMidLoad(const char *filename); +KMID_EXPORT int kMidPlay(void); +KMID_EXPORT int kMidStop(void); +KMID_EXPORT void kMidDestruct(void); +KMID_EXPORT int kMidIsPlaying(void); +KMID_EXPORT int kMidDevices(void); +KMID_EXPORT const char * kMidName(int i); +KMID_EXPORT const char * kMidType(int i); +KMID_EXPORT void kMidSetDevice(int i); +KMID_EXPORT void kMidSetMidiMapper(const char *mapfilename); +KMID_EXPORT const char * kMidVersion(void); +KMID_EXPORT const char * kMidCopyright(void); + + + +#ifdef __cplusplus + +} + +/** + * @internal + */ +extern struct kMidData +{ + class DeviceManager *midi; + class MidiPlayer *player; + class MidiMapper *map; + struct PlayerController *pctl; + int pctlsmID; + int pid; +} kMid; +#endif + + +#endif |