Signatur
Beschreibung
openal_listener_set konfiguriert eine Eigenschaft des sogenannten Listeners in OpenAL. Der Listener repräsentiert die "Ohren" in einem 3D-Audio-Szenario – also den Standpunkt, von dem aus Klänge wahrgenommen werden. Typische Eigenschaften sind Position, Geschwindigkeit (Velocity) und Ausrichtung (Orientation).
Die Funktion ist Teil der PHP-OpenAL-Erweiterung (ext/openal), die eine Schnittstelle zur OpenAL-Bibliothek bereitstellt. Sie erlaubt es, die akustische Wahrnehmungsperspektive im Raum dynamisch anzupassen – beispielsweise bei beweglichen Kamerasichten in Spielen oder Simulationen.
Der Parameter property wird durch eine der vordefinierten OpenAL-Konstanten bestimmt (z. B. AL_POSITION, AL_VELOCITY, AL_ORIENTATION). Der übergebene Wert value muss dem jeweiligen Typ der Eigenschaft entsprechen – skalare Werte für einfache Eigenschaften, Arrays für Vektoren oder Ausrichtungsdaten.
Diese Funktion ist sinnvoll in Echtzeit-Audio-Anwendungen, in denen der Hörer im Raum bewegt wird und die räumliche Klangwiedergabe dynamisch angepasst werden soll.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $property Pflicht | int | Eine OpenAL-Konstante, die die zu setzende Listener-Eigenschaft identifiziert. Mögliche Werte sind z. B. AL_POSITION, AL_VELOCITY, AL_GAIN oder AL_ORIENTATION. |
|
| $value Pflicht | mixed | Der neue Wert für die Eigenschaft. Für skalare Eigenschaften wie AL_GAIN ein float, für Vektoreigenschaften wie AL_POSITION oder AL_VELOCITY ein Array mit drei Fließkommazahlen [x, y, z]. Für AL_ORIENTATION ein Array mit sechs Werten (At-Vektor + Up-Vektor). |
Rückgabewert
true zurück, wenn die Eigenschaft erfolgreich gesetzt wurde, andernfalls false (z. B. bei ungültiger Eigenschaft oder falschem Werteformat).Beispiele
Listener-Position im 3D-Raum setzen
<?php
// OpenAL-Gerät und -Kontext initialisieren
$device = openal_device_open();
$context = openal_context_create($device);
openal_context_current($context);
// Listener an Position (1.0, 0.0, -5.0) im 3D-Raum platzieren
$result = openal_listener_set(AL_POSITION, [1.0, 0.0, -5.0]);
if ($result) {
echo "Listener-Position erfolgreich gesetzt.";
} else {
echo "Fehler beim Setzen der Listener-Position.";
}
?>Listener-Lautstärke (Gain) und Ausrichtung konfigurieren
<?php
$device = openal_device_open();
$context = openal_context_create($device);
openal_context_current($context);
// Gesamtlautstärke des Listeners auf 0.8 setzen
openal_listener_set(AL_GAIN, 0.8);
// Geschwindigkeit des Listeners setzen (für Doppler-Effekt)
openal_listener_set(AL_VELOCITY, [0.0, 0.0, 1.0]);
// Ausrichtung: At-Vektor (Blickrichtung) + Up-Vektor
// Blick entlang der negativen Z-Achse, oben entlang der Y-Achse
openal_listener_set(AL_ORIENTATION, [0.0, 0.0, -1.0, 0.0, 1.0, 0.0]);
echo "Listener vollständig konfiguriert.";
?>// Wichtig · Fallstricke
Hinweis zur Verfügbarkeit: Die OpenAL-Erweiterung ist standardmäßig nicht in PHP enthalten und muss als PECL-Paket installiert werden (pecl install openal). Sie steht nicht auf allen Plattformen zur Verfügung und wird in modernen PHP-Versionen kaum noch aktiv gepflegt.
Werteformate: Ein falsches Format für value (z. B. ein skalarer Wert statt eines Arrays für AL_POSITION) führt zu false als Rückgabe. Überprüfe stets, ob der Wert dem erwarteten Typ der jeweiligen Eigenschaft entspricht.
Kontext: Ein gültiger und aktiver OpenAL-Kontext muss mit openal_context_current gesetzt sein, bevor Listener-Eigenschaften geändert werden können.