Table des matières du kit Midi     Index du kit Midi

BMidiSynthFile

Hérité de: public BMidiSynth

Déclaré dans: be/midi/MidiSynthFile.h

Bibliothèque: libmidi.so

Résumé

La classe BMidiSynthFile lit les fichiers Standard MIDI et les joue sur le synthétiseur General MIDI. Chaque instance de BMidiSynthFile ne peut lire (et jouer) qu'un seul fichier à la fois. Pour utiliser BMidiSynthFile, créez l'objet, chargez un fichier MIDI, et enclenchez la lecture en appelant la fonction Start():

   /* Création et initialisation de BMidiSynthFile. */
   BMidiSynthFile midiSynthFile;
   entry_ref midiRef;
   get_ref_for_path("/boot/optional/midi/QuickBrownFox.mid", &midiRef);
   midiSynthFile.LoadFile(&midiRef);
   
   /* Joue le fichier. */
   midiSynthFile.Start();

Vous devrez créer une nouvelle instance de BMidiSynthFile pour chaque fichier MIDI que vous voudriez mixer afin d'en obtenir une interprétation commune.

 
Il peut arriver qu'un objet BMidiSynthFile puisse charger et jouer plus d'un fichier MIDI à la fois. Toutefois, vous ne devriez pas vous fier à cette possibilité.



Chargement et lecture

Lorsque vous appelez LoadFile(), l'objet BMidiSynthFile appelle automatiquement EnableInput(true, false). Cette fonction charge alors les données du fichier MIDI dans le synthétiseur; celui-ci lit à son tour les patches des instruments requis. Au cas où ce fichier utiliserait beaucoup d'instruments différents, son chargement peut prendre un certain temps.

Quand le fichier ne joue plus (parce qu'il s'est arrêté en fin de lecture ou alors parce que vous avez appelé Stop()), les instruments ne sont pas déchargés (en prévision d'une nouvelle lecture qui serait ainsi accélérée).


Le thread Run et les fonctions

La classe BMidiSynthFile diffère des autres objets BMidi utilisant Start(): elle n'utilise pas de boucle Run. Les données MIDI sont analysées et jouées par le thread client du synthétiseur (ce thread qui présente les données à l'entrée du convertisseur numérique-analogique). Cette absence de boucle de fonctionnement ne devrait pas modifier la manière d'écrire votre code, mais vous devez être conscient qu'il n'y a pas de thread, et que vous ne pourrez donc pas en contrôler l'activité durant le développement de votre programme.

De plus, BMidiSynthFile ne met pas en œuvre de fonction Run(). Démarrer et arrêter le fonctionnement de l'objet, tâches normalement dévolues à cette fonction, sont prises en charge par le synthétiseur dans son thread client. Si vous dérivez une classe à partir de BMidiSynthFile, ne tentez pas de réimplanter la fonction Run(). Laissez-la absente!

De même que dans la classe BMidiSynth, les implémentations de Hooks MIDI par BMidiSynthFile ne font pas appel aux fonctions Spray. Ce qui signifie que vous ne pouvez pas, par exemple, associer BMidiSynthFile à BMidiPort. Si vous voulez jouer un fichier MIDI vers un port MIDI, utilisez BMidiStore.


Constructeur et Destructeur


BMidiSynthFile()

                                                         
  

BMidiSynthFile(void)

Crée un nouvel objet BMidiSynthFile vide, ainsi qu'une instance de BSynth désignée par la variable globale be_synth (si cet objet n'existe pas déjà). Après l'étape de construction, LoadFile() permet de charger un fichier MIDI dans l'objet BMidiSynthFile. Toutefois, à la différence des instances ordinaires de BMidiSynth, n'appelez pas EnableInput() (LoadFile() prend cette fonction en charge).


~BMidiSynthFile()

                                                         
  

virtual ~BMidiSynthFile()

Déconnecte l'objet du synthétiseur, décharge le fichier MIDI mémorisé ainsi que ses instruments, puis détruit l'objet.


Fonctions membres


Duration() , Position() , Seek()

                                                         
  

int32 Duration(void) const

status_t Position(int32 ticks)

int32 Seek(void)

Duration() retourne la durée des données mémorisées par l'objet (en 1/64èmes de tick MIDI).

Position() modifie la position courante de l'objet dans le fichier MIDI.

Seek() renvoie la position actuelle de l'objet.

Pour repositionner le "song pointer", vous devez indiquer un pourcentage de la durée mesurée par Duration().

 
Le tick MIDI est défini dans le champ "MIDI Division" au début de chaque fichier MIDI. Le fichier indique si cette valeur est en "ppgn" (pulses per quarter note ou impulsions à la noire - dépendante du tempo), ou en mesure et unité de mesure par seconde (indépendante du tempo). La classe BMidiSynthFile gère le mode indépendant du tempo.


CODES DE RETOUR

En général, Position() renvoie toujours B_OK.


EnableLooping() voir Start()


GetMuteMap() voir MuteTrack()


GetPatches()

                                                         
  

status_t GetPatches(int16 *instruments, int16 *count)

