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

BMidiSynth

Hérité de: BMidi

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

Bibliothèque: libmidi.so

Résumé

La classe BMidiSynth est l'interface MIDI du synthétiseur General MIDI: pour lui envoyer des données MIDI, créez une instance de BMidiSynth. Vous pouvez envoyer des messages MIDI directement à l'objet:

   /* Crée et initialise BMidiSynth. */
   BMidiSynth midiSynth;
   midiSynth.EnableInput(true, true);
   
   /* Choix d'un instrument et émission d'une note. */
   midiSynth.ProgramChange(1, B_ACOUSTIC_GRAND);
   midiSynth.NoteOn(1, 40, 100, B_NOW);
   snooze(1000000);
   midiSynth.NoteOff(1, 40, 100, B_NOW);

Il est également possible de connecter un objet BMidiSynth à la sortie d'un autre objet BMidi, tel BMidiPort:

   /* Connexion du synthé à un port MIDI. */
   BMidiPort midiPort;
   char buf[B_OS_NAME_LENGTH];
   
   /* Initialisation de BMidiPort. */
   if (midiPort.GetDeviceName(0, buf) == B_OK) {
      midiPort.Open(buf);
   
      /* Utilisation de midiSynth (créé et initialisé plus haut). */
      midiPort.Connect(midiSynth);
      midiPort.Start();
      ...
   }

L'unique chose à ne pas faire serait d'associer BMidiFile à BMidiSynth. Pour écouter un fichier MIDI, utilisez plutôt une instance de BMidiSynthFile (BMidiSynthFile est une classe directe de BMidiSynth).

BMidiSynth n'émet pas de messages MIDI; et il serait donc incorrect de connecter d'autres objets BMidi à sa sortie. Autrement dit, ne procédez pas ainsi:

   /* --- A  NE PAS FAIRE --- Ce serait une aberration. */
   midiSynth.Connect(someOtherMidiObject);


Initialisation de votre instance de BMidiSynth

La création d'un objet BMidiSynth génère une instance de BSynth (si elle n'existe pas déjà). Cet objet BSynth, présent globalement dans votre application sous forme de la variable be_synth, assure le contrôle de certains des réglages généraux du synthétiseur, tels que volume et réverbération.

Avant d'envoyer des messages à BMidiSynth, appelez EnableInput(). Cette fonction autorise l'objet en entrée et indique au synthétiseur s'il doit charger, ou non, le fichier de synthèse sonore. Si vous demandez à EnableInput() de ne pas charger ce fichier, vous devrez le faire vous-même pour les instruments dont vous aurez besoin. A titre d'exemple, sélectionnons ici deux instruments, puis faisons-leur jouer chacun une note. Nous devons aussi transmettre un message ProgramChange() afin que BMidiSynth utilise nos instruments sur les canaux appropriés (ceux où nous jouons les notes):

   /* Entrée autorisée, mais sans chargement du fichier de synthèse. */
   midiSynth.EnableInput(true, false);
   
   /* Chargement de deux instruments. */
   midiSynth.LoadInstrument(B_TINKLE_BELL);
   midiSynth.LoadInstrument(B_VIOLIN);
   
   /* Attribution de canaux MIDI aux instruments. */
   midiSynth.ProgramChange(1, B_TINKLE_BELL);
   midiSynth.ProgramChange(2, B_VIOLIN);
   
   /* Musique! */
   midiSynth.NoteOn(1, 84, 100);
   snooze(10);
   midiSynth.NoteOn(2, 60, 100);
   snooze(1000000);
   midiSynth.NoteOff(1, 84, 100);
   snooze(10);
   midiSynth.NoteOff(2, 60, 100);

L'organisation et les numéros des instruments respectent la norme General MIDI, et commencent à l'instrument 0 (certains synthétiseurs et séquenceurs se basent sur des numéros d'instruments partant de 1). Les constantes midi_axe, définies dans be/midi/MidiDefs.h, fournissent des noms descriptifs utilisés ici pour les instruments (vous pouvez également consulter la liste des constantes midi_axe à la page "Instruments General MIDI").

Persistance des instruments

Toutes les fonctions de chargement d'instruments (EnableInput() et les fonctions citées avec LoadInstrument()) agissent sur tous les clients de be_synth (c'est-à-dire tous les objets BMidiSynth de votre application). Ce qui peut être heureux: charger un instrument à partir de BMidiSynth signifie qu'il n'aura pas à être rechargé quand, par exemple, BMidiSynthFile en aura besoin (le synthétiseur est intelligent dans ses rechargements: si un instrument est déjà en mémoire, il ne tentera pas de l'y remettre). Un autre exemple: si vous utilisez plus d'un objet BMidiSynth, chacun d'eux peut charger les instruments en totalité (au moyen de EnableInput()) sans pertes de performances.

Toutefois, il y a aussi un inconvénient: si l'un des objets BMidiSynth libère un instrument (par UnloadInstrument() ou FlushInstrumentCache(false)), cet instrument disparaîtra aussi pour tous les autres BMidiSynth. Vous pouvez prévenir ces déchargements intempestifs en appelant la fonction FlushInstrumentCache(true) (reportez-vous à sa description pour plus de détails).

Instruments de percussion

Pour utiliser les percussions du canal 10, il est nécessaire de charger tous les instruments:

   /* J'ai besoin des percussions, donc... */
   midiSynth.EnableInput(true, true);


Constructeur et Destructeur


BMidiSynth()

                                                         
  

BMidiSynth(void)

Crée un nouvel objet BMidiSynth, ainsi qu'une instance de BSynth désignée par la variable globale be_synth (si cet objet n'existe pas déjà). Pour activer votre objet BMidiSynth après sa construction, appelez la fonction SetEnabled().


