midiOutSetVolume-Funktion (mmeapi.h)

  • Artikel

Die midiOutSetVolume-Funktion legt die Lautstärke eines MIDI-Ausgabegeräts fest.

Syntax

MMRESULT midiOutSetVolume(
  HMIDIOUT hmo,
  DWORD    dwVolume
);

Parameter

hmo

Handle für ein offenes MIDI-Ausgabegerät. Dieser Parameter kann auch das Handle eines MIDI-Streams enthalten, solange er in HMIDIOUT umgewandelt wird. Dieser Parameter kann auch ein Gerätebezeichner sein.

dwVolume

Neue Volumeeinstellung. Das Wort mit niedriger Reihenfolge enthält die Lautstärkeeinstellung für den linken Kanal, und das Wort mit hoher Ordnung enthält die Einstellung für den rechten Kanal. Ein Wert von 0xFFFF stellt die volle Lautstärke dar, und der Wert 0x0000 ist Stille.

Wenn ein Gerät nicht sowohl die linke als auch die rechte Lautstärkeregelung unterstützt, gibt das Wort mit niedriger Ordnung dwVolume die Mono-Lautstärkeebene an, und das Wort mit hoher Ordnung wird ignoriert.

Rückgabewert

Gibt MMSYSERR_NOERROR zurück, wenn erfolgreich oder andernfalls ein Fehler aufgetreten ist. Mögliche Fehlerwerte sind:

Rückgabecode Beschreibung
MMSYSERR_INVALHANDLE
 Das angegebene Gerätehandle ist ungültig.
MMSYSERR_NOMEM
 Das System kann Arbeitsspeicher nicht zuordnen oder sperren.
MMSYSERR_NOTSUPPORTED
 Die Funktion wird nicht unterstützt.

Hinweise

Wenn ein Gerätebezeichner verwendet wird, gilt das Ergebnis des midiOutSetVolume-Aufrufs für alle Instanzen des Geräts. Wenn ein Gerätehandle verwendet wird, gilt das Ergebnis nur für die instance des Geräts, auf das vom Gerätehandle verwiesen wird.

Nicht alle Geräte unterstützen Volumeänderungen. Sie können ermitteln, ob ein Gerät dies unterstützt, indem Sie das Gerät mithilfe der Funktion midiOutGetDevCaps und dem flag MIDICAPS_VOLUME abfragen.

Sie können auch ermitteln, ob das Gerät die Lautstärkesteuerung sowohl auf dem linken als auch im rechten Kanal unterstützt, indem Sie das Gerät mithilfe der MidiOutGetDevCaps-Funktion und dem flag MIDICAPS_LRVOLUME abfragen.

Geräte, die keine vollständige 16-Bit-Steuerung auf Volumeebene unterstützen, verwenden die Bits mit hoher Reihenfolge der angeforderten Volumeeinstellung. Beispielsweise erzeugt ein Gerät, das 4 Bits der Lautstärkeregelung unterstützt, die gleiche Lautstärkeeinstellung für die folgenden Werte auf Volumeebene: 0x4000, 0x43be und 0x4fff. Die midiOutGetVolume-Funktion gibt unabhängig von den Funktionen des Geräts den vollständigen 16-Bit-Wert zurück, der von midiOutSetVolume festgelegt wird.

Volumeeinstellungen werden logarithmisch interpretiert. Dies bedeutet, dass die wahrgenommene Erhöhung der Lautstärke gleich ist, wenn die Lautstärke von 0x5000 auf 0x6000 erhöht wird, wie von 0x4000 auf 0x5000.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows 2000 Professional [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows 2000 Server [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile mmeapi.h (Einschließen von Windows.h)
Bibliothek Winmm.lib
DLL Winmm.dll

Weitere Informationen

MIDI-Funktionen