Retourne un tableau des numéros d'instruments (patches) requis par le fichier MIDI chargé en mémoire. Ce tableau instruments doit comporter 128 entrées, (par précaution), et doit avoir été alloué avant d'être transmis. A son retour, la fonction affiche dans count le nombre (de numéros) d'instruments du tableau. Ainsi:

   int16 insts[128];
   int16 count;
   midiSynthFile.GetPatches(insts, &count);
   for (int n = 0; n < count; n++) 
      printf("Le fichier utilise l'instrument numéro %d\n", insts[n]);


GetSoloMap() voir MuteTrack()


IsFinished() voir Start()


LoadFile() , UnloadFile()

                                                         
  

status_t LoadFile(const entry_ref *midiFileRef)

void UnloadFile(void) const

LoadFile() demande à l'objet de présenter au synthétiseur les données MIDI du fichier midiFileRef. Le synthétiseur stocke ces données dans sa mémoire cache en prévision d'une lecture lancée ultérieurement par la fonction Start(). Tous les instruments nécessaires pour jouer le fichier sont chargés dans le synthétiseur, s'ils ne l'étaient pas déjà.

UnloadFile() arrête une lecture éventuelle des données chargées par l'objet, puis les évacue en les retirant du synthétiseur.

 
Il peut arriver qu'un objet BMidiSynthFile puisse charger et jouer plus d'un fichier MIDI à la fois. Toutefois, vous ne devriez pas vous fier à cette possibilité.


CODES DE RETOUR


MuteTrack() , GetMuteMap() , SoloTrack() , GetSoloMap()

 
Ces fonctions sont hors service. Ne les utilisez pas.



Pause() voir Start()


Position() voir Duration()


Resume() voir Start()


ScaleTempoBy() voir Tempo()


Seek() voir Duration()


SetFileHook() voir Start()


SetTempo() voir Tempo()


SoloTrack() voir MuteTrack()


Start() , Stop() , Fade() , Pause() , Resume() , IsFinished() , EnableLooping() , SetFileHook() , synth_file_hook

                                                         
  

virtual status_t Start(void)

virtual void Stop(void)

void Fade(void)

void Pause(void)

void Resume(void)

bool IsFinished(void) const

void EnableLooping(bool loop)

void SetFileHook(synth_file_hook fileDone, int32 arg)

typedef void (*synth_file_hook)(int32 arg)

Ces fonctions contrôlent le fonctionnement de l'objet.

Start() fait démarrer la synthèse des données chargées par l'objet à partir de leur début. Remarquez que Start() n'interrompt pas une restitution en cours. Autrement dit, si l'objet est déjà en train de jouer des données, vous obtiendriez une seconde exécution en plus de la première qui se poursuivrait.

Stop() arrête immédiatement la lecture des données en cours.

Fade() interrompt la lecture lui aussi, mais d'une façon plus sophistiquée: le son est atténué avant d'être coupé.

 
Les fonctions Start() et Stop() de BMidiSynthFile se substituent à celles définies par BMidi. En particulier, elles engendrent et commandent un thread Run. Voyez le paragraphe "Le thread Run et les fonctions" pour plus de précisions.


Pause() et Resume() (reprendre) portent bien leurs noms. Notez que lors de la reprise d'une lecture, les notes "passées" ne sont pas rejouées, mais que le tempo exact est respecté. Imaginons par exemple un fichier MIDI qui contiendrait deux notes: la première démarre au moment 1.0 (en secondes) pour une durée de 10.0 secondes, et l'autre débute à l'instant 9.0. Enclenchez la lecture du fichier, appelez ensuite la fonction Pause() à l'instant 3.0: comme prévu, la première note s'arrête. Peu de temps après, reprenez votre lecture (avec Resume()): il y aura six secondes de silence avant l'audition de la seconde note.

IsFinished() renvoie la valeur false si l'objet est en cours (ou en pause) de lecture. Notez que la fonction retourne false avant le chargement d'un fichier, et true si le fichier est chargé mais non encore lu.

EnableLooping(true) rejoue le fichier quand sa lecture est finie. Si l'argument contient la valeur false, le fichier n'est pas rejoué. Stop() interrompt toujours les lectures, même si le bouclage est activé.

SetFileHook() enregistre une fonction appelée en fin de lecture, que celle-ci résulte d'une fin de données normale ou d'un appel à Stop(); arg est l'unique argument transmis. Remarquez que le hook est appelé quand l'objet est totalement arrêté, et non à chaque rembobinage des données quand la lecture en boucle est activée.

CODES DE RETOUR

Start() renvoie...


Stop() voir Start()


synth_file_hook voir Start()


Tempo() , SetTempo() , ScaleTempoBy()

                                                         
  

int32 Tempo(void) const

void SetTempo(int32 beatsPerMinute)

void ScaleTempoBy(double scalar)

Tempo() renvoie le tempo adopté pour la restitution des données, en beats-per-minute (bpm ou pulsations par minute), telle que cette valeur a été lue dans le fichier MIDI ou telle qu'elle a été redéfinie par l'une des deux autres fonctions:

SetTempo() le détermine de manière absolue, en beats-per-minute, et ...

ScaleTempoBy() modifie le tempo en cours en fonction de son argument (scalar == 2.0 signifie que les données sont jouées deux fois plus vite, scalar == .5 moitié moins vite, et ainsi de suite).


UnloadFile() voir LoadFile()


Table des matières du kit Midi     Index du kit Midi


The Be Book,
...in lovely HTML...
for BeOS Release 5.

Copyright © 2000 Be, Inc. All rights reserved..