You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
tdelibs/libkmid/libkmid.h

227 lines
6.7 KiB

/* 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 <tdelibs_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