~BMidiSynth()

                                                         
  

virtual ~BMidiSynth()

Dissocie l'objet du synthétiseur avant de le détruire.


Fonctions membres


EnableInput() , IsInputEnabled()

                                                         
  

status_t EnableInput(bool enable, bool loadSynthFile)

bool IsInputEnabled(void) const

EnableInput() connecte et déconnecte l'objet du synthétiseur, suivant la valeur de enable: true ou false. Inactivé, BMidiSynth ne transmet aucun message MIDI au synthétiseur.

Si enable et loadSynthFile contiennent la valeur true, les instruments du fichier de synthèse qui ne seraient pas déjà chargés le sont immédiatement. La mise en mémoire de l'ensemble du fichier des instruments peut durer un certain temps (plus d'une seconde mais moins d'une minute), et ce n'est pas votre dernier appel à des instruments: c'est pourquoi vous pouvez souhaiter ne pas les charger tous en une fois. Pour différer le chargement, appelez LoadInstrument() consécutivement à EnableInput().

IsInputEnabled() vous indique si BMidiSynth est activé.

Le paragraphe "Initialisation de votre instance de BMidiSynth" vous donnera plus d'indications sur le chargement et la persistance des instruments, ainsi que sur l'usage des percussions du canal 10.

 
Les objets BMidiSynthFile n'ont pas besoin d'appeler EnableInput(). L'entrée est automatiquement activée par le chargement du fichier.


CODES DE RETOUR

Généralement, EnableInput() retourne toujours B_OK.


FlushInstrumentCache() voir LoadInstrument()


GetMuteMap() voir MuteChannel()


GetSoloMap() voir MuteChannel()


IsInputEnabled() voir EnableInput()


LoadInstrument() , RemapInstrument() , UnloadInstrument() , FlushInstrumentCache()

                                                         
  

status_t LoadInstrument(int16 instrument)

status_t RemapInstrument(int16 from, int16 to)

status_t UnloadInstrument(int16 instrument)

void FlushInstrumentCache(bool flush)

 
Ces fonctions affectent tous les clients de be_synth (qui doivent effectivement faire partie de la classe BSynth).


LoadInstrument() charge, s'il ne l'était pas déjà, l'instrument nommé à partir du fichier de synthèse. L'instrument doit résider en mémoire avant de pouvoir être utilisé; si tous y ont déjà été chargés (par InputEnabled()), vous n'aurez pas à appeler cette fonction. Un instrument résident est accessible à tous les objets BMidiSynth de votre programme.

RemapInstrument() demande au synthétiseur de substituer toutes ses requêtes à l'instrument from par des requêtes à l'instrument to. Voici un exemple où nous demandons au synthétiseur d'émettre un coup de feu pour chaque note de banjo:

   /* Le banjo se transforme en fusil: bonne idée! */
   midiSynth.RemapInstrument(B_BANJO, B_GUNSHOT);

UnloadInstrument() décharge l'instrument nommé du synthétiseur.

FlushInstrumentCache() a un mode de fonctionnement stupide. Si flush contient la valeur false, le synthétiseur s'arrête de jouer tous les sons (et échantillons) en cours de restitution et décharge tous ses instruments. Si flush contient true, le jeu en cours n'est pas modifié, mais cela interdit tout déchargement ultérieur d'instruments, ce qui veut dire que FlushInstrumentCache(true) permet au synthétiseur d'ignorer tous les appels futurs de UnloadInstrument(). Cette restriction sera maintenue jusqu'à l'appel de FlushInstrumentCache(false).

 
Le paragraphe "Initialisation de votre instance de BMidiSynth" vous donnera plus d'indications sur le chargement et la persistance des instruments, ainsi que sur l'usage des percussions du canal 10.


CODES DE RETOUR

Généralement, UnloadInstrument() retourne toujours B_OK. Les deux autres fonctions de type status_t renvoient...


MuteChannel() , GetMuteMap() , SoloChannel() , GetSoloMap()

 
Ces fonctions sont hors service. Ne les utilisez pas.



RemapInstrument() voir LoadInstrument()


SetTransposition() , Transposition()

                                                         
  

void SetTransposition(int16 transpose)

int16 Transposition(void) const

SetTransposition() permet de déterminer, par demi-tons, le degré de transposition appliqué à la génération des notes à venir; celles qui seraient déjà en cours de restitution ne seront pas transposées. Cette transposition s'applique à tous les canaux de l'objet en référence.

Transposition() renvoie, en demi-tons, le degré de transposition utilisé (0 par défaut).


SetVolume() , Volume()

                                                         
  

void SetVolume(double volume)

double Volume(void) const

SetVolume() règle l'amplitude (sonore) de l'objet en fonction du coefficient volume (sur tous les canaux). En plus d'agir sur les sons à venir, le nouveau niveau de volume s'applique à ceux que l'objet serait en train de restituer.

Volume() renvoie le coefficient d'amplitude actuel (1.0 par défaut).


SoloChannel() voir MuteChannel()


Tick()

                                                         
  

uint32 Tick(void) const

Renvoie le nombre de millionièmes de secondes écoulées depuis la création de l'objet. Cette durée doit être utilisée pour calculer des valeurs relatives, par exemple le temps entre des notes. Notez bien que l'argument time des fonctions MIDI Hook est donné en millièmes de seconde.


Transposition() voir SetTransposition()


UnloadInstrument() voir LoadInstrument()


Volume() voir SetVolume()


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..