openal_source_get — Funktion · PHP-Referenz

Signatur

openal_source_get(resource $source, int $property): mixed

Beschreibung

openal_source_get liest eine bestimmte Eigenschaft einer mit openal_source_create erzeugten OpenAL-Audioquelle aus. Eigenschaften steuern das Verhalten der Quelle im 3D-Audioraum, z. B. Position, Geschwindigkeit, Lautstärke oder Abspielstatus.

Der Parameter property akzeptiert eine der vordefinierten OpenAL-Konstanten wie AL_POSITION, AL_VELOCITY, AL_GAIN, AL_PITCH, AL_LOOPING oder AL_SOURCE_STATE. Je nach Eigenschaft wird ein skalarer Wert (z. B. float oder int) oder ein Array zurückgegeben (z. B. bei Positions- oder Richtungsvektoren).

Diese Funktion ist typischerweise in Spielen, Audio-Engines oder Multimedia-Anwendungen nützlich, die die PECL-Erweiterung openal verwenden, um 3D-Positionalaudio zu realisieren.

Parameter

Name	Typ	Default	Beschreibung
$source Pflicht	resource		Eine gültige OpenAL-Quellenressource, die zuvor mit `openal_source_create` erstellt wurde.
$property Pflicht	int		Die abzurufende Quelleigenschaft als OpenAL-Konstante, z. B. `AL_GAIN`, `AL_PITCH`, `AL_POSITION`, `AL_LOOPING` oder `AL_SOURCE_STATE`.

Rückgabewert

Typ

mixed

Beschreibung

Gibt den aktuellen Wert der angeforderten Eigenschaft zurück. Skalare Eigenschaften wie AL_GAIN oder AL_PITCH liefern einen float- bzw. int-Wert; Vektoreigenschaften wie AL_POSITION oder AL_VELOCITY liefern ein indiziertes Array mit drei Elementen (x, y, z). Im Fehlerfall wird false zurückgegeben.

Beispiele

Lautstärke und Position einer Audioquelle auslesen

<?php
// OpenAL-Gerät und -Kontext öffnen
$device  = openal_device_open();
$context = openal_context_create($device);
openal_context_current($context);

// Quelle erstellen und Eigenschaften setzen
$source = openal_source_create();
openal_source_set($source, AL_GAIN, 0.8);
openal_source_set($source, AL_POSITION, [1.0, 0.0, -3.0]);

// Eigenschaft auslesen
$gain     = openal_source_get($source, AL_GAIN);
$position = openal_source_get($source, AL_POSITION);

echo "Lautstärke: " . $gain . PHP_EOL;
echo "Position: x={$position[0]}, y={$position[1]}, z={$position[2]}" . PHP_EOL;

// Aufräumen
openal_source_destroy($source);
openal_context_destroy($context);
openal_device_close($device);
?>

Lautstärke: 0.8 Position: x=1, y=0, z=-3

Abspielstatus einer Quelle prüfen

<?php
$device  = openal_device_open();
$context = openal_context_create($device);
openal_context_current($context);

$source = openal_source_create();

// Buffer laden und Quelle abspielen
$buffer = openal_buffer_create();
openal_buffer_loadwav($buffer, '/pfad/zur/audiodatei.wav');
openal_source_set($source, AL_BUFFER, $buffer);
openal_source_play($source);

// Status abfragen
$state = openal_source_get($source, AL_SOURCE_STATE);
if ($state === AL_PLAYING) {
    echo "Die Quelle spielt gerade ab." . PHP_EOL;
} else {
    echo "Die Quelle ist nicht aktiv." . PHP_EOL;
}

openal_source_destroy($source);
openal_buffer_destroy($buffer);
openal_context_destroy($context);
openal_device_close($device);
?>

Die Quelle spielt gerade ab.

// Wichtig · Fallstricke

PECL-Erweiterung: openal_source_get ist Teil der PECL-Erweiterung openal, die separat installiert werden muss und in Standard-PHP-Installationen nicht enthalten ist. Sie ist zudem abhängig von der installierten OpenAL-Bibliothek des Betriebssystems.

Die Erweiterung wird kaum noch aktiv gepflegt. Für neue Projekte sollte geprüft werden, ob alternative Lösungen (z. B. externe Programme oder andere Audio-Bibliotheken) geeigneter sind.

Wird eine ungültige Quellenressource oder eine nicht unterstützte Konstantenkennung übergeben, gibt die Funktion false zurück. Eine Fehlerprüfung nach dem Aufruf ist daher empfehlenswert.

Siehe auch

openal_source_create openal_source_set openal_source_play openal_source_stop openal_source_destroy openal_buffer_create