Copy the KDE 3.5 branch to branches/trinity for new KDE 3.5 features.

BUG:215923


git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/kdelibs@1054174 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 396 insertions, 0 deletions

diff --git a/libkmid/player.h b/libkmid/player.h
new file mode 100644
index 000000000..6a9210292
--- /dev/null
+++ b/libkmid/player.h
@@ -0,0 +1,396 @@
+/*  player.h  - class MidiPlayer. Plays a set of tracks
+    This file is part of LibKMid 0.9.5
+    Copyright (C) 1997,98,99,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 _PLAYER_H
+#define _PLAYER_H
+
+#include <libkmid/dattypes.h>
+#include <libkmid/midfile.h>
+#include <libkmid/deviceman.h>
+#include <libkmid/track.h>
+#include <libkmid/notearray.h>
+#include <kdemacros.h>
+
+/**
+ * This struct stores text, lyrics and change tempo events among others.
+ *
+ * It includes the main information for an event. That is, the absolute
+ * millisecond at which this event is played (from the beginning of the song),
+ * the delta milliseconds from the previous SpecialEvent, an ID, etc. 
+ *
+ * This struct is used as nodes for a linked list, which you can get using
+ * MidiPlayer::specialEvents().
+ *
+ * @short Struct used to store certain events
+ * @version 0.9.5 17/01/2000
+ * @author Antonio Larrosa Jimenez <larrosa@kde.org>
+ */
+struct SpecialEvent
+{
+  /**
+   * An integer ID, that is assigned in order to each SpecialEvent.
+   */
+  int id;
+
+  /**
+   * Delta milliseconds from the previous SpecialEvent. 
+   *
+   * @see absmilliseconds
+   */
+  ulong diffmilliseconds;
+
+  /**
+   * The absolute millisecond (from the beginning of the song) at which this
+   * SpecialEvent object is played.
+   *
+   * @see diffmilliseconds
+   */
+  ulong absmilliseconds;
+
+  /**
+   * MIDI ticks (from the beginning of the song) at which this event is played.
+   */
+  int ticks;
+
+  /**
+   * Type of event. This currently includes:
+   *
+   * @li 0 - Nothing, end of linked list.
+   * @li 1 - Text Event . See text.
+   * @li 3 - Change Tempo Event . See tempo.
+   * @li 5 - Lyrics Event . See text.
+   * @li 6 - Change number of beats per measure . See num and den.
+   * @li 7 - Beat . See num and den.
+   *
+   * The "Change number of beats per measure" and "beat" events are not really
+   * in the midi file, but they are added to the linked list in case you have
+   * an use for it.
+   */
+  int type;
+
+  /**
+   * Text field . It has a meaning only for Text and Lyrics events.
+   */
+  char text[1024];
+
+  /**
+   * Tempo field . It has a meaning only for Change Tempo events.
+   */
+  ulong tempo;
+  /**
+   * Numerator . It has a meaning only for Change number of beats per measure and
+   * beat events.
+   */
+  int num;
+  /**
+   * Denominator . It has a meaning only for Change number of beats per measure
+   * and beat events.
+   */
+  int den;
+
+  /**
+   * This struct stores text, lyrics and change tempo events among others.
+   *
+   * It includes the main information for an event. That is, the absolute
+   * millisecond at which this event is played (from the beginning of the song),
+   * the delta milliseconds from the previous SpecialEvent, an ID, etc. 
+   *
+   * This struct is used as nodes for a linked list, which you can get using
+   * MidiPlayer::specialEvents().
+   */
+  struct SpecialEvent *next;
+
+  /**
+   * Next node in the linked list.
+   */
+  
+};
+
+
+/**
+ * PlayerController is a struct that is used by the MidiPlayer object
+ * to tell other parts of the application about the status of the MIDI playing.
+ *
+ * @short Struct used to have control over the player engine
+ * @version 0.9.5 17/01/2000
+ * @author Antonio Larrosa Jimenez <larrosa@kde.org>
+ */
+struct PlayerController
+{
+  volatile ulong  ticksTotal;
+  volatile ulong  ticksPlayed;
+  volatile double millisecsPlayed;
+  volatile ulong  beginmillisec;
+
+  volatile int tempo;
+  volatile int num;
+  volatile int den;
+
+  volatile int SPEVprocessed;
+  volatile int SPEVplayed;
+
+  /**
+   * When pause is released, if the caller must know when the player has
+   * opened the devices and is playing again, then it just has to check
+   * to see when OK changes the value to 1
+   */
+  volatile int OK; 
+
+  /**
+   * When the player is playing (or paused), playing is set to 1.
+   */
+  volatile int playing;
+
+  /**
+   * When the player is paused, paused is set to 1.
+   */
+  volatile int paused;
+
+  /**
+   * When the player seeking the position of the song, moving is set to 1.
+   */
+  volatile int moving;
+
+  /**
+   * When the player has finished playing a song, finished is set to 1.
+   */
+  volatile int finished;
+
+  /**
+   * @internal
+   * @deprecated
+   * Not used
+   */
+  volatile int message KDE_DEPRECATED; // set one of the following :
+
+#define PLAYER_DOPAUSE	1
+#define PLAYER_DOSTOP	2
+#define PLAYER_SETPOS	4
+#define PLAYER_HALT	8
+
+  volatile ulong gotomsec; //milliseconds to go to,if player_setpos is set
+
+  /**
+   * When error is 1, an error has ocurred (i.e. it coultn't open the device)
+   */    
+  volatile int error;
+
+  /**
+   * If gm is 1, the song follows the General Midi standard, if gm is 0, the song
+   * is in MT 32 format.
+   */
+  volatile int gm;
+
+  /**
+   * 100 means no change, 50 halfs the volume, 200 doubles it (if possible), etc.
+   *
+   * @see DeviceManager::setVolumePercentage()
+   */
+  volatile int volumepercentage ; 
+
+  /**
+   * Activate or disactivate the force to use a patch for a given channel.
+   * @see pgm
+   */
+  volatile bool forcepgm[16];
+
+  /**
+   * Force a given patch in each channel at "this" moment, as determined by
+   * forcepgm.
+   */
+  volatile int pgm[16];
+
+  /**
+   * Ratio to multiply the tempo to.
+   */
+  volatile double ratioTempo;
+
+  /**
+   * @internal Used to stop the main pid until the child has finished to 
+   * send the all notes off event
+   */
+  volatile bool isSendingAllNotesOff;
+
+  volatile MidiEvent *ev;
+};
+
+
+/**
+ * MIDI file player routines . This class reads a MIDI file and
+ * play it using a DeviceManager object.
+ *
+ * To use it, just call loadSong() with the filename you want to play,
+ * and then play().
+ * 
+ * Please have a look at the note in the play() documentation.
+ *
+ * MidiPlayer will write information about the playing process on a 
+ * PlayerController() structure that you must supply to the constructor
+ *
+ * Alternatively, if everything you want is to play a midi file in a game or
+ * any other application that doesn't need to fine tune the midi playing, just
+ * use the kmidplay() function.
+ *
+ * @see KMidSimpleAPI
+ *
+ * @short The MIDI file player engine
+ * @version 0.9.5 17/01/2000
+ * @author Antonio Larrosa Jimenez <larrosa@kde.org>
+ */
+class KMID_EXPORT MidiPlayer
+{
+  class MidiPlayerPrivate;
+  MidiPlayerPrivate *d;
+
+  DeviceManager *midi;
+  MidiFileInfo *info;
+  MidiTrack **tracks;
+  SpecialEvent *spev;
+  NoteArray *na;
+
+  int songLoaded;
+
+  PlayerController *ctl;
+
+  bool parsesong;
+  bool generatebeats;
+
+  void removeSpecialEvents(void);
+  void parseSpecialEvents(void);
+  void insertBeat(SpecialEvent *ev,ulong ms,int num,int den);
+  void generateBeats(void);
+
+  //NoteArray *parseNotes(void);
+  void debugSpecialEvents(void);
+  public:
+
+  /**
+   * Constructor . You must construct and pass a DeviceManager object and a 
+   * PlayerController structure. None of them will be destroyed by this
+   * object, so you should do it after destroying the MidiPlayer object.
+   */
+  MidiPlayer(DeviceManager *midi_,PlayerController *pctl);
+
+  /**
+   * Destructor.
+   */
+  ~MidiPlayer();
+
+  /**
+   * Loads a Song, and parses it (it the parse wasn't disabled with 
+   * setParseSong() ) . It also generates the Beat events (see 
+   * SpecialEvent::type() ) if you enabled this by using 
+   * setGenerateBeats() .
+   */
+  int loadSong(const char *filename);
+
+  /**
+   * Unloads the current song, so that every internal variable is empty and clean
+   * for further usage.
+   */
+  void removeSong(void); 
+
+  /**
+   * Returns true if there's a song already loaded (with a previous call to 
+   * loadSong() ) and false if not.
+   */
+  int isSongLoaded(void) { return songLoaded; }
+
+  /**
+   * Returns the linked list of SpecialEvents objects . For this to work,
+   * the parse should be enabled (the default), by using setParseSong().
+   */
+  SpecialEvent *specialEvents() { return spev; }
+
+  /**
+   * Returns and array with the notes playen through the song . MidiPlayer must
+   * parse the song to get the notes, so be sure not to disable the parsing of
+   * the song.
+   *
+   * Returns an array of notes, (just note on and note off events), in the form
+   * of a NoteArray object
+   */
+  NoteArray *noteArray(void) { return na; }
+
+
+  /**
+   * Plays the song using the DeviceManager object supplied in the
+   * constructor. It should be already configured, as play doesn't change the
+   * volume, nor midi mapper, for example.
+   *
+   * Note: Calling this function will block the execution of your application
+   * until the song finishes playing. The solution for this is simple, fork
+   * before calling it, and create the PlayerController object on shared
+   * memory.
+   *
+   * As alternative, if everything you want is playing a midi file in a game or
+   * any other application that doesn't need to fine tune the midi playing, just
+   * use the KMidSimpleAPI::kMidPlay() function. 
+   *
+   * @see KMidSimpleAPI::kMidInit
+   * @see KMidSimpleAPI::kMidPlay
+   * @see KMidSimpleAPI::kMidStop
+   * @see KMidSimpleAPI::kMidDestruct
+   */
+  void play(bool calloutput=false,void output(void) = 0);
+
+  /**
+   * Enables or disables the parsing of the song when loading it. This affects
+   * the SpecialEvents ( specialEvents() ) and the NoteArray 
+   * ( noteArray() ).
+   */
+  void setParseSong(bool b = true);
+
+  /**
+   * Enables or disables the generation of beats event in a song when loading
+   * it. 
+   */
+  void setGenerateBeats(bool b = false);
+
+  /**
+   * Returns information about the current MIDI file.
+   *
+   * @see loadSong
+   */
+  MidiFileInfo *information(void) { return info; }
+
+  /**
+   * Sets the position in a song. 
+   * @param gotomsec the number of milliseconds to go to . A subsequent call to
+   * play() will start playing the song from that moment, instead of the
+   * beginning.
+   * @param midistat a MidiStatus object that will contain the status in
+   * which the MIDI device would be if it would have arrived to this situation by
+   * a normal playing of the song.
+   */
+  void setPos(ulong gotomsec, class MidiStatus *midistat);
+
+  /**
+   * Changes the speed at which a song is played. The song's tempo is multiplied
+   * by the specified ratio.
+   */
+  void setTempoRatio(double ratio);
+
+};
+
+#endif